@rhythmjs/rhythm 0.0.14 → 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,38 +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.
+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()`.
 - `.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.d.ts

@@ -5,17 +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);
     get sources(): readonly object[];
-    use<TExtra extends object>(fn: DeriveMiddleware<TContext, TExtra>): Rhythm<TInput, TContext & TExtra, TProviders>;
+    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

@@ -30,9 +30,8 @@ function derive(fn) {
 class Rhythm {
   #middleware = [];
   #options;
-  #providers = [];
-  #setupPromise = null;
   #sources = [];
+  context = {};
   parent;
   constructor(options = {}) {
     this.#options = options;
@@ -54,32 +53,14 @@ class Rhythm {
     this.#adopt(sourceOf2(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();
-    });
-    return this;
-  }
   register(other, exportValue) {
     const module = other;
     this.#adopt(module);
-    this.#providers.push({
-      factory: async () => {
-        await module.setup();
-        return {};
-      },
-      dispose: () => module.teardown()
-    });
-    let chain;
     this.#middleware.push(async (ctx, next) => {
-      const inner = { ...ctx };
+      const inner = Object.assign({ ...ctx }, module.context);
       let downstream;
       try {
-        await module.setup();
-        await (chain ??= compose2([...module.#middleware]))(inner, async () => {
+        await compose2([...module.#middleware])(inner, async () => {
           try {
             if (exportValue)
               Object.assign(ctx, exportValue(inner));
@@ -99,37 +80,9 @@ class Rhythm {
     });
     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);
@@ -137,7 +90,7 @@ class Rhythm {
   middleware() {
     const fn = compose2([...this.#middleware]);
     return withSource2(async (ctx, next) => {
-      await this.setup();
+      Object.assign(ctx, this.context);
       await fn(ctx, next);
     }, this);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhythmjs/rhythm",
-  "version": "0.0.14",
+  "version": "0.0.15",
   "description": "A minimal, type-safe onion-middleware and provider composition kernel.",
   "homepage": "https://rhythm.js.org/rhythm",
   "license": "ISC",

package/dist/rhythm-habff18r.js

@@ -1,41 +0,0 @@
-// @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/sources.d.ts

@@ -1,21 +0,0 @@
-/** 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

@@ -1,15 +0,0 @@
-// @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
-};