rhythmjs

Search documentation

Search guides, the tutorial and every package.

On this page

Rhythm#

new Rhythm<S, I, D>(options?)#
Create a pipeline. S is the startup context, I the input the caller supplies on each call, D the fields added by derive. All three are normally inferred as you chain; only I is sometimes written by hand. Options are name and type (default "module"), used to label errors.
register(callback, cleanup?)#
Startup step. Calls callback(ctx, app) with the shared startup context, right away unless an earlier register is still pending; then it runs once that one settles, so it sees what earlier async registrations added. A returned promise is awaited before the first call, and a failed registration skips the later ones. cleanup(ctx, app) runs on stop(). Passing decorate() or include() extends the startup type.
use(middleware)#
Request step. Takes (ctx, next) => unknown. Passing derive() extends the request type; passing mount() widens the input type.
callback()#
Get the reusable (input?) => ctx | Promise<ctx> handler for the middleware registered so far. The input is required when I has required fields. Every call gets a fresh context that inherits the startup context through its prototype, with the input's fields copied on top, so request-time writes never reach the startup context. The result is the context itself when every middleware is synchronous and a promise otherwise (or while startup is still pending), so always await it; failures reject and never throw.
stop()#
Run the registered cleanups in reverse order. If several throw, all still run and stop() rejects with an AggregateError. Rhythm is also AsyncDisposable.
sources#
Read-only list of the plugins (routers, clis, anything tagged) the pipeline was built from, in order, with Rhythm modules expanded in place. Read it lazily, once the app is assembled.
parent#
The pipeline this one was adopted by through mount() or include(). Undefined for a root.
options#
The name and type the pipeline was created with.

Composables#

decorate(fn)#
Goes in register. Merges the object fn(ctx) returns (sync or async) into the startup context and types it for everything after.
derive(fn)#
Goes in use, or as the first handler of a route. Merges the object fn(ctx) returns (sync or async) into the request context, then calls next().
mount(plugin, condition?)#
Goes in use. Runs another pipeline (a Rhythm, router, ws, cron or cli) against the current context, then always calls next(). The host's input type is widened to cover what the plugin needs. With condition(ctx), the plugin runs only when it returns true. Failures are wrapped with the plugin's name and type; the original is the cause.
include(module, pick?)#
Goes in register. Runs a Rhythm module once with the parent's startup context as input, registers its stop() as a parent cleanup, and copies pick(child) into the parent's startup context. Failures are wrapped as included module "name" failed.

Pipeline and helpers#

Pipeline#
The abstract base shared by Rhythm, RhythmRouter, RhythmWs, RhythmCron and RhythmCli: use(), callback(), sources, parent and options. Extend it to build your own plugin.
compose(middleware[])#
Return a dispatcher accepting a context and an optional final next handler. The onion every pipeline is built on.
withSource(fn, source)#
Tag a middleware or register callback with the object it was built from and return it. use() and register() record the tag in sources.
sourceOf(fn)#
Read the tag back, or undefined for an untagged function.

Types#

From @rhythmjs/rhythm/types, re-exported by the root.

Middleware<T>#
A (ctx, next) function returning anything or a promise.
ExtensionMiddleware<T, U>#
A middleware that adds the fields U to the context, as returned by derive().
ExtensionRegister<T, U>#
A register callback that adds the fields U to the startup context, as returned by decorate() and include().
Mountable<I>#
Anything with a callback() that mount() and the serving helpers accept; I is the input it needs.
PipelineOptions#
Optional name and type labels.

Each function also has its own entry point (@rhythmjs/rhythm/derive, /decorate, /mount, /include, /compose, /pipeline, /source, /types); the root export re-exports them all.