@rhythmjs/rhythm 0.0.13 → 0.0.15

package/README.md

@@ -1,24 +1,21 @@
 # @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, lifecycle-managed providers, 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 (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.
 
 ## Concepts
 
 - **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()`.
+- **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 `provide()`), 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 startup `context`, or through a value branded with the `RhythmMutable` symbol (how `RhythmRouter`/`RhythmCli`'s response objects stay mutable).
 
 ## Example
 
 ```ts
 import { Rhythm } from "@rhythmjs/rhythm";
 
-const app = new Rhythm<{ userId: string }>()
-  .provide(() => ({ config: { serviceName: "greeter" } }))
-  .provide((deps) => ({
-    logger: { info: (msg: string) => console.log(`[${deps.config.serviceName}] ${msg}`) },
-  }))
+const app = new Rhythm<{ userId: string }, { logger: { info(msg: string): void } }>()
   .use(async (ctx, next) => {
     const startedAt = Date.now();
     await next();
@@ -28,11 +25,27 @@ const app = new Rhythm<{ userId: string }>()
     ctx.logger.info(`hello, ${ctx.userId}`);
   });
 
+app.context.logger = { info: (msg) => console.log(`[greeter] ${msg}`) };
+
 await app.run({ userId: "u1" });
-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.
+On each `run()`, the middleware chain executes in registration order, onion-style.
+
+### Startup values
+
+```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
+```
+
+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.
+
+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.
 
 ### Extending the context
 
@@ -46,37 +59,33 @@ const app = new Rhythm<{ userId: string }>()
   .use((ctx) => console.log(ctx.user.name));
 ```
 
-Keys prefixed with `#` are dropped from the context. For long-lived resources with teardown, use `provide()` instead.
+Keys prefixed with `#` are dropped from the context. For long-lived resources, create them at startup and assign them to `app.context`.
 
 ### Module registration
 
 ```ts
 import { Rhythm, derive } from "@rhythmjs/rhythm";
 
-const authModule = new Rhythm<{ userId: string }>({ name: "auth" })
-  .provide(
-    () => ({ db: connectToUserDb() }),
-    (db) => db.close(),
-  )
+const authModule = new Rhythm<{ userId: string }, { db: Db }>({ name: "auth" })
   .use(derive((ctx) => ({ user: ctx.db.findUser(ctx.userId) })));
+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}`));
 ```
 
-`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()`.
+- `new Rhythm<TInput, TStartup>(options?)`: creates a pipeline; `options.name`/`options.type` label errors from `register()`.
 - `.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()`.
+- `.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)`: runs `setup()` if needed, dispatches `input` through the middleware chain.
+- `.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()`.
-- `.setup()`: resolves all providers, cascading into registered modules. Idempotent; retryable on failure.
-- `.teardown()`: disposes all providers in reverse order, cascading into registered modules.
+- `.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.

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.d.ts

@@ -5,15 +5,20 @@ export interface RhythmOptions {
     [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 = {}, TContext extends object = TInput, TProviders extends object = {}> {
+export declare class Rhythm<TInput extends object = {}, TStartup extends object = {}, TContext extends object = TInput & TStartup> {
     #private;
+    /**
+     * Startup-time values (a db connection, config, ...). Declare the shape as the second type parameter, assign
+     * before serving, and every request context carries them. Registered modules inherit their parent's values and
+     * can add their own; a module's values never reach its parent.
+     */
+    readonly context: TStartup;
+    parent?: Rhythm<any, any, any>;
     constructor(options?: RhythmOptions);
-    use<TExtra extends object>(fn: DeriveMiddleware<TContext, TExtra>): Rhythm<TInput, TContext & TExtra, TProviders>;
+    get sources(): readonly object[];
+    use<TExtra extends object>(fn: DeriveMiddleware<TContext, TExtra>): Rhythm<TInput, TStartup, TContext & TExtra>;
     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>>;
-    register<TRegInput extends object, TRegContext extends object, TExported extends object = {}>(other: Rhythm<TRegInput, TRegContext, any> & (TContext extends TRegInput ? unknown : never), exportValue?: (result: TRegContext) => TExported): Rhythm<TInput, TContext & TExported, TProviders>;
-    setup(): Promise<void>;
-    teardown(): Promise<void>;
+    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>;

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) {
@@ -26,90 +30,69 @@ function derive(fn) {
 class Rhythm {
   #middleware = [];
   #options;
-  #providers = [];
-  #setupPromise = null;
+  #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);
+  }
   use(fn) {
     if (typeof fn !== "function")
       throw new TypeError("middleware must be a function!");
     this.#middleware.push(fn);
-    return this;
-  }
-  provide(factory, dispose) {
-    const entry = { factory, dispose };
-    this.#providers.push(entry);
-    this.#middleware.push(async (ctx, next) => {
-      Object.assign(ctx, publicEntries(entry.resolved));
-      await next();
-    });
+    this.#adopt(sourceOf2(fn));
     return this;
   }
   register(other, exportValue) {
     const module = other;
-    this.#providers.push({
-      factory: async () => {
-        await module.setup();
-        return {};
-      },
-      dispose: () => module.teardown()
-    });
+    this.#adopt(module);
     this.#middleware.push(async (ctx, next) => {
-      let result;
+      const inner = Object.assign({ ...ctx }, module.context);
+      let downstream;
       try {
-        result = await module.run(ctx);
+        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 });
       }
-      if (exportValue)
-        Object.assign(ctx, exportValue(result));
-      await next();
     });
     return this;
   }
-  setup() {
-    if (!this.#setupPromise) {
-      this.#setupPromise = this.#resolveProviders().catch((err) => {
-        this.#setupPromise = null;
-        throw err;
-      });
-    }
-    return this.#setupPromise;
-  }
-  async#resolveProviders() {
-    const resolved = {};
-    for (const entry of this.#providers) {
-      entry.resolved = await entry.factory(resolved);
-      Object.assign(resolved, publicEntries(entry.resolved));
-    }
-  }
-  async teardown() {
-    for (const entry of [...this.#providers].reverse()) {
-      if (entry.resolved === undefined)
-        continue;
-      await entry.dispose?.(entry.resolved);
-      entry.resolved = undefined;
-    }
-    this.#setupPromise = null;
-  }
   callback() {
     const fn = compose2([...this.#middleware]);
-    return async (input) => {
-      await this.setup();
-      return fn({ ...input });
-    };
+    return (input) => fn({ ...this.context, ...input });
   }
   run(input) {
     return this.callback()(input);
   }
   middleware() {
     const fn = compose2([...this.#middleware]);
-    return async (ctx, next) => {
-      await this.setup();
+    return withSource2(async (ctx, next) => {
+      Object.assign(ctx, this.context);
       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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhythmjs/rhythm",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "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"
   }