@rhythmjs/rhythm 0.0.16 → 0.0.17

package/README.md

@@ -1,92 +1,130 @@
 # @rhythmjs/rhythm
 
-The composition kernel at the core of Rhythm, the Bun-native backend framework, the piece `@rhythmjs/router` and `@rhythmjs/cli` are built on. It gives an application its structure (onion middleware, startup-time context, encapsulated modules, all checked at compile time) and deliberately nothing else: no router, no HTTP layer, and never will be.
+The composition kernel at the core of Rhythm, the Bun-native backend framework, the piece `@rhythmjs/router` and `@rhythmjs/cli` are built on. It gives an application its structure (startup-time setup, request-time onion middleware, encapsulated modules, all checked at compile time) and deliberately nothing else: no router, no HTTP layer, and never will be.
 
 ## Concepts
 
-- **Onion middleware**: `use()` wraps downstream steps, running code before _and_ after `next()`.
-- **Startup vs request time**: Rhythm only handles request time. Anything created at startup (a DB connection, a config object) is created by you, before serving, and handed to the app by assigning to `app.context`. Rhythm has no setup or teardown phase; you close what you opened.
-- **Startup context**: `app.context` is a plain object typed by the second type parameter, `Rhythm<TInput, TStartup>`. Everything assigned to it is on every request context. Declare the shape once; assignments and reads are then checked.
-- **Encapsulated modules**: `register()` mounts a child `Rhythm`; its context stays sealed unless you explicitly export fields from it.
-- **Readonly context**: the context passed to middleware is deeply readonly at the type level; `next()` takes no arguments (pure Koa style), so state only changes via `derive()` or startup `context`, or through a value branded with the `RhythmMutable` symbol (how `RhythmRouter`/`RhythmCli`'s response objects stay mutable).
+Rhythm separates **when** something happens:
 
-## Example
+- **Startup time: `register()`.** Runs a callback once, immediately, against the app's shared startup context. Use it to create what lives for the whole process (a DB connection, config) and, optionally, how to close it. `stop()` runs the cleanups in reverse order.
+- **Request time: `use()`.** Adds an onion middleware step that runs on every call of the handler, before _and_ after `next()`.
+
+Four small composable functions plug into those two methods, each for one purpose:
+
+| Function                 | Goes in    | Purpose                                                                 |
+| ------------------------ | ---------- | ----------------------------------------------------------------------- |
+| `decorate(fn)`           | `register` | Add typed fields to the startup context.                                |
+| `derive(fn)`             | `use`      | Add typed fields to the request context, then continue.                 |
+| `mount(plugin, cond?)`   | `use`      | Run another pipeline (a `Rhythm`, router, CLI) for each request.        |
+| `include(module, pick?)` | `register` | Run a `Rhythm` module once at startup and pull selected fields from it. |
+
+The context is a plain object, and it is **strictly typed**: `Rhythm<S, I, D>` tracks the startup fields added by `register` (`S`), the input the caller must supply per call (`I`), and the request fields added by `derive` (`D`). Types grow as you chain and nothing is declared twice. Reading a field that was never added is a compile error, a field added by `derive` is not visible to `register`, and a field is only visible to the steps after the one that added it.
 
 ```ts
-import { Rhythm } from "@rhythmjs/rhythm";
+new Rhythm()
+  .use((ctx) => ctx.user) // error: not added yet
+  .use(derive(() => ({ user: { name: "ada" } })))
+  .use((ctx) => ctx.user.name) // string
+  .use((ctx) => ctx.nope); // error: never added
+```
+
+To add a field, use `decorate` or `derive`; plain assignment to an unknown field is rejected on purpose.
 
-const app = new Rhythm<{ userId: string }, { logger: { info(msg: string): void } }>()
+## Example
+
+```ts
+import { Rhythm, decorate, derive } from "@rhythmjs/rhythm";
+
+const app = new Rhythm({ name: "app" })
+  .register(
+    decorate(() => ({ startedAt: Date.now() })), // startup: runs now
+    (ctx) => console.log(`stopped after ${Date.now() - ctx.startedAt}ms`), // cleanup: runs on stop()
+  )
+  .use(derive(() => ({ requestId: crypto.randomUUID() }))) // request: runs on every call
   .use(async (ctx, next) => {
-    const startedAt = Date.now();
+    console.log(`[${ctx.requestId}] up for ${Date.now() - ctx.startedAt}ms`);
     await next();
-    ctx.logger.info(`handled in ${Date.now() - startedAt}ms`);
-  })
-  .use((ctx) => {
-    ctx.logger.info(`hello, ${ctx.userId}`);
   });
 
-app.context.logger = { info: (msg) => console.log(`[greeter] ${msg}`) };
-
-await app.run({ userId: "u1" });
+const handle = app.callback();
+await handle(); // one request
+await app.stop(); // shut down
 ```
 
-On each `run()`, the middleware chain executes in registration order, onion-style.
+## Startup: `register()`
 
-### Startup values
+`register(callback, cleanup?)` calls `callback(ctx, app)` right away with the shared startup context. Return a promise and the first request waits for it. `cleanup(ctx, app)` is optional and runs on `stop()`; if several cleanups throw, `stop()` still runs all of them and rejects with an `AggregateError`. `Rhythm` is also `AsyncDisposable`, so `await using app = ...` stops it for you.
 
 ```ts
-const app = new Rhythm<{ userId: string }, { db: Db }>() // second parameter: the startup shape
-  .register(usersModule); // usersModule: Rhythm<{ userId: string; db: Db }> sees db
-
-app.context.db = await createDb(); // startup time: yours to create and close
-app.context.db = 1; // type error: not a Db
-app.context.cache = x; // type error: not in the declared shape
+const app = new Rhythm().register(
+  decorate(async () => ({ db: await connect() })),
+  (ctx) => ctx.db.close(),
+);
 ```
 
-TypeScript can't infer a type from a later property assignment, so the shape is declared once on the instance. `ctx.db` is then typed in every middleware, and `register()` rejects, at compile time, a module that requires context the parent's input and startup shape don't provide.
+`decorate(fn)` is the typed way to add fields at startup: the returned object is merged into the startup context and `ctx.db` is typed for everything after it. A plain callback works too when you only need a side effect.
 
-A registered module inherits its parent's context and can add its own through its own `module.context`. Those values are visible inside the module and to modules it registers, never to its parent. Per-request input wins over a startup value with the same key. Values are read when a request runs, so assign before serving; nothing checks that every declared key was assigned.
+## Request: `use()` and `derive()`
 
-### Extending the context
+`use(middleware)` takes `(ctx, next) => unknown`. `next()` takes no arguments; to add fields to the context use `derive()`, which runs your function (sync or async), merges the result, and calls `next()` for you. Every call of the handler gets a fresh copy of the startup context, so request-time changes never leak between requests.
 
-`next()` accepts no parameters: middleware cannot pass values downstream through it. To add fields to the context, use `derive()`, which runs your function, merges the returned fields into the context, then calls `next()` for you. The new fields are inferred and visible to everything chained after it.
+```ts
+const app = new Rhythm().use(derive((ctx) => ({ user: lookup(ctx.userId) }))).use((ctx) => console.log(ctx.user.name));
+```
+
+### Typed input
+
+The second type parameter is input the caller must pass to the handler on each call. It is checked at compile time: `callback()` returns a function that requires `I` when it has required fields and makes it optional otherwise.
 
 ```ts
-import { Rhythm, derive } from "@rhythmjs/rhythm";
+const app = new Rhythm<{}, { userId: string }>().use((ctx) => console.log(ctx.userId));
 
-const app = new Rhythm<{ userId: string }>()
-  .use(derive((ctx) => ({ user: { id: ctx.userId, name: "Ada" } })))
-  .use((ctx) => console.log(ctx.user.name));
+await app.callback()({ userId: "u1" });
+await app.callback()(); // type error: userId is required
 ```
 
-Keys prefixed with `#` are dropped from the context. For long-lived resources, create them at startup and assign them to `app.context`.
+## Composing pipelines
+
+### `mount(plugin, condition?)`: request time
 
-### Module registration
+Runs another pipeline against the current request, then continues with `next()`. The optional `condition(ctx)` decides per request whether it runs.
 
 ```ts
-import { Rhythm, derive } from "@rhythmjs/rhythm";
+app.use(mount(routes)); // a RhythmRouter, a RhythmCli, or another Rhythm
+app.use(mount(metrics, () => Bun.env.METRICS !== "off"));
+```
 
-const authModule = new Rhythm<{ userId: string }, { db: Db }>({ name: "auth" }).use(
-  derive((ctx) => ({ user: ctx.db.findUser(ctx.userId) })),
+A mounted `Rhythm` module gets a copy of the context, so what it derives stays sealed inside it; routers and CLIs work on the request context itself (params, response). `mount` checks, at compile time, that the parent's context can supply the plugin's required input (`RhythmRouter<I>` and `RhythmCli<I>` declare theirs the same way). A mounted plugin's own derived fields never leak into the parent's type.
+
+### `include(module, pick?)`: startup time
+
+Runs a `Rhythm` module's pipeline once, at registration, with the parent's startup context as input, and registers the module's `stop()` as a cleanup of the parent. `pick(child)` copies chosen fields from the module's finished context into the parent's startup context (typed); without it nothing crosses back.
+
+```ts
+const database = new Rhythm({ name: "database", type: "service" }).register(
+  decorate(async () => ({ db: await connect() })),
+  (ctx) => ctx.db.close(),
 );
-authModule.context.db = connectToUserDb();
 
-const app = new Rhythm<{ userId: string }>()
-  .register(authModule, (result) => ({ user: result.user })) // only `user` crosses back
-  .use((ctx) => console.log(`hello, ${ctx.user.name}`));
+const app = new Rhythm().register(include(database, (child) => ({ db: child.db })));
 ```
 
-The child runs in place: if it ends the chain without calling `next()`, the parent stops there.
+## Errors, names and sources
+
+- **Named failures.** `new Rhythm({ name, type })` (also accepted by `RhythmRouter` and `RhythmCli`) labels the plugin. A failure inside a mounted or included plugin is rethrown as `mounted service "billing" failed` / `included module "db" failed` with the original error as `cause`. Errors raised downstream of the mount are not attributed to the plugin. Without options the label is `module "anonymous"`.
+- **Sources.** `mount()` and `include()` tag themselves with the plugin they wrap. `pipeline.sources` lists the leaf plugins (routers, CLIs, anything tagged with `withSource(fn, source)`) below it, with `Rhythm` modules expanded in place, and `pipeline.parent` is the pipeline a plugin was adopted by. Tooling such as OpenAPI generation or help output uses this to find what an app is made of.
 
 ## API
 
-- `new Rhythm<TInput, TStartup>(options?)`: creates a pipeline; `options.name`/`options.type` label errors from `register()`.
-- `.use(fn: (ctx, next) => Promise<void> | void, condition?: Condition)`: add an onion middleware step. With a second callback, the step runs only when `condition(ctx)` returns true and otherwise falls through to `next()`; a conditional `derive()` does not extend the context type. `next()` takes no arguments; to extend the context pass a `derive()` middleware.
-- `derive(fn: (ctx) => TExtra | Promise<TExtra>)`: middleware that merges `fn`'s result into the context and continues; the typed way to add fields.
-- `.context`: the startup values object, typed by `Rhythm<TInput, TStartup>`. Assign to it before serving; every request context carries it. Inherited by registered modules, never by the parent.
-- `.register(other: Rhythm, exportValue?)`: mount a child `Rhythm` module; sealed by default, opt in via `exportValue`. Controllers (`RhythmRouter`, `RhythmCli`) are not modules; they mount via `.use()` instead.
-- `.run(input)`: dispatches `input` through the middleware chain.
-- `.callback()`: returns the cached, reusable `(input) => Promise<TContext>` handler `run()` uses internally.
-- `.middleware()`: returns this instance as a plain middleware, for flat mounting into a parent via `.use()` instead of `.register()`.
-- `.parent` / `.sources`: the module this one was registered into, and the tagged sources (routers, clis, any extension) below it in order, with registered modules expanded in place. Read lazily, once the app is assembled. Tag your own middleware with `withSource(fn, source)` from `@rhythmjs/rhythm/source`.
-- `compose(middleware[])`: the standalone Koa-style onion dispatcher `Rhythm` is built on.
+- `new Rhythm<S, I, D>(options?)`: startup, input and derived context types (all inferred as you chain, only `I` is usually written by hand); `options.name` / `options.type` label failures.
+- `.register(callback, cleanup?)`: startup step; returns the app with its type extended when given `decorate()`/`include()`.
+- `.use(middleware)`: request step; `derive()` extends the type.
+- `.callback()`: returns the reusable `(input?) => Promise<ctx>` handler (input required when `I` has required fields). Built from the middleware registered so far.
+- `.stop()` / `[Symbol.asyncDispose]()`: run the cleanups in reverse order.
+- `.sources` / `.parent` / `.options`: introspection, available on every `Pipeline`.
+- `decorate(fn)`, `derive(fn)`, `mount(plugin, condition?)`, `include(module, pick?)`: the composables above.
+- `Pipeline<C>`: abstract base shared by `Rhythm`, `RhythmRouter` and `RhythmCli`: `use()`, `sources`, `parent`, `options`, and a protected `chain()`. Extend it to build your own controller.
+- `compose(middleware[])`: the standalone Koa-style onion dispatcher everything is built on.
+- `withSource(fn, source)` / `sourceOf(fn)`: tag and read a middleware's source.
+
+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.

package/dist/compose.d.ts

@@ -1,11 +1,2 @@
-import type { Condition, DeriveMiddleware, Middleware, NextFn } from "./types";
-type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
-type ContextOf<M> = M extends Middleware<infer C> ? C : never;
-type ExtraOf<M> = M extends DeriveMiddleware<any, infer E> ? E : {};
-export type ComposedMiddleware<TContext extends object, TExtra extends object> = ((context: TContext, next?: NextFn<TContext>) => Promise<TContext>) & Middleware<TContext> & {
-    readonly "~derive": TExtra;
-};
-export declare function gate<TContext extends object>(fn: Middleware<TContext>, condition: Condition<TContext>): Middleware<TContext>;
-export declare function compose<const TMiddleware extends readonly Middleware<any>[]>(middleware: TMiddleware): ComposedMiddleware<UnionToIntersection<ContextOf<TMiddleware[number]>> & {}, UnionToIntersection<ExtraOf<TMiddleware[number]>> & {}>;
-export declare function compose<TContext extends object>(middleware: Middleware<TContext>[]): (context: TContext, next?: NextFn<TContext>) => Promise<TContext>;
-export {};
+import type { Middleware, Next } from "./types";
+export declare function compose<T>(middleware: Middleware<T>[]): (ctx: T, next?: Next) => Promise<void>;

package/dist/compose.js

@@ -1,9 +1,7 @@
 // @bun
 import {
-  gate2,
   compose2
-} from "./rhythm-4by5yd5a.js";
+} from "./rhythm-5w3dm83b.js";
 export {
-  compose2 as compose,
-  gate2 as gate
+  compose2 as compose
 };

package/dist/decorate.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionRegister } from "./types";
+export declare function decorate<U extends object, T extends object = {}>(factory: (ctx: T) => U | Promise<U>): ExtensionRegister<T, U>;

