@rhythmjs/rhythm 0.0.12 → 0.0.13

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,17 +34,31 @@ 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
@@ -56,7 +70,8 @@ const app = new Rhythm<{ userId: string }>()
 ## 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.

package/package.json

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