@rhythmjs/rhythm 0.0.13 → 0.0.14

package/README.md

@@ -65,7 +65,7 @@ const app = new Rhythm<{ userId: string }>()
   .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
 
@@ -77,6 +77,7 @@ const app = new Rhythm<{ userId: string }>()
 - `.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.13",
+  "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"
   }