All Symbols - @binstruct/cli documentation

mod.ts

Binary Structure CLI Tool

Examples

Decode with the full three-word form

deno run -A @binstruct/cli png pngFile decode < input.png > struct.json5

Encode it back

deno run -A @binstruct/cli png pngFile encode < struct.json5 > output.png

Omit the coder when the package has only one

deno run -A @binstruct/cli arp decode < arp.bin > arp.json5

A local module works the same way, relative to the working directory

deno run -A @binstruct/cli ./my-package/mod.ts myStruct decode < input.bin > output.json5

Programmatic usage: plan an invocation without performing it

import { assertEquals } from "@std/assert";
import { planCli } from "@binstruct/cli";

const plan = await planCli(["png", "pngFile", "decode"]);

assertEquals(plan.kind, "run");
if (plan.kind === "run") assertEquals(plan.specifier, "jsr:@binstruct/png");

Functions

diagnoseEmptyDiscovery(

specifier: string,

timeout?: number

): Promise<EmptyDiscoveryDiagnosis>

Explains why a package yielded no coders, by reading its module graph.

discoverCoders(

specifier: string,

timeout?: number

): Promise<DiscoveryOutcome>

Discovers the coder factories a package exposes, without importing it.

explainFailure(

packageInput: string,

coderName: string,

error: unknown

): Promise<string>

Explains a failure that only surfaced once the package was imported.

inspectLocalTarget(specifier: string): Promise<LocalTarget>

Reports what a resolved specifier points at, before anything is run on it.

isModulePath(name: string): boolean

Reports whether a name ends in an extension the runtime will load.

listScopePackages(options?: ScopeListingOptions): Promise<ScopeListing>

Lists the packages of the @binstruct scope, live from JSR.

main(args?: string[]): Promise<void>

Main CLI entry point.

nearestName(

input: string,

candidates: Iterable<string>

): string | undefined

Picks the candidate closest to a misspelling, for a "did you mean" line.

parseCliArgs(args: string[]): CliOptions

Parses command line arguments into the three positionals and the flags.

planCli(args: string[]): Promise<CliPlan>

Works out what an invocation amounts to, without performing it.

readDocSurface(doc: DenoDocJson): PackageSurface

Reads a package's discoverable surface out of parsed deno doc --json output.

readScopeListing(body: unknown): ScopePackage[] | undefined

Reads a package listing out of a parsed JSR scope-packages response.

readSymbolDocs(

specifier: string,

symbol: string,

timeout?: number

): Promise<SymbolDocsOutcome>

Returns deno doc's formatted documentation for one exported symbol.

renderGuide(guide: Guide): string

Renders a guidance screen.

resolveSpecifier(input: string): ResolvedSpecifier

Resolves a user-typed package argument to a module specifier.

shortenSpecifier(specifier: string): string

Renders the shortest form of a specifier that still resolves back to it.

Interfaces

CliOptions

CLI configuration options.

blankSlots: readonly string[]
Slots filled with a word that says nothing, named as <package> and so on.
coder: string | undefined
Coder name, absent when it is to be inferred or asked for.
command: string | undefined
Command word, absent when it is to be asked for.
docs: boolean
Print deno doc output for the chosen coder instead of running it.
extraArgs: readonly string[]
Positionals beyond the third, as typed.
help: boolean
Print guidance to stdout and exit 0 instead of to stderr and exit 1.
package: string | undefined
Package specifier as typed, before resolveSpecifier.
unknownFlags: readonly string[]
Flags the parser was given and does not know, as typed.
version: boolean
Print version information.

ResolvedSpecifier

A user-typed package argument and everything derived from it.

form: SpecifierForm
The resolution rule that matched.
input: string
The argument exactly as the user typed it.
short: string
The shortest form that resolves back to ResolvedSpecifier.specifier, for listings and TRY lines. Equal to shortenSpecifier(specifier), except for a path, where it is the input itself — a path is anchored to the working directory the CLI was started in, and only the typed form still says so.
shorthand: boolean
Whether the input was shorthand, and therefore expanded.
specifier: string
The module specifier to hand to deno doc.

Type Aliases

CliPlan =

{ readonly kind: "print"; readonly text: string; readonly stream: "stdout" | "stderr"; readonly code: number; readonly notices?: readonly string[]; }
| { readonly kind: "run"; readonly specifier: string; readonly coder: string; readonly command: CommandName; readonly arityVerified: boolean; readonly notices: readonly string[]; }

What an invocation amounts to, once its arguments are understood.

CommandName = (COMMANDS)[number]["name"]

A command the CLI can carry out.