package/dist/decorate.js

@@ -0,0 +1,7 @@
+// @bun
+import {
+  decorate2
+} from "./rhythm-k0635rcp.js";
+export {
+  decorate2 as decorate
+};

package/dist/derive.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionMiddleware } from "./types";
+export declare function derive<U extends object, T extends object = {}>(factory: (ctx: T) => U | Promise<U>): ExtensionMiddleware<T, U>;

package/dist/derive.js

@@ -0,0 +1,7 @@
+// @bun
+import {
+  derive2
+} from "./rhythm-08xqt5pf.js";
+export {
+  derive2 as derive
+};

package/dist/failure.d.ts

@@ -0,0 +1,4 @@
+import type { PipelineOptions } from "./types";
+export declare function wrapFailure(verb: "mounted" | "included", plugin: {
+    readonly options?: PipelineOptions;
+}, cause: unknown): Error;

package/dist/include.d.ts

@@ -0,0 +1,4 @@
+import type { Rhythm } from "./rhythm";
+import type { ExtensionRegister, RegisterCallback } from "./types";
+export declare function include<S extends object, I extends object, D extends object, T extends object = {}, U extends object = {}>(plugin: Rhythm<S, I, D> & (T extends I ? unknown : never), select: (child: S & I & D) => U): ExtensionRegister<T, U>;
+export declare function include<I extends object = {}, T extends object = {}>(plugin: Rhythm<any, I, any> & (T extends I ? unknown : never)): RegisterCallback<T>;

