bare-inspector

stable

bare-inspector — V8 inspector support for Bare. It is a native addon and requires Bare >=1.29.0.

Mirrors the Node.js inspector module.

npm i bare-inspector

Usage

const { Session } = require('bare-inspector')

const session = new Session()
session.connect()

try {
  const { result } = await session.post('Runtime.evaluate', {
    expression: '1 + 2'
  })

  console.log(result)
} catch (err) {
  console.error(err)
}

Heap snapshots

const { Session, HeapSnapshot } = require('bare-inspector')
const fs = require('bare-fs')

const session = new Session()
session.connect()

const snapshot = new HeapSnapshot(session)

snapshot.pipe(fs.createWriteStream('profile.heapsnapshot'))

Dispatches messages to the V8 inspector back-end and receives responses and notifications, mirroring Node's inspector.Session. onpaused is called whenever the debugger pauses; return true to keep the pause, or a falsy value to resume immediately.

Parameters

Parameter	Type	Default	Description
`onpaused?`	`() => boolean`	—	Called whenever the debugger pauses; return `true` to keep the pause, or a falsy value to resume immediately (the default resumes).

`Session.connect(): void`

_Source

Connects the session to the inspector back-end, enabling post() to send messages. A no-op if already connected or destroyed.

`Session.connected: boolean`

_Source

Whether the session is connected and not destroyed.

`Session.destroy(): void`

_Source

Destroys the session, releasing its inspector back-end handle. A no-op if already destroyed.

`Session.destroyed: boolean`

_Source

Whether the session has been destroyed.

`Session.post`

post<T extends unknown = unknown>(method: string, cb: (err: Error, result: T) => void): Promise<T>

_Source

Posts method (with optional params) to the inspector back-end. Resolves or calls cb with the result, or with an Error if the inspector returns one.

Parameters

Parameter	Type	Default	Description
`method`	`string`	—	The inspector protocol method name (e.g. `'Runtime.evaluate'`).
`cb`	`(err: Error, result: T) => void`	—	Called with the error or result; when given, no promise is returned.

Returns Promise<T> — A promise settling with the inspector's response, or undefined when cb is given.

`Session.InspectorSessionEvents`

interface InspectorSessionEvents extends EventMap {
  inspectorNotification: [message: SessionMessage]
  [method: string]: [message: SessionMessage]
}

_Source

The events a Session emits: inspectorNotification for every inspector notification, and one event per inspector protocol method name (e.g. 'Debugger.paused') carrying the same message.

`Session.SessionMessage`

interface SessionMessage {
  method: string
  params: Record<string, unknown>
}

_Source

An inspector protocol notification: the method name and its params.

Server

`new Server(opts: InspectorServerOptions)`

_Source

A WebSocket server exposing a Session for remote debugging, compatible with Chrome DevTools and mirroring the endpoints Node's --inspect exposes (/json/list and a WebSocket debugger URL).

Overloads:

new Server(opts: InspectorServerOptions)
new Server(port: number, opts: InspectorServerOptions)
new Server(port: number, host: string, opts?: InspectorServerOptions)

Parameters

Parameter	Type	Default	Description
`opts`	`InspectorServerOptions`	—	Options; `path` is the script URL reported to DevTools and defaults to `require.main.path`.

`Server.address(): TCPSocketAddress`

_Source

Returns the address the server is listening on.

`Server.close(cb?: (err?: Error | null) => void): this`

_Source

Stops the server from accepting new connections, destroys existing connections and the underlying debugger session, and calls cb once closed.

Parameters

Parameter	Type	Default	Description
`cb?`	`(err?: Error \| null) => void`	—	Called once the underlying server has closed.

`Server.listening: boolean`

_Source

Whether the server is currently listening for connections.

`Server.ref(): this`

_Source

Marks the server so the event loop won't exit while it's listening.

`Server.InspectorServerEvents`

interface InspectorServerEvents extends EventMap {
  listening: []
}

_Source

The events an inspector Server emits: listening, once the server starts listening.

`Server.InspectorServerOptions`

interface InspectorServerOptions {
  path: URL | string
}

_Source

