@db3.ai/app 0.1.0-beta.1

package/src/events/README.md

@@ -0,0 +1,106 @@
+# Events
+
+`@db3.ai/app/events` provides the typed, in-process event dispatcher exposed
+through `app().events`. It is intended for application events and small
+cross-cutting reactions without coupling the producer to each listener.
+
+## Run a note event
+
+Complete [Installation](https://db3.ai/docs/installation), then run this from your independent application:
+
+```sh
+mkdir -p examples
+cp -R node_modules/@db3.ai/app/src/events/examples/. examples/
+npx tsx examples/runNoteEvents.ts
+```
+
+Expect the trace `index:one`, `first:one`, `index:two`, `after:four`, with `rejected: true` and `hasListeners: false`. The third dispatch fails before its later listener. The example removes the failing listener and dispatches a new event. It has no database, side-effecting indexer or durable worker.
+
+Copy the exact test from [Events](https://db3.ai/docs/events#testing) into `tests/events/runNoteEvents.test.ts` and run:
+
+```sh
+npx vitest run tests/events/runNoteEvents.test.ts
+npx tsc --noEmit --target ES2022 --module ESNext --moduleResolution Bundler --types node --skipLibCheck examples/*.ts
+```
+
+The tests use the real dispatcher and cover every service method, exact-class identity, async ordering, failure propagation and cleanup. See the [complete contract reference](https://db3.ai/docs/events-api) for listener and constructor types.
+
+## Defining And Dispatching Events
+
+Events are normal classes containing application data. Prefer past-tense names
+that describe something that has already happened:
+
+```ts
+class WebsiteCrawled {
+	constructor(
+		readonly websiteId: string,
+		readonly crawlId: string,
+	) {}
+}
+```
+
+Register listeners during application boot, then dispatch an instance:
+
+```ts
+const unsubscribe = app().events.listen(WebsiteCrawled, async event => {
+	await updateSearchIndex(event.websiteId);
+});
+
+await app().events.dispatch(new WebsiteCrawled(websiteId, crawlId));
+
+unsubscribe();
+```
+
+The event class is the runtime listener key and gives the callback its inferred
+event type. Listeners registered for a parent class do not receive subclass
+instances.
+
+Use `once(...)` for a one-shot listener:
+
+```ts
+app().events.once(WebsiteCrawled, event => {
+	app().log.info({
+		websiteId: event.websiteId,
+	}, 'Observed the first completed crawl');
+});
+```
+
+`hasListeners(EventClass)`, `forget(EventClass)`, and `clear()` are available
+for bootstrapping, tests, and explicit teardown. `App.close()` automatically
+clears listeners created through `app().events`.
+
+## Execution And Errors
+
+`dispatch(...)` invokes the listeners present when dispatch begins, in
+registration order. It awaits each asynchronous listener before starting the
+next listener.
+
+If a listener throws or rejects, dispatch rejects and later listeners are not
+run. This makes failure visible to the producer and avoids silently losing
+required application work. Catch the error at the producer only when that
+failure is intentionally non-fatal.
+
+Earlier listeners may already have made changes; there is no rollback. Do not replay a whole dispatch without considering duplicate side effects. The listener list is captured when dispatch begins, so unsubscribing does not cancel callbacks already in that snapshot.
+
+Event data is not cloned. Every listener receives the same instance, so event
+classes should normally be immutable data objects.
+
+## Process And Durability Boundary
+
+Framework events are process-local and in-memory:
+
+- They are not persisted.
+- They do not cross API, queue-worker, or scheduler processes.
+- They are lost if the process exits before dispatch completes.
+- They do not retry failed listeners.
+
+Use the queue for durable, retryable, delayed, or cross-process work. A simple
+event listener can dispatch a queued job when an event should trigger that kind
+of work.
+
+A database commit followed by event dispatch is not an atomic outbox. Design a transaction/reconciliation boundary explicitly when a durable handoff cannot be lost.
+
+Queue lifecycle events remain a separate typed stream because they describe
+queue-driver transitions and intentionally isolate observer failures from
+already-completed queue operations. Logs also remain observability records;
+they must not be used to trigger application behavior.

package/src/events/contracts/EventConstructor.ts

@@ -0,0 +1,12 @@
+/**
+ * Runtime class token used to register a listener for one event type.
+ *
+ * The constructor is used only as an identity key. Applications create and
+ * dispatch their event instances themselves.
+ */
+export interface EventConstructor<TEvent extends object = object> {
+	/** Human-readable class name used in diagnostics and tooling. */
+	readonly name: string;
+	/** Event instance shape represented by this class token. */
+	readonly prototype: TEvent;
+}

package/src/events/contracts/EventListener.ts

@@ -0,0 +1,8 @@
+/**
+ * Synchronous or asynchronous consumer of one application event type.
+ *
+ * @param event - Event instance dispatched by application or framework code.
+ */
+export type EventListener<TEvent extends object> = (
+	event: TEvent,
+) => void | Promise<void>;

package/src/events/contracts/EventUnsubscribe.ts

@@ -0,0 +1,4 @@
+/**
+ * Idempotent function that removes one event listener registration.
+ */
+export type EventUnsubscribe = () => void;

package/src/events/contracts/index.ts

@@ -0,0 +1,3 @@
+export * from './EventConstructor';
+export * from './EventListener';
+export * from './EventUnsubscribe';

package/src/events/examples/NoteSaved.ts

@@ -0,0 +1,9 @@
+/** Immutable notification that one application note has already been saved. */
+export class NoteSaved {
+	/**
+	 * Carries identifiers rather than a request, model connection or mutable service.
+	 * @param noteId - Saved note identity.
+	 * @param ownerId - Authorized owner identity determined by the producer.
+	 */
+	constructor(readonly noteId: string, readonly ownerId: string) {}
+}

package/src/events/examples/runNoteEvents.ts

@@ -0,0 +1,31 @@
+import { pathToFileURL } from 'node:url';
+import { Events } from '@db3.ai/app/events';
+import { NoteSaved } from './NoteSaved';
+
+/**
+ * Exercises ordered listeners, one-shot observation, failure and explicit repair.
+ * @returns The dispatch trace and teardown state; no durable side effect is made.
+ */
+export async function runNoteEvents() {
+	const events = new Events();
+	const trace: string[] = [];
+	try {
+		const unsubscribe = events.listen(NoteSaved, async event => { await Promise.resolve(); trace.push(`index:${event.noteId}`); });
+		events.once(NoteSaved, event => { trace.push(`first:${event.noteId}`); });
+		await events.dispatch(new NoteSaved('one', 'ada'));
+		await events.dispatch(new NoteSaved('two', 'ada'));
+		unsubscribe();
+		const removeFailure = events.listen(NoteSaved, () => { throw new Error('Reaction failed'); });
+		events.listen(NoteSaved, event => { trace.push(`after:${event.noteId}`); });
+		let rejected = false;
+		try { await events.dispatch(new NoteSaved('three', 'ada')); } catch { rejected = true; }
+		removeFailure();
+		await events.dispatch(new NoteSaved('four', 'ada'));
+		events.forget(NoteSaved);
+		return { trace, rejected, hasListeners: events.hasListeners(NoteSaved) };
+	} finally {
+		events.clear();
+	}
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) console.log(JSON.stringify(await runNoteEvents(), null, 2));

package/src/events/index.ts

@@ -0,0 +1,2 @@
+export * from './contracts';
+export * from './Events';

package/src/flows/FlowBlockRegistry.ts

@@ -0,0 +1,79 @@
+import type { FlowBlockDefinition, FlowBlockMetadata } from './contracts';
+
+/**
+ * Runtime registry resolving serialized block type names into executable functions.
+ */
+export class FlowBlockRegistry {
+	readonly #blocks = new Map<string, FlowBlockDefinition>();
+
+	/**
+	 * Creates a registry and optionally registers initial block types.
+	 *
+	 * @param blocks - Block definitions available to the runtime.
+	 */
+	constructor(blocks: FlowBlockDefinition[] = []) {
+		for (const block of blocks) {
+			this.register(block);
+		}
+	}
+
+	/**
+	 * Registers one executable block type.
+	 *
+	 * @param block - Block definition to register.
+	 */
+	register(block: FlowBlockDefinition): void {
+		const type = block.type.trim();
+
+		if (!type) {
+			throw new Error('Flow block type is required.');
+		}
+
+		if (this.#blocks.has(type)) {
+			throw new Error(`Flow block type "${type}" is already registered.`);
+		}
+
+		if ((block.kind ?? 'function') === 'function' && typeof block.run !== 'function') {
+			throw new Error(`Function flow block type "${type}" requires a run function.`);
+		}
+
+		this.#blocks.set(type, block);
+	}
+
+	/**
+	 * Resolves one registered block type.
+	 *
+	 * @param type - Serialized block type name.
+	 * @returns Registered block definition or null.
+	 */
+	get(type: string): FlowBlockDefinition | null {
+		return this.#blocks.get(type) ?? null;
+	}
+
+	/**
+	 * Resolves one block type or throws a developer-facing error.
+	 *
+	 * @param type - Serialized block type name.
+	 * @returns Registered block definition.
+	 */
+	require(type: string): FlowBlockDefinition {
+		const block = this.get(type);
+
+		if (!block) {
+			throw new Error(`Flow block type "${type}" is not registered.`);
+		}
+
+		return block;
+	}
+
+	/**
+	 * Returns serializable metadata for block palettes and inspectors.
+	 *
+	 * @returns Registered block metadata ordered by display name.
+	 */
+	metadata(): FlowBlockMetadata[] {
+		return [...this.#blocks.values()]
+			.map(({ run: _run, ...metadata }) => metadata)
+			.sort((a, b) => a.name.localeCompare(b.name));
+	}
+}