package/dist/include.js

@@ -0,0 +1,8 @@
+// @bun
+import {
+  include2
+} from "./rhythm-bq68je0h.js";
+import"./rhythm-7z989406.js";
+export {
+  include2 as include
+};

package/dist/mount.d.ts

@@ -0,0 +1,2 @@
+import type { Middleware, Mountable } from "./types";
+export declare function mount<T extends object = {}, I extends object = any>(plugin: Mountable<I> & (T extends I ? unknown : never), condition?: (ctx: T) => boolean): Middleware<T>;

package/dist/mount.js

@@ -0,0 +1,8 @@
+// @bun
+import {
+  mount2
+} from "./rhythm-bhjtktgq.js";
+import"./rhythm-7z989406.js";
+export {
+  mount2 as mount
+};

package/dist/pipeline.d.ts

@@ -0,0 +1,13 @@
+import type { Middleware, Next, PipelineOptions } from "./types";
+export declare abstract class Pipeline<C> {
+    #private;
+    readonly options: PipelineOptions;
+    parent?: Pipeline<any>;
+    protected readonly transparent: boolean;
+    constructor(options?: PipelineOptions);
+    get sources(): readonly object[];
+    use(middleware: Middleware<C>): this;
+    abstract callback(): (...input: any[]) => Promise<unknown>;
+    protected adopt(source: object | undefined): void;
+    protected chain(): (ctx: C, next?: Next) => Promise<void>;
+}