Options for Server: path, the entry-point URL reported to DevTools as the URL of the inspected script.

`Server.unref(): this`

_Source

Unmarks the server so the event loop can exit even while it's listening.

HeapSnapshot

`new HeapSnapshot(session: Session)`

_Source

A readable stream of a V8 heap snapshot taken over session, using the inspector protocol's HeapProfiler.takeHeapSnapshot. Pipe it to a file (e.g. with a .heapsnapshot extension) to load it in Chrome DevTools.

Parameters

Parameter	Type	Default	Description
`session`	`Session`	—	The connected `Session` to take the snapshot over.

`bare-inspector/console`

InspectorConsole

`InspectorConsole.assert(condition: unknown, ...data: unknown[]): void`

_Source

Parameters

Parameter	Type	Default	Description
`condition`	`unknown`	—	The value to test; the assertion logs only when it is falsy.
`data`	`unknown[]`	—	The values to log when `condition` is falsy.

`InspectorConsole.clear(): void`

_Source

`InspectorConsole.count(label?: string): void`

_Source

Parameters

Parameter	Type	Default	Description
`label?`	`string`	—	The label of the counter.

`InspectorConsole.countReset(label?: string): void`

_Source

Parameters

Parameter	Type	Default	Description
`label?`	`string`	—	The label of the counter to reset.

`InspectorConsole.debug(...data: unknown[]): void`

_Source

Parameters

Parameter	Type	Default	Description
`data`	`unknown[]`	—	The values to log.

`InspectorConsole.dir(object: unknown, opts?: DirOptions): void`

_Source

Parameters

Parameter	Type	Default	Description
`object`	`unknown`	—	The object to inspect.
`opts?`	`DirOptions`	—	Inspection options: `colors`, `depth`, and `showHidden`.

`InspectorConsole.dirxml(...data: unknown[]): void`

_Source

Parameters

Parameter	Type	Default	Description
`data`	`unknown[]`	—	The values to log.

`InspectorConsole.error(...data: unknown[]): void`

_Source

Parameters

Parameter	Type	Default	Description
`data`	`unknown[]`	—	The values to log.

`InspectorConsole.group(...data: unknown[]): void`

_Source

Parameters

Parameter	Type	Default	Description
`data`	`unknown[]`	—	The values to log as the group heading.

`InspectorConsole.groupCollapsed(...data: unknown[]): void`

_Source

Parameters

Parameter	Type	Default	Description
`data`	`unknown[]`	—	The values to log as the group heading.

`InspectorConsole.groupEnd(): void`

_Source

`InspectorConsole.info(...data: unknown[]): void`

_Source

Parameters

Parameter	Type	Default	Description
`data`	`unknown[]`	—	The values to log.

`InspectorConsole.log(...data: unknown[]): void`

_Source

Parameters

Parameter	Type	Default	Description
`data`	`unknown[]`	—	The values to log.

`InspectorConsole.profile(label?: string): void`

_Source

Parameters

Parameter	Type	Default	Description
`label?`	`string`	—	The label of the profile.

`InspectorConsole.profileEnd(label?: string): void`

_Source

Parameters

Parameter	Type	Default	Description
`label?`	`string`	—	The label of the profile to stop.

`InspectorConsole.table(data: unknown, props?: string[]): void`

_Source

Parameters

Parameter	Type	Default	Description
`data`	`unknown`	—	The tabular data to display.
`props?`	`string[]`	—	The property names to include as columns.

`InspectorConsole.time(label?: string): void`

_Source

Parameters

Parameter	Type	Default	Description
`label?`	`string`	—	The label of the timer.

`InspectorConsole.timeEnd(label?: string): void`

_Source

Parameters

Parameter	Type	Default	Description
`label?`	`string`	—	The label of the timer to stop.

`InspectorConsole.timeLog(label?: string, ...data: unknown[]): void`

_Source

Parameters

Parameter	Type	Default	Description
`label?`	`string`	—	The label of the timer.
`data`	`unknown[]`	—	Additional values to log alongside the elapsed time.

`InspectorConsole.timeStamp(label?: string): void`

_Source

