@rhythmjs/rhythm 0.0.1 → 0.0.3

package/README.md

@@ -5,7 +5,7 @@ The core composition kernel `@rhythmjs/router` and `@rhythmjs/cli` are built on.
 ## 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 is injected into every request's context. A returned key prefixed with `#` (e.g. `"#close"`) stays out of context but is still passed in full to `dispose()`.
+- **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).
 
@@ -32,7 +32,7 @@ await app.run({ userId: "u1" });
 await app.teardown();
 ```
 
-`provide()` factories run once, in declaration order, each receiving everything resolved so far via `deps`. `use()` middleware runs on every `run()` call, in onion order.
+`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.
 
 ### Module registration
 
@@ -57,11 +57,11 @@ const app = new Rhythm<{ userId: string }>()
 
 - `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.
-- `.provide(factory: (deps) => TValue | Promise<TValue>, dispose?)` — register a provider; resolved once, disposed in reverse order on `teardown()`.
-- `.register(other: Rhythm, exportValue?)` — mount a child module; sealed by default, opt in via `exportValue`.
+- `.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()` (what `RhythmRouter.routes()`/`RhythmCli.commands()` build on).
+- `.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.
 - `compose(middleware[])` — the standalone Koa-style onion dispatcher `Rhythm` is built on.

package/dist/compose.d.ts

@@ -0,0 +1,4 @@
+import { Middleware, NextFn } from "./types.js";
+//#region src/compose.d.ts
+export declare function compose<TContext extends object>(middleware: Middleware<TContext>[]): (context: TContext, next?: NextFn<TContext>) => Promise<TContext>;
+//#endregion

package/dist/compose.js

@@ -0,0 +1,24 @@
+//#region src/compose.ts
+function compose(middleware) {
+	if (!Array.isArray(middleware)) throw new TypeError("Middleware stack must be an array!");
+	for (const fn of middleware) if (typeof fn !== "function") throw new TypeError("Middleware must be composed of functions!");
+	return function(context, next) {
+		let index = -1;
+		return dispatch(0);
+		function dispatch(i) {
+			if (i <= index) return Promise.reject(/* @__PURE__ */ new Error("next() called multiple times"));
+			index = i;
+			const fn = i === middleware.length ? next : middleware[i];
+			if (!fn) return Promise.resolve(context);
+			const dispatchNext = () => dispatch(i + 1);
+			try {
+				const call = fn;
+				return Promise.resolve(call(context, dispatchNext)).then(() => context);
+			} catch (err) {
+				return Promise.reject(err);
+			}
+		}
+	};
+}
+//#endregion
+export { compose };

package/dist/rhythm.d.ts

@@ -1,26 +1,18 @@
+import { DeriveMiddleware, Middleware, OmitHashKeys } from "./types.js";
 //#region src/rhythm.d.ts