package/dist/pipeline.js

@@ -0,0 +1,9 @@
+// @bun
+import {
+  Pipeline2
+} from "./rhythm-vpajpf9k.js";
+import"./rhythm-5w3dm83b.js";
+import"./rhythm-7z989406.js";
+export {
+  Pipeline2 as Pipeline
+};

package/dist/rhythm-08xqt5pf.js

@@ -0,0 +1,18 @@
+// @bun
+// src/derive.ts
+function derive2(factory) {
+  const middleware = (ctx, next) => {
+    const values = factory(ctx);
+    if (values instanceof Promise) {
+      return values.then((resolved) => {
+        Object.assign(ctx, resolved);
+        return next();
+      });
+    }
+    Object.assign(ctx, values);
+    return next();
+  };
+  return middleware;
+}
+
+export { derive2 };

package/dist/rhythm-5w3dm83b.js

@@ -0,0 +1,20 @@
+// @bun
+// src/compose.ts
+function compose2(middleware) {
+  return (ctx, next) => {
+    let index = -1;
+    async function dispatch(i) {
+      if (i <= index) {
+        throw new Error("next() called multiple times");
+      }
+      index = i;
+      const fn = i === middleware.length ? next : middleware[i];
+      if (!fn)
+        return;
+      await fn(ctx, () => dispatch(i + 1));
+    }
+    return dispatch(0);
+  };
+}
+
+export { compose2 };

