mod.ts - @binstruct/cli documentation

Binary Structure CLI Tool

A command-line interface for decoding and encoding binary data with any binstruct package. Binary arrives on stdin and JSON5 leaves on stdout, or the other way round, so the tool drops into a shell pipeline.

The argument list is a prefix chain, and every prefix of it is a valid invocation:

binstruct [<package> [<coder> [<command>]]] [options]

A prefix that stops short prints guidance for the missing word — what it means, the values it may take, and a paste-ready command one step further along — to stderr, and exits 1; --help prints the same material to stdout and exits 0. Stdout otherwise carries the payload and nothing else. A bare package name means the @binstruct scope on JSR, and a package exposing exactly one zero-argument coder may omit the <coder> word.

The package list shown for the missing <package> word is fetched from JSR's scope API and cached for a day, so it names what is published today rather than what was published when the CLI was released. That costs --allow-net=jsr.io; without it — or without a network — the list is omitted and everything else still works.

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.

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

Usage