-export declare const RhythmMutable: unique symbol;
-export type DeepReadonly<T> = T extends ((...args: any[]) => any) ? T : T extends ReadonlyArray<infer U> ? readonly DeepReadonly<U>[] : T extends Map<infer K, infer V> ? ReadonlyMap<DeepReadonly<K>, DeepReadonly<V>> : T extends Set<infer U> ? ReadonlySet<DeepReadonly<U>> : T extends {
-  readonly [RhythmMutable]: true;
-} ? T : T extends object ? { readonly [K in keyof T]: DeepReadonly<T[K]>; } : T;
-export type OmitHashKeys<T> = { [K in keyof T as K extends `#${string}` ? never : K]: T[K]; };
-export type NextFn<TContext extends object> = {
-  (): Promise<DeepReadonly<TContext>>;
-  <TExtra extends object>(extra: TExtra): Promise<DeepReadonly<TContext & TExtra>>;
-};
-export type Middleware<TContext extends object> = (ctx: DeepReadonly<TContext>, next: NextFn<TContext>) => Promise<void> | void;
-export declare function compose<TContext extends object>(middleware: Middleware<TContext>[]): (context: TContext, next?: NextFn<TContext>) => Promise<TContext>;
 export interface RhythmOptions {
   name?: string;
   type?: string;
   [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 = {}> {
   #private;
   constructor(options?: RhythmOptions);
-  use<TExtra extends object = {}>(fn: Middleware<TContext>): Rhythm<TInput, TContext & TExtra, TProviders>;
-  provide<TValue extends object>(factory: (deps: DeepReadonly<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: DeepReadonly<TRegContext>) => TExported): Rhythm<TInput, TContext & TExported, TProviders>;
+  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>>;
+  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>;
   callback(): (input: TInput) => Promise<TContext>;

package/dist/rhythm.js

@@ -1,50 +1,41 @@
+import { compose } from "./compose.js";
 //#region src/rhythm.ts
-const RhythmMutable = Symbol("RhythmMutable");
-function compose(middleware) {
-	if (!Array.isArray(middleware)) throw new TypeError("Middleware stack must be an array!");
-	for (const fn of middleware) if (typeof fn !== "function") throw new TypeError("Middleware must be composed of functions!");
-	return function(context, next) {
-		let index = -1;
-		return dispatch(0);
-		function dispatch(i) {
-			if (i <= index) return Promise.reject(/* @__PURE__ */ new Error("next() called multiple times"));
-			index = i;
-			const fn = i === middleware.length ? next : middleware[i];
-			if (!fn) return Promise.resolve(context);
-			const dispatchNext = ((extra) => {
-				if (extra) Object.assign(context, extra);
-				return dispatch(i + 1);
-			});
-			try {
-				const call = fn;
-				return Promise.resolve(call(context, dispatchNext)).then(() => context);
-			} catch (err) {
-				return Promise.reject(err);
-			}
-		}
+function publicEntries(value) {
+	const exported = {};
+	for (const [key, val] of Object.entries(value)) if (!key.startsWith("#")) exported[key] = val;
+	return exported;
+}
+function derive(fn) {
+	if (typeof fn !== "function") throw new TypeError("derive factory must be a function!");
+	const middleware = async (ctx, next) => {
+		const value = await fn(ctx);
+		Object.assign(ctx, publicEntries(value));
+		await next();
 	};
+	return middleware;
 }
 var Rhythm = class {
 	#middleware = [];
 	#options;
 	#providers = [];
 	#setupPromise = null;
-	#providedCache = null;
-	#composed = null;
-	#callbackFn = null;
 	constructor(options = {}) {
 		this.#options = options;
 	}
 	use(fn) {
 		if (typeof fn !== "function") throw new TypeError("middleware must be a function!");
 		this.#middleware.push(fn);
-		this.#invalidateCallback();
 		return this;
 	}
 	provide(factory, dispose) {
-		this.#providers.push({
+		const entry = {
 			factory,
 			dispose
+		};
+		this.#providers.push(entry);
+		this.#middleware.push(async (ctx, next) => {
+			Object.assign(ctx, publicEntries(entry.resolved));
+			await next();
 		});
 		return this;
 	}
@@ -65,15 +56,11 @@ var Rhythm = class {
 				const { type = "module", name = "anonymous" } = module.#options;
 				throw new Error(`registered ${type} "${name}" failed`, { cause });
 			}
-			await next(exportValue ? exportValue(result) : {});
+			if (exportValue) Object.assign(ctx, exportValue(result));
+			await next();
 		});
-		this.#invalidateCallback();
 		return this;
 	}
-	#invalidateCallback() {
-		this.#composed = null;
-		this.#callbackFn = null;
-	}
 	setup() {
 		if (!this.#setupPromise) this.#setupPromise = this.#resolveProviders().catch((err) => {
 			this.#setupPromise = null;
@@ -85,39 +72,34 @@ var Rhythm = class {
 		const resolved = {};
 		for (const entry of this.#providers) {
 			entry.resolved = await entry.factory(resolved);
-			for (const [key, value] of Object.entries(entry.resolved)) if (!key.startsWith("#")) resolved[key] = value;
+			Object.assign(resolved, publicEntries(entry.resolved));
 		}
-		this.#providedCache = resolved;
 	}
 	async teardown() {
-		for (const entry of [...this.#providers].reverse()) await entry.dispose?.(entry.resolved);
+		for (const entry of [...this.#providers].reverse()) {
+			if (entry.resolved === void 0) continue;
+			await entry.dispose?.(entry.resolved);
+			entry.resolved = void 0;
+		}
+		this.#setupPromise = null;
 	}
 	callback() {
-		if (!this.#callbackFn) {
-			if (!this.#composed) this.#composed = compose(this.#middleware);
-			const fn = this.#composed;
-			this.#callbackFn = async (input) => {
-				await this.setup();
-				return fn({
-					...this.#providedCache,
-					...input
-				});
-			};
-		}
-		return this.#callbackFn;
+		const fn = compose([...this.#middleware]);
+		return async (input) => {
+			await this.setup();
+			return fn({ ...input });
+		};
 	}
 	run(input) {
 		return this.callback()(input);
 	}
 	middleware() {
+		const fn = compose([...this.#middleware]);
 		return async (ctx, next) => {
 			await this.setup();
-			if (!this.#composed) this.#composed = compose(this.#middleware);
-			const context = ctx;
-			Object.assign(context, this.#providedCache);
-			await this.#composed(context, next);
+			await fn(ctx, next);
 		};
 	}
 };
 //#endregion
-export { Rhythm, RhythmMutable, compose };
+export { Rhythm, derive };

package/dist/types.d.ts

@@ -0,0 +1,8 @@
+//#region src/types.d.ts
+export type OmitHashKeys<T> = { [K in keyof T as K extends `#${string}` ? never : K]: T[K]; };
+export type NextFn<TContext extends object> = () => Promise<TContext>;
+export type Middleware<TContext extends object> = (ctx: TContext, next: NextFn<TContext>) => Promise<void> | void;
+export type DeriveMiddleware<TContext extends object, TExtra extends object> = Middleware<TContext> & {
+  readonly "~derive": TExtra;
+};
+//#endregion

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@rhythmjs/rhythm",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "A minimal, type-safe onion-middleware and provider composition kernel.",
+  "homepage": "https://rhythm.js.org/rhythm",
   "license": "ISC",
   "repository": {
     "type": "git",
@@ -18,6 +19,14 @@
       "types": "./dist/rhythm.d.ts",
       "default": "./dist/rhythm.js"
     },
+    "./compose": {
+      "types": "./dist/compose.d.ts",
+      "default": "./dist/compose.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.js"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -30,10 +39,5 @@
   },
   "engines": {
     "node": ">=20.19.0"
-  },
-  "scripts": {
-    "build": "vp pack",
-    "typecheck": "tsc --noEmit",
-    "test": "vp test"
   }
 }