Skip to content

Latest commit

 

History

History
248 lines (160 loc) · 11.2 KB

API.md

File metadata and controls

248 lines (160 loc) · 11.2 KB

API Documentation

English | 简体中文

debug

Debug scripts. Two arguments accepted, which are script code string script and script debug id debuggerId, respectively.

The script can be not only the source code, but also the transformed result generated by the transform method. And the debuggerId is the script url normally. If missing debuggerId, the debugging script will be treated as a temporary script, and a random debuggerId will be generated.

This method returns an execution function called run, for code real execution. Therefore, before run calls, you can use other APIs like setBreakpoint to modify breakpoints. If inputed arguments is invalid, or current environment doesn't support debug, this method returns false.

function debug(script: string, debuggerId?: string): (() => void) | false

transform

Transform scripts. Two arguments accepted, which are script code string script and script debug id debuggerId, respectively.

The debuggerId is the script url normally. If missing debuggerId, the debugging script will be treated as a temporary script, and a random debuggerId will be generated.

This method returns a code transformed result, which can be passed to the debug method for debugging scripts at runtime. If inputed arguments is invalid, this method returns false.

function transform(script: string, debuggerId?: string): string | false

resume

Resume execution when paused by hitting breakpoints. One optional argument accepted, which can be stepInto, stepOver or stepOut:

  1. Continue executing by default if missing.
  2. Step into child process if passing stepInto.
  3. Step over child process if passing stepOver.
  4. Step out to parent process if passing stepOut.

This method returns a boolean value to inform whether resume succeeds.

function resume(type?: ResumeType): boolean

type ResumeType = 'stepInto' | 'stepOver' | 'stepOut'

evaluate

Evaluate expressions in specific scopes. Two arguments accepted, which are expression code string expression and call frame id callFrameId, respectively.

The callFrameId is optional, which can be achieved from the scopeChain of paused info, by getPausedInfo method or paused event. If callFrameId inputed, the expression will be evaluated in the corresponding scope. Or, if callFrameId missed, the expression will be evaluated in the global scope.

function evaluate<Result = unknown>(expression: string, callFrameId?: number): Result | false

getPossibleBreakpoints

Get all possible breakpoints of a script. One script debug id argument accepted.

If get succeeds, this method returns an array of all possible breakpoint info, including breakpoint id id, exact break line number lineNumber (1-based) and exact break column number columnNumber (0-based) of all breakpoints. Or, if get fails, this method returns false.

function getPossibleBreakpoints(debuggerId: string): Breakpoint[] | false

interface Breakpoint { id: number, lineNumber: number, columnNumber: number }

setBreakpoint

Set breakpoints by script debug id, including 2 overloads:

  1. Three arguments accepted, which are script debug id debuggerId, line number lineNumber (1-based) and optional break condition condition, respectively.
  2. Four arguments accepted, which are script debug id debuggerId, line number lineNumber (1-based), column number columnNumber (0-based) and optional break condition condition, respectively.

Besides, the condition is an expression string, and execution will be paused if the evaluation returns true. If condition missed, execution will be paused when hitting the corresponding position by default.

If set succeeds, this method returns the breakpoint info, including breakpoint id id, exact break line number lineNumber (1-based) and exact break column number columnNumber (0-based). Or, if set fails, this method returns false.

function setBreakpoint(debuggerId: string, lineNumber: number, condition?: string): Breakpoint | false
function setBreakpoint(debuggerId: string, lineNumber: number, columnNumber: number, condition?: string): Breakpoint | false

interface Breakpoint { id: number, lineNumber: number, columnNumber: number }

removeBreakpoint

Remove breakpoint by breakpoint id. One breakpoint id argument accepted.

This method returns a boolean value to inform whether remove succeeds.

function removeBreakpoint(id: number): boolean

setBreakpointsActive

Set whether all breakpoints are active. One boolean argument accepted.

This method returns a boolean value to inform whether breakpoints are active.

function setBreakpointsActive(value: boolean): boolean

setExecutionPause

Set whether execution pauses. One boolean argument accepted.

This method returns a boolean value to inform whether execution will pause. If the return is true, execution will pause at the next coming step.

function setExecutionPause(value: boolean): boolean

setExceptionPause

Set whether execution pauses when exception. One boolean argument accepted.

This method returns a boolean value to inform whether execution will pause when exception. If the return is true, execution will pause right before the exception thro

