Core@rhythmjs/rhythm
Core API reference
The public API and types exported by @rhythmjs/rhythm.
On this page
Rhythm#
new Rhythm<S, I, D>(options?)#- Create a pipeline.
Sis the startup context,Ithe input the caller supplies on each call,Dthe fields added byderive. All three are normally inferred as you chain; onlyIis sometimes written by hand. Options arenameandtype(default"module"), used to label errors. register(callback, cleanup?)#- Startup step. Calls
callback(ctx, app)with the shared startup context, right away unless an earlierregisteris 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 onstop(). Passingdecorate()orinclude()extends the startup type. use(middleware)#- Request step. Takes
(ctx, next) => unknown. Passingderive()extends the request type; passingmount()widens the input type. callback()#- Get the reusable
(input?) => ctx | Promise<ctx>handler for the middleware registered so far. The input is required whenIhas 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 alwaysawaitit; failures reject and never throw. stop()#- Run the registered cleanups in reverse order. If several throw, all still run and
stop()rejects with anAggregateError.Rhythmis alsoAsyncDisposable. sources#- Read-only list of the plugins (routers, clis, anything tagged) the pipeline was built from, in order, with
Rhythmmodules expanded in place. Read it lazily, once the app is assembled. parent#- The pipeline this one was adopted by through
mount()orinclude(). Undefined for a root. options#- The
nameandtypethe pipeline was created with.
Composables#
decorate(fn)#- Goes in
register. Merges the objectfn(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 objectfn(ctx)returns (sync or async) into the request context, then callsnext(). mount(plugin, condition?)#- Goes in
use. Runs another pipeline (aRhythm, router, ws, cron or cli) against the current context, then always callsnext(). The host's input type is widened to cover what the plugin needs. Withcondition(ctx), the plugin runs only when it returns true. Failures are wrapped with the plugin's name and type; the original is thecause. include(module, pick?)#- Goes in
register. Runs aRhythmmodule once with the parent's startup context as input, registers itsstop()as a parent cleanup, and copiespick(child)into the parent's startup context. Failures are wrapped asincluded module "name" failed.
Pipeline and helpers#
Pipeline#- The abstract base shared by
Rhythm,RhythmRouter,RhythmWs,RhythmCronandRhythmCli:use(),callback(),sources,parentandoptions. 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()andregister()record the tag insources. sourceOf(fn)#- Read the tag back, or undefined for an untagged function.
Types#
From @rhythmjs/rhythm/types, re-exported by the root.
Next#() => void | Promise<void>. Continue to the next step; it takes no arguments. It returns nothing when the rest of the chain is synchronous, soawaitit (or wrap it inPromise.resolve) rather than chaining.then.Middleware<T>#- A
(ctx, next)function returning anything or a promise. ExtensionMiddleware<T, U>#- A middleware that adds the fields
Uto the context, as returned byderive(). ExtensionRegister<T, U>#- A register callback that adds the fields
Uto the startup context, as returned bydecorate()andinclude(). Mountable<I>#- Anything with a
callback()thatmount()and the serving helpers accept;Iis the input it needs. PipelineOptions#- Optional
nameandtypelabels.
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.