DenoDocDeclaration = { kind: string; location: { filename: string; }; jsDoc?: { doc?: string; }; def: { params?: DenoDocParam[]; returnType?: DenoDocType; }; }

A single declaration of an exported symbol in deno doc --json output.

def: { params?: DenoDocParam[]; returnType?: DenoDocType; }
Kind-specific detail; for functions, the signature.
jsDoc: { doc?: string; }
The declaration's JSDoc, when it has one.
kind: string
Declaration kind, e.g. function, variable, interface.
location: { filename: string; }
Where the declaration lives; the version rides along for JSR specifiers.

DenoDocJson = { nodes: Record<string, DenoDocNode>; }

The deno doc --json document, narrowed to the parts discovery reads.

nodes: Record<string, DenoDocNode>
One entry per documented module, keyed by the module's own URL.

DenoDocNode = { module_doc?: { doc?: string; }; symbols: DenoDocSymbol[]; }

A module entry in deno doc --json output.

module_doc: { doc?: string; }
The @module JSDoc of the documented module.
symbols: DenoDocSymbol[]
Every exported symbol, in declaration order.

DenoDocParam = { kind: string; optional?: boolean; }

A parameter of a declaration in deno doc --json output.

kind: string
Binding form: identifier, assign, rest, object or array.
optional: boolean
Whether the parameter was declared with a trailing ?.

DenoDocSymbol = { name: string; declarations: DenoDocDeclaration[]; }

An exported symbol in deno doc --json output.

declarations: DenoDocDeclaration[]
One entry per declaration, e.g. one per overload.
name: string
The exported name.

DenoDocType = { repr?: string; value?: { typeParams?: DenoDocType[]; }; }

A type reference in deno doc --json output.

repr: string
Rendered type name, e.g. Coder. Absent for anonymous forms like unions.
value: { typeParams?: DenoDocType[]; }
Resolved details, including the type arguments of a generic reference.

DiscoveredCoder = { name: string; decodedType?: string; summary?: string; requiredParams: number; }

A coder factory found in a package's public types.

decodedType: string
The T of Coder<T>, absent when it is an anonymous type such as a union.
name: string
The exported name, e.g. pngFile.
requiredParams: number
Arguments the caller must supply; 0 means the CLI can call it directly.
summary: string
First line of the factory's JSDoc, absent when it is undocumented.

DiscoveryOutcome = DiscoverySuccess | ToolFailure

The result of discoverCoders.

DiscoverySuccess = PackageSurface & { ok: true; specifier: string; }

A package whose type declarations were read successfully.

EmptyDiscoveryDiagnosis =

{ ok: true; specifier: string; dependsOnBinstruct: boolean; }
| ToolFailure

The result of diagnoseEmptyDiscovery.

Guide = { readonly header?: string; readonly diagnostic?: boolean; readonly notes?: readonly string[]; readonly next: GuideNext; readonly options: GuideOptions; readonly try?: readonly string[]; readonly footer?: readonly string[]; }

Everything one guidance screen says.

diagnostic: boolean
Whether the screen reports a failure rather than disclosing the next word.
footer: readonly string[]
Trailing lines, e.g. the usage recap --help adds.
header: string
First line, echoing the resolved specifier so shorthand is never invisible.
next: GuideNext
The missing word.
notes: readonly string[]
Lines shown before NEXT: what went wrong, or what was inferred.
options: GuideOptions
The values that word may take.
try: readonly string[]
Paste-ready commands one step further along.

GuideNext = { readonly word: string; readonly meaning: string; }

The missing word and what it means.

meaning: string
One line on what the word selects.
word: string
The word, written as it appears in the usage line, e.g. <coder>.

GuideOption = { readonly name: string; readonly detail?: string; readonly summary?: string; }

One legal value of the missing word.

detail: string
Short annotation shown in its own column, e.g. → PngFile.
name: string
The word to type, e.g. png, pngFile or decode.
summary: string
One-line description, e.g. the first line of the coder's JSDoc.

GuideOptions = { readonly heading: string; readonly items: readonly GuideOption[]; readonly empty?: string; }

The options block: every value the missing word may take.

empty: string
Line shown in place of an empty list, e.g. why discovery found nothing.
heading: string
Block heading, e.g. PACKAGES or CODERS in png.
items: readonly GuideOption[]
The legal values, in the order they should be shown.

ListingSource = "network" | "cache" | "stale-cache" | "none"

Where the packages of a ScopeListing came from.

LocalTarget =

{ readonly kind: "elsewhere"; }
| { readonly kind: "module"; }
| { readonly kind: "directory"; readonly modules: readonly string[]; }
| { readonly kind: "missing"; }
| { readonly kind: "unreadable"; readonly reason: string; }