function setExceptionPause(value: boolean): boolean

getPausedInfo

Get paused info when execution paused.

When execution paused, This method returns debuger id debuggerId, breakpoint id breakpointId, line number lineNumber (1-based), column number columnNumber (0-based), scope chain scopeChain and script source content scriptContent. If execution doesn't pause, this method returns false.

The scopeChain includes the global scope, function scopes and block scopes, and you can check if the callFrame field exists to determine whether the scope is the global scope or function scope. The call stack can be generated by filtering all scopes with the callFrame field.

Also, the callFrame contains a callFrameId which can be passed to the evaluate method for evaluating expressions in specific scopes.

function getPausedInfo(): PausedInfo | false

interface PausedInfo { breakpointId?: number, reason?: string, data?: any, debuggerId: string, lineNumber: number, columnNumber: number, scopeChain: Scope[], scriptContent: string }
interface Scope { eval: (expression: string) => any, name: string, callFrameId: number, callFrame?: CallFrame }
interface CallFrame { debuggerId: string, lineNumber: number, columnNumber: number }

getScopeChain

Get current scope chain.

function getScopeChain(): Scope[]

interface Scope { eval: (expression: string) => any, name: string, callFrameId: number, callFrame?: CallFrame }
interface CallFrame { debuggerId: string, lineNumber: number, columnNumber: number }

getScriptContent

Get script source content by debugger id debuggerId.

function getScriptContent(debuggerId: string): string

runInNativeEnv

Run callbacks in the native environment, like browser or node.js. One argument accepted, which is the callback function that need to run.

The debug method executes scripts in a internal sandbox, so this method is used to run callbacks in the native host environment.

If run succeeds, this method returns the callback return. Or, if run fails, this method returns false.

function runInNativeEnv(callback: () => Return): Return | false

runInSkipOver

Run callbacks with skipping over all breakpoints. One argument accepted, which is the callback function that need to run.

When paused by hitting breakpoints, if you call some functions of debugging scripts in the internal sandbox, they will be blocked until resume. So, this method is generally used to call the functions in the sandbox continuously by evaluate method, in order to get variables or returns in the corresponding scope.

If run succeeds, this method returns the callback return. Or, if run fails, this method returns false.

function runInSkipOver(callback: () => Return): Return | false

setModuleRequest

Set the request function of modules. One argument accepted, which is the custom request function that need to override the internal default request function.

When a module requests other modules, fetch is used for request by default. If fetch isn't supported, or you want to customize the behavior of module request like caching module response, you can use this method to set the request function of modules.

The request function requires a module url importUrl as input, and is requested to return a module script wrapped by Promise<string>. Also, the module script can be not only the source code, but also the transformed result generated by the transform method.

This method returns a boolean value to inform whether set succeeds.

function setModuleRequest(request: (importUrl: string) => Promise<string>): boolean

addEventListener / removeEventListener

Add or remove event listeners. Two arguments accepted, which are event and callback function listener, respectively.

Currently we have four events, which are paused, resumed, error and sandboxchange:

  1. Paused event paused emits when break, and returns paused info which is the same as the return of getPausedInfo method.
  2. Resumed event resumed emits when resume, and has no returns.
  3. Error event error emits when an error occurred, and returns error info, including reasons and the scope chain.
  4. Sandbox status change event sandboxchange emits when sandbox environment switched, and returns sandbox info, including whether sandbox enabled.

This method returns a boolean value to inform whether adding or removing listeners succeeds.

function addEventListener<Event extends keyof EventListener>(event: Event, listener: EventListener[Event]): boolean
function removeEventListener<Event extends keyof EventListener>(event: Event, listener: EventListener[Event]): boolean

interface EventListener {
  resumed: () => void,
  paused: (pausedInfo: PausedInfo) => void,
  error: (errorInfo: ErrorInfo) => void,
  sandboxchange: (sandboxInfo: SandboxInfo) => void,
}
interface PausedInfo { breakpointId?: number, reason?: string, data?: any, debuggerId: string, lineNumber: number, columnNumber: number, scopeChain: Scope[], scriptContent: string }
interface ErrorInfo { error: Error, scopeChain: Scope[] }
interface SandboxInfo { enable: boolean }
interface Scope { eval: (expression: string) => any, name: string, callFrameId: number, callFrame?: CallFrame }
interface CallFrame { debuggerId: string, lineNumber: number, columnNumber: number }