Parameters

Parameter	Type	Default	Description
`label?`	`string`	—	The label of the timestamp marker.

`InspectorConsole.trace(...data: unknown[]): void`

_Source

Parameters

Parameter	Type	Default	Description
`data`	`unknown[]`	—	The values to log with the stack trace.

`InspectorConsole.warn(...data: unknown[]): void`

_Source

Parameters

Parameter	Type	Default	Description
`data`	`unknown[]`	—	The values to log.

Types

`DirOptions`

interface DirOptions {
  colors?: number
  depth?: number
  showHidden?: boolean
}

_Source

Options for dir(): colors, depth, and showHidden, matching util.inspect()'s options of the same names.

`bare-inspector/session`

InspectorSession

`new InspectorSession(onpaused?: () => boolean)`

_Source

Parameters

Parameter	Type	Default	Description
`onpaused?`	`() => boolean`	—	Called whenever the debugger pauses; return `true` to keep the pause, or a falsy value to resume immediately (the default resumes).

`InspectorSession.connect(): void`

_Source

Connects the session to the inspector back-end, enabling post() to send messages. A no-op if already connected or destroyed.

`InspectorSession.connected: boolean`

_Source

Whether the session is connected and not destroyed.

`InspectorSession.destroy(): void`

_Source

Destroys the session, releasing its inspector back-end handle. A no-op if already destroyed.

`InspectorSession.destroyed: boolean`

_Source

Whether the session has been destroyed.

`InspectorSession.post`

post<T extends unknown = unknown>(method: string, cb: (err: Error, result: T) => void): Promise<T>

_Source

Posts method (with optional params) to the inspector back-end. Resolves or calls cb with the result, or with an Error if the inspector returns one.

Parameters

Parameter	Type	Default	Description
`method`	`string`	—	The inspector protocol method name (e.g. `'Runtime.evaluate'`).
`cb`	`(err: Error, result: T) => void`	—	Called with the error or result; when given, no promise is returned.

Returns Promise<T> — A promise settling with the inspector's response, or undefined when cb is given.

Types

`SessionMessage`

interface SessionMessage {
  method: string
  params: Record<string, unknown>
}

_Source

An inspector protocol notification: the method name and its params.

`InspectorSessionEvents`

interface InspectorSessionEvents extends EventMap {
  inspectorNotification: [message: SessionMessage]
  [method: string]: [message: SessionMessage]
}

_Source

The events a Session emits: inspectorNotification for every inspector notification, and one event per inspector protocol method name (e.g. 'Debugger.paused') carrying the same message.

`bare-inspector/server`

InspectorServer

`new InspectorServer(opts: InspectorServerOptions)`

_Source

A WebSocket server exposing a Session for remote debugging, compatible with Chrome DevTools and mirroring the endpoints Node's --inspect exposes (/json/list and a WebSocket debugger URL).

Overloads:

new InspectorServer(opts: InspectorServerOptions)
new InspectorServer(port: number, opts: InspectorServerOptions)
new InspectorServer(port: number, host: string, opts?: InspectorServerOptions)

Parameters

Parameter	Type	Default	Description
`opts`	`InspectorServerOptions`	—	Options; `path` is the script URL reported to DevTools and defaults to `require.main.path`.

`InspectorServer.address(): TCPSocketAddress`

_Source

Returns the address the server is listening on.

`InspectorServer.close(cb?: (err?: Error | null) => void): this`

_Source

Stops the server from accepting new connections, destroys existing connections and the underlying debugger session, and calls cb once closed.

Parameters

Parameter	Type	Default	Description
`cb?`	`(err?: Error \| null) => void`	—	Called once the underlying server has closed.

interface InspectorServerEvents extends EventMap {
  listening: []
}

_Source

The events an inspector Server emits: listening, once the server starts listening.

`InspectorServerOptions`

interface InspectorServerOptions {
  path: URL | string
}

_Source

Options for Server: path, the entry-point URL reported to DevTools as the URL of the inspected script.

Parameter	Type	Default	Description
`session`	`Session`	—	The connected `Session` to take the snapshot over.

bare-inspector

On this page