package/dist/rhythm-bhjtktgq.js

@@ -0,0 +1,25 @@
+// @bun
+import {
+  withSource2
+} from "./rhythm-7z989406.js";
+import {
+  wrapFailure
+} from "./rhythm-vd616d70.js";
+
+// src/mount.ts
+function mount2(plugin, condition) {
+  const handler = plugin.callback();
+  const middleware = async (ctx, next) => {
+    if (!condition || condition(ctx)) {
+      try {
+        await handler(ctx);
+      } catch (cause) {
+        throw wrapFailure("mounted", plugin, cause);
+      }
+    }
+    await next();
+  };
+  return withSource2(middleware, plugin);
+}
+
+export { mount2 };

package/dist/rhythm-bq68je0h.js

@@ -0,0 +1,25 @@
+// @bun
+import {
+  withSource2
+} from "./rhythm-7z989406.js";
+import {
+  wrapFailure
+} from "./rhythm-vd616d70.js";
+
+// src/include.ts
+function include2(plugin, select) {
+  const callback = (ctx, app) => {
+    app.register(() => {}, () => plugin.stop());
+    const done = plugin.callback()(ctx).catch((cause) => {
+      throw wrapFailure("included", plugin, cause);
+    });
+    if (!select)
+      return done;
+    return done.then((child) => {
+      Object.assign(ctx, select(child));
+    });
+  };
+  return withSource2(callback, plugin);
+}
+
+export { include2 };

package/dist/rhythm-k0635rcp.js

@@ -0,0 +1,16 @@
+// @bun
+// src/decorate.ts
+function decorate2(factory) {
+  const callback = (ctx) => {
+    const values = factory(ctx);
+    if (values instanceof Promise) {
+      return values.then((resolved) => {
+        Object.assign(ctx, resolved);
+      });
+    }
+    Object.assign(ctx, values);
+  };
+  return callback;
+}
+
+export { decorate2 };

package/dist/rhythm-vd616d70.js

@@ -0,0 +1,8 @@
+// @bun
+// src/failure.ts
+function wrapFailure(verb, plugin, cause) {
+  const { type = "module", name = "anonymous" } = plugin.options ?? {};
+  return new Error(`${verb} ${type} "${name}" failed`, { cause });
+}
+
+export { wrapFailure };

package/dist/rhythm-vpajpf9k.js