What sits at the far end of a resolved specifier.

PackageSurface = { version?: string; summary?: string; coders: DiscoveredCoder[]; }

The public surface of a package as read from its type declarations.

coders: DiscoveredCoder[]
Coder factories, zero-required-parameter ones first.
summary: string
First line of the module JSDoc, absent when the module is undocumented.
version: string
Resolved version, when the specifier resolved to a JSR package.

ScopeListing = { readonly packages: readonly ScopePackage[]; readonly source: ListingSource; readonly reason?: string; }

The result of listScopePackages.

packages: readonly ScopePackage[]
The scope's published packages, sorted by name, without @binstruct/cli.
reason: string
Why the network answer is missing, when it is.
source: ListingSource
Where they came from.

ScopeListingOptions = { readonly cacheDir?: string | null; readonly now?: number; readonly ttl?: number; }

Options for listScopePackages.

cacheDir: string | null
Directory holding the cache file. Absent means the OS cache directory; null disables the cache in both directions.
now: number
Current time in milliseconds, for ageing the cache.
ttl: number
How long a cached listing is served before a refetch, in milliseconds.

ScopePackage = { readonly name: string; readonly description: string; readonly latestVersion: string; }

One published package of the scope, as JSR describes it.

description: string
JSR's one-paragraph description, empty when the package has none.
latestVersion: string
The version a bare jsr:@binstruct/<name> resolves to today.
name: string
Short name, e.g. png; prefix @binstruct/ for the JSR coordinate.

SpecifierForm = "scheme" | "path" | "scoped" | "bare"

Which resolution rule matched an input.

SymbolDocsOutcome = { ok: true; text: string; } | ToolFailure

The result of readSymbolDocs.

ToolFailure = { ok: false; reason: ToolFailureReason; specifier: string; command: string[]; code?: number; stderr: string; }

A deno subprocess that did not produce usable output.

code: number
Exit status, absent when the process never started.
command: string[]
The argument vector, for a reproducible line in an error message.
ok: false
Discriminant: this outcome carries no result.
reason: ToolFailureReason
Which environmental condition stopped the tool.
specifier: string
The specifier discovery was asked about.
stderr: string
The subprocess's stderr, or the message of the error that replaced it.

ToolFailureReason =

Why a deno subprocess spawned by discovery produced no usable output.

cli.ts

Binary Structure CLI Tool

Examples

Decode a PNG file

binstruct png pngFile decode < input.png > struct.json5

The coder word is optional when a package has only one

binstruct arp decode < arp.bin > arp.json5

A local package is named by its module file, never by its directory

binstruct ./my-package/mod.ts decode < input.bin > output.json5

`--` ends the flags, for a package word that starts with one

binstruct -- -dash/mod.ts decode < input.bin > output.json5

Functions

explainFailure(

packageInput: string,

coderName: string,

error: unknown

): Promise<string>

Explains a failure that only surfaced once the package was imported.

main(args?: string[]): Promise<void>

Main CLI entry point.

parseCliArgs(args: string[]): CliOptions

Parses command line arguments into the three positionals and the flags.

planCli(args: string[]): Promise<CliPlan>

Works out what an invocation amounts to, without performing it.

Interfaces

CliOptions

CLI configuration options.

blankSlots: readonly string[]
Slots filled with a word that says nothing, named as <package> and so on.
coder: string | undefined
Coder name, absent when it is to be inferred or asked for.
command: string | undefined
Command word, absent when it is to be asked for.
docs: boolean
Print deno doc output for the chosen coder instead of running it.
extraArgs: readonly string[]
Positionals beyond the third, as typed.
help: boolean
Print guidance to stdout and exit 0 instead of to stderr and exit 1.
package: string | undefined
Package specifier as typed, before resolveSpecifier.
unknownFlags: readonly string[]
Flags the parser was given and does not know, as typed.
version: boolean
Print version information.

Type Aliases

CliPlan =

What an invocation amounts to, once its arguments are understood.

CommandName = (COMMANDS)[number]["name"]

A command the CLI can carry out.

Examples

Decode with the full three-word form

Encode it back

Omit the coder when the package has only one

A local module works the same way, relative to the working directory

Programmatic usage: plan an invocation without performing it

Functions

Interfaces

Type Aliases

Examples

Decode a PNG file

The coder word is optional when a package has only one

A local package is named by its module file, never by its directory

-- ends the flags, for a package word that starts with one

Functions

Interfaces

Type Aliases

`--` ends the flags, for a package word that starts with one