@db3.ai/app 0.1.0-beta.1

package/src/db/test/db.ts

@@ -0,0 +1,159 @@
+import 'dotenv/config';
+import crypto from 'node:crypto';
+import knex, { type Knex } from 'knex';
+import {
+	rememberDatabaseDialect,
+	resolveDatabaseDialect,
+	type DatabaseDialect,
+} from '../dialects';
+
+type ConnectionInput = Knex.StaticConnectionConfig & {
+	database?: string;
+};
+
+export interface GeneratedTestDatabase {
+	readonly db: Knex;
+	readonly databaseName: string;
+	destroy(): Promise<void>;
+}
+
+const SAFE_DATABASE_NAME = /^[A-Za-z0-9_]+$/;
+
+/**
+ * Creates an isolated test database for the configured SQL dialect.
+ */
+export async function createGeneratedTestDatabase(
+	label = 'suite',
+): Promise<GeneratedTestDatabase> {
+	const databaseName = createDatabaseName(label);
+	const dialect = resolveDatabaseDialect();
+	const admin = createKnex(undefined, dialect);
+
+	try {
+		await dialect.createDatabase(admin, databaseName);
+
+		const db = createKnex(databaseName, dialect);
+
+		return {
+			db,
+			databaseName,
+			async destroy(): Promise<void> {
+				await db.destroy();
+				await dialect.dropDatabase(admin, databaseName);
+				await admin.destroy();
+			},
+		};
+	} catch (error) {
+		await admin.destroy();
+		throw error;
+	}
+}
+
+/**
+ * Creates a Knex connection bound to the configured test dialect.
+ */
+function createKnex(
+	databaseName?: string,
+	dialect = resolveDatabaseDialect(),
+): Knex {
+	const connection = knex({
+		client: dialect.knexClient,
+		connection: createConnection(databaseName, dialect),
+		pool: {
+			min: 0,
+			max: 2,
+		},
+	});
+
+	rememberDatabaseDialect(connection, dialect);
+
+	return connection;
+}
+
+/**
+ * Builds the test database connection object from environment variables.
+ */
+function createConnection(
+	databaseName?: string,
+	dialect = resolveDatabaseDialect(),
+): ConnectionInput {
+	if (process.env.DATABASE_URL) {
+		return connectionFromUrl(process.env.DATABASE_URL, databaseName, dialect);
+	}
+
+	return {
+		host: process.env.DB_HOST || '127.0.0.1',
+		port: Number(process.env.DB_PORT || dialect.defaultPort),
+		user: process.env.DB_USER || 'root',
+		password: process.env.DB_PASSWORD || '',
+		database: databaseName,
+	};
+}
+
+/**
+ * Parses a database URL while allowing the generated database name to override it.
+ */
+function connectionFromUrl(
+	databaseUrl: string,
+	databaseName?: string,
+	dialect = resolveDatabaseDialect(),
+): ConnectionInput {
+	const url = new URL(databaseUrl);
+
+	return {
+		host: url.hostname,
+		port: Number(url.port || dialect.defaultPort),
+		user: decodeURIComponent(url.username),
+		password: decodeURIComponent(url.password),
+		database: databaseName,
+	};
+}
+
+/**
+ * Creates a safe generated database name for an integration test suite.
+ */
+function createDatabaseName(label: string): string {
+	const prefix = process.env.DB_TEST_DATABASE_PREFIX || 'db3_app_test';
+	const suffix = label.replace(/[^A-Za-z0-9_]+/g, '_').replace(/^_+|_+$/g, '');
+	const random = crypto.randomUUID().replace(/-/g, '').slice(0, 12);
+	const databaseName = `${prefix}_${process.pid}_${suffix || 'suite'}_${random}`;
+
+	assertSafeGeneratedDatabaseName(databaseName);
+
+	return databaseName.slice(0, 64);
+}
+
+/**
+ * Guards generated database names before create/drop SQL is executed.
+ */
+function assertSafeGeneratedDatabaseName(databaseName: string): void {
+	const appDatabaseName = getAppDatabaseName();
+
+	if (!SAFE_DATABASE_NAME.test(databaseName)) {
+		throw new Error(`Unsafe test database name "${databaseName}".`);
+	}
+
+	if (!databaseName.toLowerCase().includes('test')) {
+		throw new Error(
+			`Refusing to manage database "${databaseName}" because it does not contain "test".`,
+		);
+	}
+
+	if (appDatabaseName && databaseName === appDatabaseName) {
+		throw new Error(
+			`Refusing to manage test database "${databaseName}" because it matches DB_DATABASE.`,
+		);
+	}
+}
+
+/**
+ * Resolves the configured application database name for destructive safety checks.
+ */
+function getAppDatabaseName(): string | null {
+	if (process.env.DATABASE_URL) {
+		const url = new URL(process.env.DATABASE_URL);
+		return url.pathname.replace(/^\//, '') || null;
+	}
+
+	return process.env.DB_DATABASE || null;
+}

package/src/devtools/HttpEventDispatcher.ts

@@ -0,0 +1,214 @@
+import type * as devtools from './contracts/index.js';
+
+const defaultBatchSize = 25;
+const defaultFlushIntervalMs = 100;
+const defaultRetryAfterMs = 1000;
+const defaultRequestTimeoutMs = 1000;
+const defaultMaxPendingEvents = 1000;
+
+/**
+ * Builds the configured development event ingestion endpoint.
+ *
+ * @param env - Environment values controlling the devtools service address.
+ * @returns Absolute HTTP endpoint for event batches.
+ */
+export function devtoolsEventsUrl(
+	env: devtools.DevtoolsEnvironment = process.env,
+): string {
+	if (env.PLATFORM_DEVTOOLS_EVENTS_URL) {
+		return env.PLATFORM_DEVTOOLS_EVENTS_URL;
+	}
+
+	const host = env.PLATFORM_DEVTOOLS_HOST || '127.0.0.1';
+	const port = env.PLATFORM_DEVTOOLS_API_PORT || '9998';
+
+	return `http://${host}:${port}/api/events`;
+}
+
+/**
+ * Creates a bounded, fire-and-forget HTTP dispatcher for framework events.
+ *
+ * Events are batched off the caller's stack. Failed batches are discarded and
+ * subsequent delivery pauses briefly, keeping development instrumentation from
+ * affecting application behavior when the event service is unavailable.
+ *
+ * @param options - Batching, endpoint, timeout, and test-fetch configuration.
+ * @returns Callable dispatcher with flush and close lifecycle methods.
+ */
+export function createHttpEventDispatcher<TEvent extends object>(
+	options: devtools.HttpEventDispatcherOptions = {},
+): devtools.DevtoolsEventDispatcher<TEvent> {
+	const url = options.url ?? devtoolsEventsUrl();
+	const batchSize = positiveInteger(options.batchSize, defaultBatchSize);
+	const flushIntervalMs = positiveInteger(options.flushIntervalMs, defaultFlushIntervalMs);
+	const retryAfterMs = positiveInteger(options.retryAfterMs, defaultRetryAfterMs);
+	const requestTimeoutMs = positiveInteger(options.requestTimeoutMs, defaultRequestTimeoutMs);
+	const maxPendingEvents = positiveInteger(options.maxPendingEvents, defaultMaxPendingEvents);
+	const fetchImpl = options.fetch ?? fetch;
+	const queue: TEvent[] = [];
+	let timer: ReturnType<typeof setTimeout> | null = null;
+	let inFlight: Promise<boolean> | null = null;
+	let disabledUntil = 0;
+	let closed = false;
+
+	/**
+	 * Clears the scheduled batch timer.
+	 */
+	function clearScheduledFlush(): void {
+		if (!timer) return;
+
+		clearTimeout(timer);
+		timer = null;
+	}
+
+	/**
+	 * Schedules delivery without keeping an otherwise idle process alive.
+	 *
+	 * @param delayMs - Delay before the next delivery attempt.
+	 */
+	function schedule(delayMs = flushIntervalMs): void {
+		if (closed || timer || queue.length === 0) return;
+
+		timer = setTimeout(() => {
+			timer = null;
+			void flushNext();
+		}, delayMs);
+		timer.unref?.();
+	}
+
+	/**
+	 * Posts one batch and reports whether it was accepted.
+	 *
+	 * @param ignoreBackoff - Whether shutdown should bypass the retry pause.
+	 * @returns True on accepted delivery and false when delivery was skipped or failed.
+	 */
+	async function sendNextBatch(ignoreBackoff: boolean): Promise<boolean> {
+		if (queue.length === 0) return true;
+
+		const now = Date.now();
+
+		if (!ignoreBackoff && now < disabledUntil) {
+			schedule(Math.max(flushIntervalMs, disabledUntil - now));
+			return false;
+		}
+
+		const batch = queue.splice(0, batchSize);
+		const controller = new AbortController();
+		const requestTimeout = setTimeout(() => {
+			controller.abort();
+		}, requestTimeoutMs);
+		requestTimeout.unref?.();
+
+		try {
+			const response = await fetchImpl(url, {
+				method: 'POST',
+				headers: {
+					'content-type': 'application/json',
+					...options.headers,
+				},
+				body: JSON.stringify({
+					events: batch,
+				}),
+				signal: controller.signal,
+			});
+
+			if (!response.ok) {
+				throw new Error(`Devtools event sink returned ${response.status}.`);
+			}
+
+			return true;
+		} catch (_error) {
+			disabledUntil = Date.now() + retryAfterMs;
+			return false;
+		} finally {
+			clearTimeout(requestTimeout);
+		}
+	}
+
+	/**
+	 * Serializes delivery attempts so batches cannot overtake one another.
+	 *
+	 * @param ignoreBackoff - Whether to bypass a previous failure pause.
+	 * @returns True when the attempted batch was accepted.
+	 */
+	async function flushNext(ignoreBackoff = false): Promise<boolean> {
+		clearScheduledFlush();
+
+		while (inFlight) {
+			await inFlight;
+		}
+
+		if (queue.length === 0) return true;
+
+		inFlight = sendNextBatch(ignoreBackoff);
+
+		try {
+			return await inFlight;
+		} finally {
+			inFlight = null;
+
+			if (!closed && queue.length > 0) {
+				schedule();
+			}
+		}
+	}
+
+	const dispatch = ((event: TEvent): void => {
+		if (closed) return;
+
+		queue.push(event);
+
+		while (queue.length > maxPendingEvents) {
+			queue.shift();
+		}
+
+		if (queue.length >= batchSize) {
+			void flushNext();
+			return;
+		}
+
+		schedule();
+	}) as devtools.DevtoolsEventDispatcher<TEvent>;
+
+	dispatch.flush = async (): Promise<void> => {
+		await flushNext();
+	};
+
+	dispatch.close = async (): Promise<void> => {
+		if (closed) return;
+
+		closed = true;
+		clearScheduledFlush();
+
+		if (inFlight) {
+			await inFlight;
+		}
+
+		while (queue.length > 0) {
+			const sent = await flushNext(true);
+
+			if (!sent) {
+				queue.length = 0;
+				break;
+			}
+		}
+	};
+
+	return dispatch;
+}
+
+/**
+ * Returns a positive integer or a safe fallback.
+ *
+ * @param input - Caller-provided numeric option.
+ * @param fallback - Value used for invalid input.
+ * @returns Normalized positive integer.
+ */
+function positiveInteger(
+	input: number | undefined,
+	fallback: number,
+): number {
+	if (!Number.isFinite(input) || Number(input) <= 0) return fallback;
+
+	return Math.floor(Number(input));
+}

package/src/devtools/contracts/DevtoolsEventDispatcher.ts

@@ -0,0 +1,57 @@
+/**
+ * Environment values shared by framework instrumentation that streams events
+ * to the local development service.
+ */
+export interface DevtoolsEnvironment {
+	NODE_ENV?: string;
+	PLATFORM_DEVTOOLS_API_PORT?: string;
+	PLATFORM_DEVTOOLS_EVENTS_URL?: string;
+	PLATFORM_DEVTOOLS_HOST?: string;
+}
+
+/**
+ * Configuration for a bounded, best-effort HTTP event dispatcher.
+ */
+export interface HttpEventDispatcherOptions {
+	/** HTTP endpoint that accepts `{ events: [...] }` JSON batches. */
+	url?: string;
+	/** Maximum events sent in one request. */
+	batchSize?: number;
+	/** Maximum time an event waits before its batch is sent. */
+	flushIntervalMs?: number;
+	/** Pause before later batches are attempted after a failed request. */
+	retryAfterMs?: number;
+	/** Maximum time allowed for one ingestion request. */
+	requestTimeoutMs?: number;
+	/** Maximum unsent events retained before the oldest event is discarded. */
+	maxPendingEvents?: number;
+	/** Additional HTTP headers included with every ingestion request. */
+	headers?: Record<string, string>;
+	/** Fetch implementation used by tests or alternate runtimes. */
+	fetch?: typeof fetch;
+}
+
+/**
+ * Callable event sink with explicit flushing and shutdown lifecycle controls.
+ *
+ * Delivery is intentionally best-effort: a failed batch is discarded so
+ * development instrumentation cannot hold an application process open.
+ */
+export interface DevtoolsEventDispatcher<TEvent extends object> {
+	/**
+	 * Queues one event for asynchronous delivery.
+	 *
+	 * @param event - Structured framework event to send.
+	 */
+	(event: TEvent): void;
+
+	/**
+	 * Sends the next pending batch when the dispatcher is available.
+	 */
+	flush(): Promise<void>;
+
+	/**
+	 * Stops accepting events and attempts to drain the bounded queue.
+	 */
+	close(): Promise<void>;
+}

package/src/devtools/contracts/index.ts

@@ -0,0 +1 @@
+export * from './DevtoolsEventDispatcher';

package/src/devtools/environment.ts

@@ -0,0 +1,18 @@
+import { isDevelopmentEnvironment } from '@db3.ai/pure';
+
+/**
+ * Returns whether instrumentation should automatically stream to local
+ * development tooling.
+ *
+ * Tests are excluded because they should opt into transports explicitly.
+ *
+ * @param environment - Current runtime environment name.
+ * @returns True for interactive local development environments.
+ */
+export function isInteractiveDevelopmentEnvironment(
+	environment: string | undefined,
+): boolean {
+	const normalized = (environment || '').toLowerCase().trim();
+
+	return normalized !== 'test' && isDevelopmentEnvironment(normalized);
+}

package/src/devtools/index.ts

@@ -0,0 +1,3 @@
+export * from './contracts';
+export * from './environment';
+export * from './HttpEventDispatcher';

package/src/events/Events.ts

@@ -0,0 +1,165 @@
+import type * as events from './contracts';
+
+type StoredEventListener = events.EventListener<object>;
+
+/**
+ * Typed in-process dispatcher for application and framework events.
+ *
+ * Event classes are runtime keys, so listeners infer the correct event shape
+ * without requiring a global string-to-payload registry. Dispatch is
+ * intentionally synchronous from the caller's perspective: listeners run in
+ * registration order and asynchronous listeners are awaited.
+ *
+ * @example
+ * const unsubscribe = app().events.listen(WebsiteCrawled, async event => {
+ * 	await indexWebsite(event.websiteId);
+ * });
+ *
+ * await app().events.dispatch(new WebsiteCrawled(websiteId));
+ * unsubscribe();
+ */
+export class Events {
+	readonly #listeners = new Map<
+		events.EventConstructor,
+		Set<StoredEventListener>
+	>();
+
+	/**
+	 * Registers a listener for exactly one event class.
+	 *
+	 * Subclasses are independent event types and do not automatically invoke
+	 * listeners registered for a parent class.
+	 *
+	 * @param eventType - Event class used as the listener key.
+	 * @param listener - Consumer invoked for subsequent event instances.
+	 * @returns Idempotent function that removes this registration.
+	 */
+	listen<TEvent extends object>(
+		eventType: events.EventConstructor<TEvent>,
+		listener: events.EventListener<TEvent>,
+	): events.EventUnsubscribe {
+		const key: events.EventConstructor = eventType;
+		const listeners = this.#listeners.get(key) ?? new Set<StoredEventListener>();
+		const storedListener: StoredEventListener = event => {
+			return listener(event as TEvent);
+		};
+		let subscribed = true;
+
+		listeners.add(storedListener);
+		this.#listeners.set(key, listeners);
+
+		return () => {
+			if (!subscribed) return;
+
+			subscribed = false;
+			listeners.delete(storedListener);
+
+			if (listeners.size === 0) {
+				this.#listeners.delete(key);
+			}
+		};
+	}
+
+	/**
+	 * Registers a listener that removes itself before its first invocation.
+	 *
+	 * Removing the registration before calling the listener guarantees that
+	 * overlapping dispatches cannot invoke the one-shot listener twice.
+	 *
+	 * @param eventType - Event class used as the listener key.
+	 * @param listener - Consumer invoked at most once.
+	 * @returns Idempotent function that removes the pending registration.
+	 */
+	once<TEvent extends object>(
+		eventType: events.EventConstructor<TEvent>,
+		listener: events.EventListener<TEvent>,
+	): events.EventUnsubscribe {
+		let unsubscribe: events.EventUnsubscribe = () => {};
+		const oneShotListener: events.EventListener<TEvent> = event => {
+			unsubscribe();
+
+			return listener(event);
+		};
+
+		unsubscribe = this.listen(eventType, oneShotListener);
+
+		return unsubscribe;
+	}
+
+	/**
+	 * Dispatches one class instance to its current listeners.
+	 *
+	 * Listeners run sequentially in registration order. If a listener throws or
+	 * rejects, dispatch rejects immediately and later listeners are not invoked.
+	 * Callers therefore control whether listener completion is part of their
+	 * operation or should be delegated to a durable queued job.
+	 *
+	 * @param event - Class instance containing event data.
+	 */
+	async dispatch<TEvent extends object>(event: TEvent): Promise<void> {
+		const eventType = eventConstructor(event);
+		const listeners = this.#listeners.get(eventType);
+
+		if (!listeners) return;
+
+		for (const listener of [...listeners]) {
+			await listener(event);
+		}
+	}
+
+	/**
+	 * Returns whether an event class currently has one or more listeners.
+	 *
+	 * @param eventType - Exact event class to inspect.
+	 * @returns True when at least one listener is registered.
+	 */
+	hasListeners<TEvent extends object>(
+		eventType: events.EventConstructor<TEvent>,
+	): boolean {
+		return (this.#listeners.get(eventType)?.size ?? 0) > 0;
+	}
+
+	/**
+	 * Removes every listener registered for one event class.
+	 *
+	 * @param eventType - Exact event class whose registrations should be removed.
+	 */
+	forget<TEvent extends object>(
+		eventType: events.EventConstructor<TEvent>,
+	): void {
+		this.#listeners.delete(eventType);
+	}
+
+	/**
+	 * Removes all listener registrations owned by this dispatcher.
+	 */
+	clear(): void {
+		this.#listeners.clear();
+	}
+}
+
+/**
+ * Resolves and validates the exact runtime class for an event instance.
+ *
+ * Plain objects are rejected because every object literal shares the `Object`
+ * constructor and would therefore collapse unrelated event types together.
+ *
+ * @param event - Candidate event instance.
+ * @returns Concrete class token used to look up listeners.
+ */
+function eventConstructor<TEvent extends object>(
+	event: TEvent,
+): events.EventConstructor<TEvent> {
+	const prototype = Object.getPrototypeOf(event) as {
+		constructor?: unknown;
+	} | null;
+	const eventType = prototype?.constructor;
+
+	if (typeof eventType !== 'function' || eventType === Object) {
+		throw new TypeError(
+			'Events must be class instances. Define an event class and dispatch a new instance.',
+		);
+	}
+
+	return eventType as unknown as events.EventConstructor<TEvent>;
+}