lib/repl/session.ts - qunitx-cli documentation

Functions

The name a file goes into scope under when nobody says what to call it.

namespacesFor(found: readonly string[]): Map<string, string>

What each preload goes into scope as, with two that want one name pulled apart rather than left to overwrite each other.

preferredFirst(

found: readonly string[],

asked: readonly string[],

cwd: string

): string[]

The preload list with, in each group of files that want one name, the one that should keep it moved to the front.

resolvePreload(

config: Config,

inputs: readonly string[]

): Promise<string[]>

The files a qunitx repl <inputs> invocation should preload, resolved the way a run resolves its targets — directories walked, globs expanded, extensions honoured.

start(

config: Config,

preload?: string[],

onOpen?: (session: ReplSession) => void

): Promise<ReplSession>

Starts a REPL for an assembled config: bundles qunitx and the preload files, serves it, opens a page on it, and attaches to that page over CDP.

Interfaces

Breakpoint

A breakpoint the session set, numbered the way gdb numbers them.

index: number
Its number, from 1, which is what removes it again.
where: string
Where it is, as file:line in the source you wrote.

Frame

One frame of a stopped call stack.

index: number
Its place on the stack: 0 is where the page stopped, and each one after it is the caller.
selected: boolean
Whether the rest of the session is currently reading this one.
where: string
Where it is, the same way a pause names itself.

ReplResult

What one input produced. output is already rendered — the terminal prints it verbatim — and the rest is there so a caller can react rather than parse.

failed: boolean
Whether the input worked. What output never says, and what a caller needs before it can do anything but print: colour the line red, decline to add it to the replayable history, exit non-zero on a piped session.
incomplete: boolean
The input was unfinished (const a = {), so nothing ran and the terminal should read on.
output: string
The text to print, whichever way it went: the rendered value when the input worked, the error and its source-mapped stack when it did not. Empty when there is nothing to print.
pausedAt: string
Where the input stopped at a debugger statement, or absent when it ran to completion.
tests: TestDetails[]
Tests QUnit ran because of this input. Already reported through the session's reporters.
thrown: boolean
The failure was the page throwing, rather than the session refusing the input.

ReplSession

A live REPL: one browser page, kept open, that evaluates what you type.

addBreakpoint(location: string): Promise<Breakpoint | string>
Stops the page at file:line without a debugger statement in the source.
alive(): boolean
Whether there is still a page to evaluate in.
backtrace(): Frame[]
The call stack where the page is stopped, innermost first — empty when nothing is.
breakpoints(): Breakpoint[]
The breakpoints this session has set, in the order they were set.
close(): Promise<void>
Closes the page, the browser and the server. Idempotent.
completions(base: string): Promise<string[]>
What could come next after base: its own properties, or everything in scope at top level when base is ''.
continue(): Promise<void>
Lets a paused page carry on. A no-op when it is not paused.
declaredAt(expression: string): Promise<{ file: string; line: number; } | null>
Where a value was written — the file and line of its declaration, or null for one that has no source: a value typed at this prompt, or anything that is not a function.
eval(
input: string,
options?: { whole?: boolean; }
): Promise<ReplResult>
Evaluates one input in the page and resolves with what to print.
frameSource(): Promise<{ text: string; line: number; } | null>
The source the breakpoint is in and the line it stopped on, or null when nothing is stopped.
import(
file: string,
callItThis?: string
): Promise<{ name: string; names: string[]; } | string>
Brings a file into the page after the fact, the way the command line brings one in before it.
imported(): Promise<
Array<
{ file: string; exports: Array<{ name: string; capture: string; }>; }
>
>
What each preloaded file put in scope, and what kind of thing each one is.
inspector: string | null
Where to open Chrome's DevTools on the page this session is evaluating in — the same realm, the same DOM, the same paused frame. null where this browser has none to serve them from.
interrupt(): Promise<void>
Stops whatever is executing in the page — the Ctrl-C of a runaway expression.
loaded: Array<[string, string[]]>
[file, exported names] per preloaded module — what the terminal lists on start-up.
locals(): Promise<ScopeEntry[]>
What is in scope at the breakpoint, innermost first, or empty when the page is not paused. .locals, and the frame it reads is whichever ReplSession.selectFrame last chose.
pausedAt: string | null
Where the page is stopped at a debugger statement, or null when it is running.
preview(
input: string,
depth?: number
): Promise<string>
What the input WOULD evaluate to, or '' where it cannot be known without doing something.
refresh(file: string): Promise<string[] | string | null>
Loads a file again the way it was loaded the first time, for one that has changed on disk.
reload(): Promise<string[]>
Reloads the page and brings the modules back, resolving with the names that returned.
removeBreakpoint(index: number): Promise<boolean>
Removes one by its number. false where there is no such breakpoint.
scope(): Promise<ScopeEntry[]>
What this session has added to the page's globals — not the several hundred a browser starts with, which is a list nobody reads. .scope.
selectFrame(index: number): string | null
Reads the rest of the session in another frame of that stack, and says where it now is.
settled(): Promise<void>
Resolves once nothing is in flight — a no-op at the back of the evaluation queue.
step(kind: StepKind): Promise<string | null>
Runs one step and stops again, reporting where — or null if the page did not stop.
toJSON(expression: string): Promise<string | null>
What an expression is worth in the page, as JSON — null where the page cannot say.
typeOf(expression: string): Promise<string>
What TypeScript would call the value an expression comes to — structural, from the value.
url: string
Where the PAGE is served, e.g. http://localhost:1234 — the application, as a browser sees it.
whenPaused(listener: (where: string) => void): void
Called when the page stops with nothing waiting on it — a breakpoint reached by a timer, or by anything else the prompt did not start.
whereFrom(name: string): string | null
Where a name came into this session from — the file it was imported from, or the input that declared it. null for a name the page already had, and for anything that is not a bare name.