@rhythmjs/rhythm 0.0.1

package/README.md

@@ -0,0 +1,67 @@
+# @rhythmjs/rhythm
+
+The core composition kernel `@rhythmjs/router` and `@rhythmjs/cli` are built on. Framework-agnostic — 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 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()`.
+- **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).
+
+## 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}`) },
+  }))
+  .use(async (ctx, next) => {
+    const startedAt = Date.now();
+    await next();
+    ctx.logger.info(`handled in ${Date.now() - startedAt}ms`);
+  })
+  .use((ctx) => {
+    ctx.logger.info(`hello, ${ctx.userId}`);
+  });
+
+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.
+
+### Module registration
+
+```ts
+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) });
+  });
+
+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.
+
+## 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.
+- `.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`.
+- `.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).
+- `.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

@@ -0,0 +1,30 @@
+//#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 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>;
+  setup(): Promise<void>;
+  teardown(): Promise<void>;
+  callback(): (input: TInput) => Promise<TContext>;
+  run(input: TInput): Promise<TContext>;
+  middleware(): Middleware<TContext>;
+}
+//#endregion

package/dist/rhythm.js

@@ -0,0 +1,123 @@
+//#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);
+			}
+		}
+	};
+}
+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({
+			factory,
+			dispose
+		});
+		return this;
+	}
+	register(other, exportValue) {
+		const module = other;
+		this.#providers.push({
+			factory: async () => {
+				await module.setup();
+				return {};
+			},
+			dispose: () => module.teardown()
+		});
+		this.#middleware.push(async (ctx, next) => {
+			let result;
+			try {
+				result = await module.run(ctx);
+			} catch (cause) {
+				const { type = "module", name = "anonymous" } = module.#options;
+				throw new Error(`registered ${type} "${name}" failed`, { cause });
+			}
+			await next(exportValue ? exportValue(result) : {});
+		});
+		this.#invalidateCallback();
+		return this;
+	}
+	#invalidateCallback() {
+		this.#composed = null;
+		this.#callbackFn = null;
+	}
+	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);
+			for (const [key, value] of Object.entries(entry.resolved)) if (!key.startsWith("#")) resolved[key] = value;
+		}
+		this.#providedCache = resolved;
+	}
+	async teardown() {
+		for (const entry of [...this.#providers].reverse()) await entry.dispose?.(entry.resolved);
+	}
+	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;
+	}
+	run(input) {
+		return this.callback()(input);
+	}
+	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);
+		};
+	}
+};
+//#endregion
+export { Rhythm, RhythmMutable, compose };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@rhythmjs/rhythm",
+  "version": "0.0.1",
+  "description": "A minimal, type-safe onion-middleware and provider composition kernel.",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rhythmjs/rhythm.git",
+    "directory": "packages/rhythm"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/rhythm.d.ts",
+      "default": "./dist/rhythm.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.3",
+    "typescript": "^7.0.2",
+    "vite-plus": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "typecheck": "tsc --noEmit",
+    "test": "vp test"
+  }
+}