@rhythmjs/rhythm 0.0.12 → 0.0.14

package/README.md

@@ -7,7 +7,7 @@ The composition kernel at the core of Rhythm, the Bun-native backend framework,
 - **Onion middleware**: `use()` wraps downstream steps, running code before _and_ after `next()`.
 - **Providers**: `provide()` registers a value or async factory that resolves once and joins the context at its position in the chain: only middleware (and mounted controllers) added after it see the value. A returned key prefixed with `#` (e.g. `"#close"`) stays out of context but is still passed in full to `dispose()`.
 - **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; state only changes via `next(extra)`, or through a value branded with the `RhythmMutable` symbol (how `RhythmRouter`/`RhythmCli`'s response objects stay mutable).
+- **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 `provide()`), or through a value branded with the `RhythmMutable` symbol (how `RhythmRouter`/`RhythmCli`'s response objects stay mutable).
 
 ## Example
 
@@ -34,34 +34,50 @@ await app.teardown();
 
 `provide()` factories run once, in declaration order, each receiving everything resolved so far via `deps`. On each `run()`, the whole chain, middleware and provider injections alike, executes in registration order, onion-style: everything only applies to what was chained after it.
 
+### Extending the context
+
+`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
+import { Rhythm, derive } from "@rhythmjs/rhythm";
+
+const app = new Rhythm<{ userId: string }>()
+  .use(derive((ctx) => ({ user: { id: ctx.userId, name: "Ada" } })))
+  .use((ctx) => console.log(ctx.user.name));
+```
+
+Keys prefixed with `#` are dropped from the context. For long-lived resources with teardown, use `provide()` instead.
+
 ### Module registration
 
 ```ts
+import { Rhythm, derive } from "@rhythmjs/rhythm";
+
 const authModule = new Rhythm<{ userId: string }>({ name: "auth" })
   .provide(
     () => ({ db: connectToUserDb() }),
     (db) => db.close(),
   )
-  .use(async (ctx, next) => {
-    await next({ user: ctx.db.findUser(ctx.userId) });
-  });
+  .use(derive((ctx) => ({ user: ctx.db.findUser(ctx.userId) })));
 
 const app = new Rhythm<{ userId: string }>()
   .register(authModule, (result) => ({ user: result.user })) // only `user` crosses back
   .use((ctx) => console.log(`hello, ${ctx.user.name}`));
 ```
 
-`register()` folds the child's `setup()`/`teardown()` into the parent's lifecycle.
+`register()` folds the child's `setup()`/`teardown()` into the parent's lifecycle. The child runs in place: if it ends the chain without calling `next()`, the parent stops there.
 
 ## API
 
 - `new Rhythm<TInput>(options?)`: creates a pipeline; `options.name`/`options.type` label errors from `register()`.
-- `.use(fn: (ctx, next) => Promise<void> | void)`: add an onion middleware step.
+- `.use(fn: (ctx, next) => Promise<void> | void)`: add an onion middleware step. `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.
 - `.provide(factory: (deps) => TValue | Promise<TValue>, dispose?)`: register a provider; resolved once, injected at its chain position, disposed in reverse order on `teardown()`.
 - `.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)`: runs `setup()` if needed, 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`.
 - `.setup()`: resolves all providers, cascading into registered modules. Idempotent; retryable on failure.
 - `.teardown()`: disposes all providers in reverse order, cascading into registered modules.
 - `compose(middleware[])`: the standalone Koa-style onion dispatcher `Rhythm` is built on.

package/dist/rhythm-7z989406.js

@@ -0,0 +1,14 @@
+// @bun
+// src/source.ts
+var SOURCE = "~source";
+function withSource2(fn, source) {
+  Object.defineProperty(fn, SOURCE, { value: source });
+  return fn;
+}
+function sourceOf2(fn) {
+  if (typeof fn !== "function")
+    return;
+  return fn[SOURCE];
+}
+
+export { withSource2, sourceOf2 };

package/dist/rhythm-habff18r.js

@@ -0,0 +1,41 @@
+// @bun
+// src/sources.ts
+var sourceKey2 = Symbol.for("rhythm.source");
+var trackerKey2 = Symbol.for("rhythm.tracker");
+function tagSource2(fn, source) {
+  return Object.assign(fn, { [sourceKey2]: source });
+}
+function sourceOf2(fn) {
+  return fn[sourceKey2];
+}
+function createSourceTracker2() {
+  const recorded = new Set;
+  const listeners = new Set;
+  const add = (source) => {
+    if (recorded.has(source))
+      return;
+    recorded.add(source);
+    for (const listener of listeners)
+      listener(source);
+  };
+  return {
+    get sources() {
+      return [...recorded];
+    },
+    add,
+    observe(listener) {
+      listeners.add(listener);
+      for (const source of recorded)
+        listener(source);
+    },
+    track(fn) {
+      const source = sourceOf2(fn);
+      if (!source)
+        return;
+      add(source);
+      source[trackerKey2]?.observe(add);
+    }
+  };
+}
+
+export { sourceKey2, trackerKey2, tagSource2, sourceOf2, createSourceTracker2 };

package/dist/rhythm.d.ts