@@ -0,0 +1,39 @@
+// @bun
+import {
+  compose2
+} from "./rhythm-5w3dm83b.js";
+import {
+  sourceOf2
+} from "./rhythm-7z989406.js";
+
+// src/pipeline.ts
+class Pipeline2 {
+  #middleware = [];
+  #sources = [];
+  options;
+  parent;
+  transparent = false;
+  constructor(options = {}) {
+    this.options = options;
+  }
+  get sources() {
+    return this.#sources.flatMap((source) => source instanceof Pipeline2 && source.transparent ? source.sources : [source]);
+  }
+  use(middleware) {
+    this.#middleware.push(middleware);
+    this.adopt(sourceOf2(middleware));
+    return this;
+  }
+  adopt(source) {
+    if (!source)
+      return;
+    if (source instanceof Pipeline2)
+      source.parent = this;
+    this.#sources.push(source);
+  }
+  chain() {
+    return compose2([...this.#middleware]);
+  }
+}
+
+export { Pipeline2 };

package/dist/rhythm.d.ts

@@ -1,20 +1,23 @@
-import type { Condition, DeriveMiddleware, Middleware, OmitHashKeys } from "./types";
-export interface RhythmOptions {
-    name?: string;
-    type?: string;
-    [key: string]: unknown;
-}
-export declare function derive<TContext extends object, TExtra extends object>(fn: (ctx: TContext) => TExtra | Promise<TExtra>): DeriveMiddleware<TContext, OmitHashKeys<TExtra>>;
-export declare class Rhythm<TInput extends object = {}, TStartup extends object = {}, TContext extends object = TInput & TStartup> {
+import { Pipeline } from "./pipeline";
+import type { CleanupCallback, ExtensionMiddleware, ExtensionRegister, Middleware, PipelineOptions, RegisterCallback, RhythmHandler } from "./types";
+export { compose } from "./compose";
+export { decorate } from "./decorate";
+export { derive } from "./derive";
+export { include } from "./include";
+export { mount } from "./mount";
+export { Pipeline } from "./pipeline";
+export { sourceOf, withSource } from "./source";
+export type * from "./types";
+export declare class Rhythm<S extends object = {}, I extends object = {}, D extends object = {}> extends Pipeline<S & I & D> {
     #private;
-    readonly context: TStartup;
-    parent?: Rhythm<any, any, any>;
-    constructor(options?: RhythmOptions);
-    get sources(): readonly object[];
-    use<TExtra extends object>(fn: DeriveMiddleware<TContext, TExtra>): Rhythm<TInput, TStartup, TContext & TExtra>;
-    use(fn: Middleware<TContext>, condition?: Condition<TContext>): this;
-    register<TRegInput extends object, TRegContext extends object, TExported extends object = {}>(other: Rhythm<TRegInput, any, TRegContext> & (TContext extends TRegInput ? unknown : never), exportValue?: (result: TRegContext) => TExported): Rhythm<TInput, TStartup, TContext & TExported>;
-    callback(): (input: TInput) => Promise<TContext>;
-    run(input: TInput): Promise<TContext>;
-    middleware(): Middleware<TContext>;
+    readonly "~input"?: I;
+    protected readonly transparent = true;
+    constructor(options?: PipelineOptions);
+    register<U extends object>(callback: ExtensionRegister<S, U>, cleanup?: CleanupCallback<S & U>): Rhythm<S & U, I, D>;
+    register(callback: RegisterCallback<S>, cleanup?: CleanupCallback<S>): this;
+    stop(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+    use<U extends object>(middleware: ExtensionMiddleware<S & I & D, U>): Rhythm<S, I, D & U>;
+    use(middleware: Middleware<S & I & D>): this;
+    callback(): RhythmHandler<I, S & I & D>;
 }

package/dist/rhythm.js

@@ -1,102 +1,86 @@
 // @bun
 import {
-  gate2,
   compose2
-} from "./rhythm-4by5yd5a.js";
+} from "./rhythm-5w3dm83b.js";
 import {
   withSource2,
   sourceOf2
 } from "./rhythm-7z989406.js";
+import {
+  Pipeline2
+} from "./rhythm-vpajpf9k.js";
+import {
+  decorate2
+} from "./rhythm-k0635rcp.js";
+import {
+  derive2
+} from "./rhythm-08xqt5pf.js";
+import {
+  include2
+} from "./rhythm-bq68je0h.js";
+import {
+  mount2
+} from "./rhythm-bhjtktgq.js";
 
 // src/rhythm.ts
-function publicEntries(value) {
-  const exported = {};
-  for (const [key, val] of Object.entries(value)) {
-    if (!key.startsWith("#"))
-      exported[key] = val;
-  }
-  return exported;
-}
-function derive(fn) {
-  if (typeof fn !== "function")
-    throw new TypeError("derive factory must be a function!");
-  const middleware = async (ctx, next) => {
-    const value = await fn(ctx);
-    Object.assign(ctx, publicEntries(value));
-    await next();
-  };
-  return middleware;
-}
-
-class Rhythm {
-  #middleware = [];
-  #options;
-  #sources = [];
-  context = {};
-  parent;
-  constructor(options = {}) {
-    this.#options = options;
-  }
-  get sources() {
-    return this.#sources.flatMap((source) => source instanceof Rhythm ? source.sources : [source]);
-  }
-  #adopt(source) {
-    if (!source)
-      return;
-    if (source instanceof Rhythm)
-      source.parent = this;
-    this.#sources.push(source);
+class Rhythm extends Pipeline2 {
+  #ctx = {};
+  #cleanups = [];
+  #ready;
+  transparent = true;
+  constructor(options) {
+    super({ type: "module", ...options });
   }
-  use(fn, condition) {
-    if (typeof fn !== "function")
-      throw new TypeError("middleware must be a function!");
-    this.#middleware.push(condition ? gate2(fn, condition) : fn);
-    this.#adopt(sourceOf2(fn));
+  register(callback, cleanup) {
+    this.adopt(sourceOf2(callback));
+    const result = callback(this.#ctx, this);
+    if (result instanceof Promise) {
+      this.#ready = Promise.all([this.#ready, result]);
+    }
+    if (cleanup) {
+      this.#cleanups.push(() => cleanup(this.#ctx, this));
+    }
     return this;
   }
-  register(other, exportValue) {
-    const module = other;
-    this.#adopt(module);
-    this.#middleware.push(async (ctx, next) => {
-      const inner = Object.assign({ ...ctx }, module.context);
-      let downstream;
+  async stop() {
+    const errors = [];
+    while (this.#cleanups.length) {
+      const cleanup = this.#cleanups.pop();
       try {
-        await compose2([...module.#middleware])(inner, async () => {
-          try {
-            if (exportValue)
-              Object.assign(ctx, exportValue(inner));
-            await next();
-          } catch (error) {
-            downstream = { error };
-            throw error;
-          }
-          return inner;
-        });
-      } catch (cause) {
-        if (downstream && downstream.error === cause)
-          throw cause;
-        const { type = "module", name = "anonymous" } = module.#options;
-        throw new Error(`registered ${type} "${name}" failed`, { cause });
+        await cleanup();
+      } catch (error) {
+        errors.push(error);
       }
-    });
-    return this;
+    }
+    if (errors.length) {
+      throw new AggregateError(errors, "cleanup failed");
+    }
   }
-  callback() {
-    const fn = compose2([...this.#middleware]);
-    return (input) => fn({ ...this.context, ...input });
+  [Symbol.asyncDispose]() {
+    return this.stop();
   }
-  run(input) {
-    return this.callback()(input);
+  use(middleware) {
+    return super.use(middleware);
   }
-  middleware() {
-    const fn = compose2([...this.#middleware]);
-    return withSource2(async (ctx, next) => {
-      Object.assign(ctx, this.context);
-      await fn(ctx, next);
-    }, this);
+  callback() {
+    const fn = this.chain();
+    return async (input) => {
+      if (this.#ready)
+        await this.#ready;
+      const ctx = Object.assign({}, this.#ctx, input);
+      await fn(ctx);
+      return ctx;
+    };
   }
 }
 export {
+  Pipeline2 as Pipeline,
   Rhythm,
-  derive
+  compose2 as compose,
+  decorate2 as decorate,
+  derive2 as derive,
+  include2 as include,
+  mount2 as mount,
+  sourceOf2 as sourceOf,
+  withSource2 as withSource
 };

package/dist/source.d.ts

@@ -1,3 +1,2 @@
-import type { Middleware } from "./types";
-export declare function withSource<TFn extends Middleware<any>>(fn: TFn, source: object): TFn;
+export declare function withSource<F extends (...args: any[]) => unknown>(fn: F, source: object): F;
 export declare function sourceOf(fn: unknown): object | undefined;

package/dist/types.d.ts

@@ -1,9 +1,23 @@
-export type OmitHashKeys<T> = {
-    [K in keyof T as K extends `#${string}` ? never : K]: T[K];
+import type { Rhythm } from "./rhythm";
+export type Next = () => Promise<void>;
+export type Middleware<T> = (ctx: T, next: Next) => unknown | Promise<unknown>;
+declare const extension: unique symbol;
+export type Extension<U extends object> = {
+    [extension]: U;
 };
-export type Condition<TContext extends object> = (ctx: TContext) => boolean | Promise<boolean>;
-export type NextFn<TContext extends object> = () => Promise<TContext>;
-export type Middleware<TContext extends object> = (ctx: TContext, next: NextFn<TContext>) => Promise<void> | void;
-export type DeriveMiddleware<TContext extends object, TExtra extends object> = Middleware<TContext> & {
-    readonly "~derive": TExtra;
+export type ExtensionMiddleware<T extends object, U extends object> = Middleware<T> & Extension<U>;
+export type RegisterCallback<T extends object> = (ctx: T, app: Rhythm<T, any, any>) => unknown;
+export type CleanupCallback<T extends object> = (ctx: T, app: Rhythm<T, any, any>) => unknown;
+export type ExtensionRegister<T extends object, U extends object> = RegisterCallback<T> & Extension<U>;
+export interface PipelineOptions {
+    name?: string;
+    type?: string;
+}
+export type Mountable<I extends object = any> = {
+    callback(): (...input: any[]) => Promise<unknown>;
+    readonly options?: PipelineOptions;
+    readonly "~input"?: I;
 };
+export type RhythmInputArgs<I extends object> = {} extends I ? [input?: I] : [input: I];
+export type RhythmHandler<I extends object, C extends object> = (...input: RhythmInputArgs<I>) => Promise<C>;
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rhythmjs/rhythm",
-  "version": "0.0.16",
-  "description": "A minimal, type-safe onion-middleware and provider composition kernel.",
+  "version": "0.0.17",
+  "description": "A minimal, type-safe middleware and startup-composition kernel: register() at startup, use() per request, with derive, decorate, mount and include.",
   "homepage": "https://rhythm.js.org/rhythm",
   "license": "ISC",
   "repository": {
@@ -23,6 +23,26 @@
       "types": "./dist/compose.d.ts",
       "default": "./dist/compose.js"
     },
+    "./pipeline": {
+      "types": "./dist/pipeline.d.ts",
+      "default": "./dist/pipeline.js"
+    },
+    "./derive": {
+      "types": "./dist/derive.d.ts",
+      "default": "./dist/derive.js"
+    },
+    "./decorate": {
+      "types": "./dist/decorate.d.ts",
+      "default": "./dist/decorate.js"
+    },
+    "./mount": {
+      "types": "./dist/mount.d.ts",
+      "default": "./dist/mount.js"
+    },
+    "./include": {
+      "types": "./dist/include.d.ts",
+      "default": "./dist/include.js"
+    },
     "./source": {
       "types": "./dist/source.d.ts",
       "default": "./dist/source.js"
@@ -45,7 +65,7 @@
     "bun": ">=1.2.0"
   },
   "scripts": {
-    "build": "bun build src/rhythm.ts src/compose.ts src/source.ts src/types.ts --outdir dist --root src --format esm --target bun --packages external --splitting && tsc -p tsconfig.build.json",
+    "build": "rm -rf dist && bun build src/rhythm.ts src/compose.ts src/pipeline.ts src/derive.ts src/decorate.ts src/mount.ts src/include.ts src/source.ts src/types.ts --outdir dist --root src --format esm --target bun --packages external --splitting && tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "test": "bun test"
   }

package/dist/rhythm-4by5yd5a.js

@@ -1,42 +0,0 @@
-// @bun
-// src/compose.ts
-var toVoid = () => {};
-function gate2(fn, condition) {
-  if (typeof condition !== "function")
-    throw new TypeError("condition must be a function!");
-  return (ctx, next) => {
-    const pass = condition(ctx);
-    if (typeof pass === "boolean")
-      return pass ? fn(ctx, next) : next().then(toVoid);
-    return pass.then((ok) => ok ? fn(ctx, next) : next().then(toVoid));
-  };
-}
-function compose2(middleware) {
-  if (!Array.isArray(middleware))
-    throw new TypeError("Middleware stack must be an array!");
-  for (const fn of middleware) {
-    if (typeof fn !== "function")
-      throw new TypeError("Middleware must be composed of functions!");
-  }
-  return function(context, next) {
-    let index = -1;
-    return dispatch(0);
-    function dispatch(i) {
-      if (i <= index)
-        return Promise.reject(new Error("next() called multiple times"));
-      index = i;
-      const fn = i === middleware.length ? next : middleware[i];
-      if (!fn)
-        return Promise.resolve(context);
-      const dispatchNext = () => dispatch(i + 1);
-      try {
-        const call = fn;
-        return Promise.resolve(call(context, dispatchNext)).then(() => context);
-      } catch (err) {
-        return Promise.reject(err);
-      }
-    }
-  };
-}
-
-export { gate2, compose2 };

package/dist/rhythm-d9ycs7zz.js

@@ -1,31 +0,0 @@
-// @bun
-// src/compose.ts
-function compose2(middleware) {
-  if (!Array.isArray(middleware))
-    throw new TypeError("Middleware stack must be an array!");
-  for (const fn of middleware) {
-    if (typeof fn !== "function")
-      throw new TypeError("Middleware must be composed of functions!");
-  }
-  return function(context, next) {
-    let index = -1;
-    return dispatch(0);
-    function dispatch(i) {
-      if (i <= index)
-        return Promise.reject(new Error("next() called multiple times"));
-      index = i;
-      const fn = i === middleware.length ? next : middleware[i];
-      if (!fn)
-        return Promise.resolve(context);
-      const dispatchNext = () => dispatch(i + 1);
-      try {
-        const call = fn;
-        return Promise.resolve(call(context, dispatchNext)).then(() => context);
-      } catch (err) {
-        return Promise.reject(err);
-      }
-    }
-  };
-}
-
-export { compose2 };

package/dist/rhythm-s2x65tdb.js

@@ -1,42 +0,0 @@
-// @bun
-// src/compose.ts
-var toVoid = () => {};
-function gate2(fn, when) {
-  if (typeof when !== "function")
-    throw new TypeError("when must be a function!");
-  return (ctx, next) => {
-    const pass = when(ctx);
-    if (typeof pass === "boolean")
-      return pass ? fn(ctx, next) : next().then(toVoid);
-    return pass.then((ok) => ok ? fn(ctx, next) : next().then(toVoid));
-  };
-}
-function compose2(middleware) {
-  if (!Array.isArray(middleware))
-    throw new TypeError("Middleware stack must be an array!");
-  for (const fn of middleware) {
-    if (typeof fn !== "function")
-      throw new TypeError("Middleware must be composed of functions!");
-  }
-  return function(context, next) {
-    let index = -1;
-    return dispatch(0);
-    function dispatch(i) {
-      if (i <= index)
-        return Promise.reject(new Error("next() called multiple times"));
-      index = i;
-      const fn = i === middleware.length ? next : middleware[i];
-      if (!fn)
-        return Promise.resolve(context);
-      const dispatchNext = () => dispatch(i + 1);
-      try {
-        const call = fn;
-        return Promise.resolve(call(context, dispatchNext)).then(() => context);
-      } catch (err) {
-        return Promise.reject(err);
-      }
-    }
-  };
-}
-
-export { gate2, compose2 };