bare-stow

bare-stow — Module bundling and harness generation for Bare.

npm i bare-stow

Usage

Given an entry module core.js that exports a start function receiving the IPC stream and an optional ready callback. The function may optionally return (or resolve to) a function that runs before the bundle exits:

module.exports = async function start(ipc, ready) {
  ipc.on('data', (data) => {
    // Handle messages from the host.
  })

  // Optionally call `ready()` to signal readiness early. Otherwise it is
  // signaled automatically when `start()` resolves.
  ready()

  return async function stop() {
    // Clean up before the bundle exits.
  }
}

The ipc argument is a duplex byte stream. Anything written to it is delivered to the host, and 'data' events fire when the host writes back.

Stow it for the bare-sidecar target:

const stow = require('bare-stow')

const entry = new URL('file:///app/core.js')
const out = new URL('file:///app/out/index.js')

for await (const artifact of stow(entry, 'bare-sidecar', out)) {
  console.log(artifact.url.href)
}

Or equivalently from the command line:

$ bare-stow --target bare-sidecar --out ./out/index.js ./core.js

This writes the harness to out and the bundle alongside it. The harness can then be required from the host and booted with start(). The harness awaits the worker's ready signal before resolving, so by the time start() returns the bundle is up:

const harness = require('/app/out/index.js')

const { ipc } = await harness.start()

ipc.write(Buffer.from('hello from the host'))

ipc.on('exit', (code) => {
  console.log('bundle exited with', code)
})

// Request a graceful shutdown.
ipc.destroy()

API

Functions

stow

stow(entry: URL | string, target: Target | TargetName, out: URL | string, opts?: StowOptions): AsyncGenerator<StowArtifact>

Bundle the module graph rooted at entry for target, writing a harness plus bundle to out.

Parameters

Returns AsyncGenerator<StowArtifact> — An async generator that yields each written artifact's url as it is produced — the harness first, then the bundle, then any offloaded addon or asset files.

Throws

• The target argument is missing.
• The out argument is missing.
• A host in opts.hosts is not supported by the resolved target.

Types

Target

interface Target {
  name: string
  linked: boolean
  offload: boolean | { addons?: boolean; assets?: boolean }
  format: 'bundle' | 'bundle.cjs' | 'bundle.mjs' | 'bundle.json'
  encoding: string | null
  extension: string
  module?: 'esm' | 'cjs'
  hosts: string[]
  generate(context: TargetContext): Artifact[]
}

A bundling target, such as bare-sidecar or bare-worker, describing how to package and boot a bundle on a given host runtime.

TargetContext

interface TargetContext {
  bundleSpecifier: string
  ipc: string
  rpc: string
  module: 'esm' | 'cjs'
  client: RPCClient | null
}

The context passed to a target's generate(), describing the bundle to embed and the RPC wiring to splice in.

RPC

interface RPC {
  name: string
  generate(context: RPCContext): Artifact[]
}

An RPC library adapter that generates the wiring code spliced into a stowed bundle's harness or entry shim.

RPCContext

interface RPCContext {
  ipc: string
  rpc: string
  module: 'esm' | 'cjs'
  role: 'client' | 'server'
}

The context passed to an RPC adapter's generate().

RPCClient

interface RPCClient {
  source: string
  type: string
}

The resolved client RPC wiring, carrying both the runtime source to splice into the harness and the type declaration to splice into the harness's .d.ts.

Artifact

interface Artifact {
  extension?: string
  source: string
}

A single generated source artifact, such as a harness or a type declaration.

StowOptions

interface StowOptions extends Omit<PackOptions, 'offload' | 'linked' | 'resolve' | 'aliases'> {
  client?: RPC | RPCName
  server?: RPC | RPCName
  resolveTarget?(name: string): Target
  resolveRPC?(name: string): RPC
}

Options for stow().

StowArtifact

interface StowArtifact {
  url: URL
}

An artifact written by stow(), yielded once its file has been written.

bare-stow/protocol

Protocol

new Protocol(stream: Duplex)

Attach a Protocol to the given underlying duplex byte stream.

Parameters

send(type: string, payload?: object): Promise<void>

Send a control frame of type with an optional JSON-serializable payload.

Parameters

Functions

attach(stream: Duplex): Protocol

Attach a Protocol to stream, an underlying duplex byte stream.

Parameters

Returns Protocol — A Protocol multiplexing control and user-data frames over stream.

Constants and variables

CONTROL: number

The frame type marker identifying a control-channel frame.

USER: number

The frame type marker identifying a user-data-channel frame.

Types

ProtocolEvents

interface ProtocolEvents extends DuplexEvents {
  ready: []
  terminate: []
  exit: [code: number]
}

The events emitted by a Protocol, in addition to the standard duplex stream events.

bare-stow/host

IPC

new IPC(stream: Duplex)

Wrap the host side of a stowed bundle's transport stream.

Parameters

ready: Promise<void>

A promise that resolves once the worker has signaled ready, and rejects if the worker errors before then.

terminate(): Promise<number | undefined>

Send a terminate control frame to the worker and resolve with its exit code once it exits.

Returns Promise<number | undefined> — The worker's exit code once it exits.

Functions

wrap(stream: Duplex): IPC

Wrap the host side of a stowed bundle's transport stream, returning an IPC handle with lifecycle helpers layered on top of the Protocol.

Parameters

Returns IPC — An IPC handle wrapping stream, with the ready promise and terminate() layered on top of Protocol.

See also

• Bare modules — the full bare-* catalog.
• Bare runtime API — the runtime these modules extend.