@@ -7,7 +7,9 @@ export interface RhythmOptions {
 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 = {}, TContext extends object = TInput, TProviders extends object = {}> {
     #private;
+    parent?: Rhythm<any, any, any>;
     constructor(options?: RhythmOptions);
+    get sources(): readonly object[];
     use<TExtra extends object>(fn: DeriveMiddleware<TContext, TExtra>): Rhythm<TInput, TContext & TExtra, TProviders>;
     use(fn: Middleware<TContext>): this;
     provide<TValue extends object>(factory: (deps: TProviders) => TValue | Promise<TValue>, dispose?: (value: TValue) => void | Promise<void>): Rhythm<TInput, TContext & OmitHashKeys<TValue>, TProviders & OmitHashKeys<TValue>>;

package/dist/rhythm.js

@@ -2,6 +2,10 @@
 import {
   compose2
 } from "./rhythm-d9ycs7zz.js";
+import {
+  withSource2,
+  sourceOf2
+} from "./rhythm-7z989406.js";
 
 // src/rhythm.ts
 function publicEntries(value) {
@@ -28,13 +32,26 @@ class Rhythm {
   #options;
   #providers = [];
   #setupPromise = null;
+  #sources = [];
+  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);
+  }
   use(fn) {
     if (typeof fn !== "function")
       throw new TypeError("middleware must be a function!");
     this.#middleware.push(fn);
+    this.#adopt(sourceOf2(fn));
     return this;
   }
   provide(factory, dispose) {
@@ -48,6 +65,7 @@ class Rhythm {
   }
   register(other, exportValue) {
     const module = other;
+    this.#adopt(module);
     this.#providers.push({
       factory: async () => {
         await module.setup();
@@ -55,17 +73,29 @@ class Rhythm {
       },
       dispose: () => module.teardown()
     });
+    let chain;
     this.#middleware.push(async (ctx, next) => {
-      let result;
+      const inner = { ...ctx };
+      let downstream;
       try {
-        result = await module.run(ctx);
+        await module.setup();
+        await (chain ??= 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 });
       }
-      if (exportValue)
-        Object.assign(ctx, exportValue(result));
-      await next();
     });
     return this;
   }
@@ -106,10 +136,10 @@ class Rhythm {
   }
   middleware() {
     const fn = compose2([...this.#middleware]);
-    return async (ctx, next) => {
+    return withSource2(async (ctx, next) => {
       await this.setup();
       await fn(ctx, next);
-    };
+    }, this);
   }
 }
 export {

package/dist/source.d.ts

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

package/dist/source.js

@@ -0,0 +1,9 @@
+// @bun
+import {
+  withSource2,
+  sourceOf2
+} from "./rhythm-7z989406.js";
+export {
+  sourceOf2 as sourceOf,
+  withSource2 as withSource
+};

package/dist/sources.d.ts

@@ -0,0 +1,21 @@
+/** Marks a middleware as the mount point of a self-describing source (a router, a cli, a Rhythm module…). */
+export declare const sourceKey: unique symbol;
+/** Marks a source that hosts mounts of its own, so a parent can follow them. */
+export declare const trackerKey: unique symbol;
+export type SourceListener = (source: object) => void;
+export interface SourceTracker {
+    /** Every source recorded so far, in discovery order. */
+    readonly sources: readonly object[];
+    add(source: object): void;
+    /** Replays the sources recorded so far, then every one added later. */
+    observe(listener: SourceListener): void;
+    /** Records the source `fn` is tagged with, and follows the sources that source hosts. */
+    track(fn: object): void;
+}
+export interface SourceHost {
+    readonly sources: readonly object[];
+    readonly [trackerKey]: SourceTracker;
+}
+export declare function tagSource<T extends object>(fn: T, source: object): T;
+export declare function sourceOf(fn: object): object | undefined;
+export declare function createSourceTracker(): SourceTracker;

package/dist/sources.js

@@ -0,0 +1,15 @@
+// @bun
+import {
+  sourceKey2,
+  trackerKey2,
+  tagSource2,
+  sourceOf2,
+  createSourceTracker2
+} from "./rhythm-habff18r.js";
+export {
+  createSourceTracker2 as createSourceTracker,
+  sourceKey2 as sourceKey,
+  sourceOf2 as sourceOf,
+  tagSource2 as tagSource,
+  trackerKey2 as trackerKey
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhythmjs/rhythm",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "description": "A minimal, type-safe onion-middleware and provider composition kernel.",
   "homepage": "https://rhythm.js.org/rhythm",
   "license": "ISC",
@@ -23,6 +23,10 @@
       "types": "./dist/compose.d.ts",
       "default": "./dist/compose.js"
     },
+    "./source": {
+      "types": "./dist/source.d.ts",
+      "default": "./dist/source.js"
+    },
     "./types": {
       "types": "./dist/types.d.ts",
       "default": "./dist/types.js"
@@ -41,7 +45,7 @@
     "bun": ">=1.2.0"
   },
   "scripts": {
-    "build": "bun build src/rhythm.ts src/compose.ts src/types.ts --outdir dist --root src --format esm --target bun --packages external --splitting && tsc -p tsconfig.build.json",
+    "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",
     "typecheck": "tsc --noEmit",
     "test": "bun test"
   }