@db3.ai/app 0.1.0-beta.1

package/src/serialization/contracts/SerializableClass.ts

@@ -0,0 +1,26 @@
+import type { Serializable } from '../Serializable';
+
+/**
+ * Constructor for a registered object whose complete runtime state is exposed
+ * through `toJSON()`.
+ *
+ * @template TState - Complete constructor state owned by the class.
+ * @template TInstance - Concrete serializable instance.
+ */
+export interface SerializableClass<
+	TState = any,
+	TInstance extends Serializable<TState> = Serializable<TState>,
+> {
+	/** Runtime class name used only for diagnostics. */
+	readonly name: string;
+
+	/** Exact instance prototype associated with this constructor. */
+	readonly prototype: TInstance;
+
+	/**
+	 * Reconstructs an instance from fully restored constructor state.
+	 *
+	 * @param state - State previously returned by the instance's `toJSON()` method.
+	 */
+	new(state: TState): TInstance;
+}

package/src/serialization/contracts/SerializedValue.ts

@@ -0,0 +1,71 @@
+/**
+ * Stable marker identifying framework serializer payloads.
+ */
+export const SERIALIZED_VALUE_FORMAT = 'platform.serialized-object' as const;
+
+/**
+ * Current framework serializer wire-format version.
+ */
+export const SERIALIZED_VALUE_VERSION = 1 as const;
+
+/**
+ * Reserved object key used only for framework-owned serialized references.
+ *
+ * Application constructor state cannot use this key because it would be
+ * ambiguous with framework metadata during restoration.
+ */
+export const SERIALIZED_REFERENCE_KEY = '$platform' as const;
+
+/**
+ * Marker value identifying one serialized ActiveRecord reference.
+ */
+export const SERIALIZED_ACTIVE_RECORD_TYPE = 'active-record' as const;
+
+/**
+ * Primitive values supported by ordinary JSON without coercion.
+ */
+export type SerializedPrimitive = null | string | boolean | number;
+
+/**
+ * Registered ActiveRecord identity stored inside otherwise ordinary JSON.
+ */
+export interface SerializedActiveRecordReference {
+	/** Reserved framework reference discriminator. */
+	[SERIALIZED_REFERENCE_KEY]: typeof SERIALIZED_ACTIVE_RECORD_TYPE;
+	/** Stable application-registered model key. */
+	model: string;
+	/** JSON-safe logical primary-key value. */
+	id: string | number;
+}
+
+/**
+ * Plain serialized object containing application-owned constructor state.
+ */
+export interface SerializedObject {
+	[key: string]: SerializedValue;
+}
+
+/**
+ * JSON value supported inside serialized constructor state.
+ *
+ * ActiveRecord references are the only framework-specific extension.
+ */
+export type SerializedValue =
+	| SerializedPrimitive
+	| SerializedValue[]
+	| SerializedObject
+	| SerializedActiveRecordReference;
+
+/**
+ * Versioned root-class envelope produced by `Serializer.serialize()`.
+ */
+export interface SerializedValueEnvelope extends Record<string, unknown> {
+	/** Stable framework serializer format marker. */
+	format: typeof SERIALIZED_VALUE_FORMAT;
+	/** Wire-format version used to interpret the constructor state. */
+	version: typeof SERIALIZED_VALUE_VERSION;
+	/** Stable registry key for the root application class. */
+	name: string;
+	/** Serialized constructor state for the registered root class. */
+	state: SerializedValue;
+}

package/src/serialization/contracts/SerializerOptions.ts

@@ -0,0 +1,19 @@
+import type { ActiveRecordClass } from '../../db';
+import type { SerializableClass } from './SerializableClass';
+
+/**
+ * Framework serializer configuration supplied when creating an application.
+ */
+export interface SerializerOptions {
+	/**
+	 * Stable class keys mapped to constructors that accept their `toJSON()` state.
+	 */
+	classes?: Record<string, SerializableClass>;
+
+	/**
+	 * ActiveRecord models available for identity-based restoration.
+	 *
+	 * Explicit stable keys keep durable payloads independent of table names.
+	 */
+	models?: Record<string, ActiveRecordClass>;
+}

package/src/serialization/contracts/SerializerService.ts

@@ -0,0 +1,29 @@
+import type { SerializationRegistry } from '../SerializationRegistry';
+import type { Serializable } from '../Serializable';
+import type { SerializedValueEnvelope } from './SerializedValue';
+
+/**
+ * Application serializer service for durable constructor-backed objects.
+ */
+export interface SerializerService {
+	/** Application-scoped registered serializable classes and ActiveRecord models. */
+	readonly registry: SerializationRegistry;
+
+	/**
+	 * Converts one registered object into a JSON-safe versioned envelope.
+	 *
+	 * @param value - Registered object whose `toJSON()` state should be serialized.
+	 * @returns JSON-safe serialized value envelope.
+	 */
+	serialize(value: Serializable): SerializedValueEnvelope;
+
+	/**
+	 * Restores one previously serialized registered object.
+	 *
+	 * ActiveRecord restoration makes this operation asynchronous.
+	 *
+	 * @param payload - Unknown payload to validate and deserialize.
+	 * @returns Restored registered object.
+	 */
+	deserialize<TInstance extends Serializable = Serializable>(payload: unknown): Promise<TInstance>;
+}

package/src/serialization/contracts/index.ts

@@ -0,0 +1,4 @@
+export * from './SerializableClass';
+export * from './SerializedValue';
+export * from './SerializerOptions';
+export * from './SerializerService';

package/src/serialization/examples/ExportRequest.ts

@@ -0,0 +1,25 @@
+import type { Serializable } from '@db3.ai/app/serialization';
+
+/** Durable, explicitly versioned application state for a bounded export. */
+export interface ExportRequestState {
+	/** Application contract version, separate from the framework envelope version. */
+	version: 1;
+	/** Validated scalar identity; the worker must authorize its own data reads. */
+	ownerId: string;
+	/** Maximum number of records requested for the export. */
+	limit: number;
+}
+
+/** A registered root that validates the same state on direct and restored construction. */
+export class ExportRequest implements Serializable<ExportRequestState> {
+	readonly #state: ExportRequestState;
+	/** Validates all state needed to recreate this request in a worker. */
+	constructor(state: ExportRequestState) {
+		if (!state || state.version !== 1 || typeof state.ownerId !== 'string' || !state.ownerId.trim() || !Number.isInteger(state.limit) || state.limit < 1 || state.limit > 100) throw new Error('ExportRequest requires version 1, an owner and limit 1–100.');
+		this.#state = { version: 1, ownerId: state.ownerId.trim(), limit: state.limit };
+	}
+	/** Returns plain constructor state, never a request, connection or service. */
+	toJSON(): ExportRequestState { return { ...this.#state }; }
+	/** Demonstrates private state was initialized by the restored constructor. */
+	label(): string { return `${this.#state.ownerId}:${this.#state.limit}`; }
+}

package/src/serialization/examples/runExportSerialization.ts

@@ -0,0 +1,24 @@
+import { pathToFileURL } from 'node:url';
+import { SerializationError, Serializer } from '@db3.ai/app/serialization';
+import { App } from '@db3.ai/app/server';
+import { ExportRequest } from './ExportRequest';
+
+/** Exercises the JSON boundary, unknown registration, invalid state and recovery. */
+export async function runExportSerialization() {
+	const application = new App({ serializer: { classes: { 'notes.export.v1': ExportRequest } } });
+	try {
+		const payload = application.serializer.serialize(new ExportRequest({ version: 1, ownerId: 'ada', limit: 25 }));
+		const durable = JSON.parse(JSON.stringify(payload));
+		const restored = await application.serializer.deserialize<ExportRequest>(durable);
+		const worker = new Serializer();
+		let unknownRejected = false;
+		try { await worker.deserialize(durable); } catch (error) { if (!(error instanceof SerializationError)) throw error; unknownRejected = true; }
+		worker.registry.registerClass('notes.export.v1', ExportRequest);
+		let invalidStateRejected = false;
+		try { await worker.deserialize({ ...durable, state: { ...durable.state, limit: 0 } }); } catch (error) { if (!(error instanceof SerializationError)) throw error; invalidStateRejected = true; }
+		const repaired = await worker.deserialize<ExportRequest>(durable);
+		return { label: restored.label(), privateStateRestored: restored instanceof ExportRequest, format: payload.format, wireVersion: payload.version, unknownRejected, invalidStateRejected, repaired: repaired.label() };
+	} finally { await application.close(); }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) console.log(JSON.stringify(await runExportSerialization(), null, 2));

package/src/serialization/index.ts

@@ -0,0 +1,6 @@
+export * from './contracts';
+export * from './Serializable';
+export * from './SerializationError';
+export * from './SerializationRegistry';
+export * from './SerializationRegistryError';
+export * from './Serializer';

package/src/server/App.ts

@@ -0,0 +1,326 @@
+import type { Knex } from 'knex';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Ai, type AIOptions } from '../ai';
+
+import {
+	Auth,
+	type AuthOptions,
+} from '../auth';
+import {
+	Cache,
+	type CacheOptions,
+} from '../cache';
+import {
+	Config,
+	type ConfigValues,
+} from '../config';
+import {
+	db as defaultDb,
+	destroyDatabase,
+} from '../db/connection';
+import {
+	Database,
+	type DatabaseOptions,
+} from '../db';
+import { Events } from '../events';
+import { UrlGenerator, type UrlGeneratorOptions } from '../url';
+import {
+	Queue,
+	type QueueOptions,
+} from '../queue';
+import {
+	Log,
+	type LoggingOptions,
+} from '../logging';
+import {
+	Storage,
+	type StorageOptions,
+} from '../storage';
+import { Scheduler } from '../scheduler';
+import { Security } from '../security';
+import { Serializer, type SerializerOptions } from '../serialization';
+import { MediaManager, type MediaOptions } from '../media';
+import { RequestContext } from './RequestContext';
+import {
+	clearActiveApp,
+	setActiveApp,
+} from './appContext';
+
+/** Application root, service configuration and optional dependencies supplied at bootstrap. */
+export interface AppOptions {
+	/** App root as a path or file URL; defaults to the working directory at construction. */
+	directory?: string | URL;
+	/** Provider adapters and extensible ActiveRecord models for app().ai. */
+	ai?: AIOptions;
+	db?: Knex;
+	dbOptions?: DatabaseOptions;
+	auth?: Omit<AuthOptions<any>, 'db' | 'requestContext'>;
+	config?: ConfigValues | Config;
+	/** Application logging configuration or injectable logger driver. */
+	log?: LoggingOptions;
+	/** Canonical application URL configuration used across all runtimes. */
+	url?: UrlGeneratorOptions;
+	queue?: QueueOptions;
+	/** Serializable classes and ActiveRecord models registered with app().serializer. */
+	serializer?: SerializerOptions;
+	storage?: StorageOptions;
+}
+
+/**
+ * Application service hub.
+ *
+ * Keep this as the place where top-level framework capabilities are discovered
+ * and wired, not where domain logic itself accumulates.
+ */
+export class App {
+	private readonly services = new Map<string, unknown>();
+	/** Absolute app root used for conventional server paths, independent of later working-directory changes. */
+	readonly directory: string;
+
+	/**
+	 * Creates an application service hub and validates configured startup security.
+	 *
+	 * @param options - Framework services and application configuration.
+	 */
+	constructor(protected readonly options: AppOptions = {}) {
+		this.directory = resolve(options.directory instanceof URL ? fileURLToPath(options.directory) : options.directory ?? process.cwd());
+		setActiveApp(this);
+
+		if (this.config.has('security')) void this.security;
+	}
+
+	/** Returns the lazy database service with this app's connection, model registry and root directory. */
+	get db(): Database {
+		return this.service('db', () => {
+			return new Database(
+				this.resolveDbConnection(),
+				this.resolveDatabaseOptions(),
+				this.directory,
+			);
+		});
+	}
+
+	get auth(): Auth<any> {
+		return this.service('auth', () => new Auth<any>({
+			...this.options.auth,
+			db: this.db,
+			config: this.config,
+			requestContext: this.requestContext,
+		}));
+	}
+
+	get requestContext(): RequestContext {
+		return this.service('requestContext', () => new RequestContext());
+	}
+
+	/** Returns the application AI service with durable request and conversation history. */
+	get ai(): Ai {
+		return this.service('ai', () => new Ai(this.options.ai ?? this.config.get<AIOptions>('ai', {})));
+	}
+
+	/**
+	 * Returns the configured application cache.
+	 *
+	 * Cache driver selection lives under `config.cache`, keeping backend
+	 * connection details out of application code.
+	 *
+	 * @returns Cache service using the configured named store.
+	 */
+	get cache(): Cache {
+		return this.service('cache', () => new Cache(
+			this.config.get<CacheOptions>('cache', {}),
+		));
+	}
+
+	/**
+	 * Returns the typed in-process application event dispatcher.
+	 *
+	 * @returns Event service shared by framework and application code.
+	 */
+	get events(): Events {
+		return this.service('events', () => new Events());
+	}
+
+	/**
+	 * Returns the application logger shared by framework and app services.
+	 *
+	 * @returns Pino-backed logging service with app lifecycle ownership.
+	 */
+	get log(): Log {
+		return this.service('log', () => new Log(this.options.log));
+	}
+
+	/**
+	 * Returns the canonical application URL generator.
+	 *
+	 * This is independent of any concrete Fastify, Express, or other server
+	 * instance so background processes resolve the same public application URL.
+	 *
+	 * @returns Shared canonical URL generator.
+	 */
+	get url(): UrlGenerator {
+		return this.service('url', () => new UrlGenerator(this.options.url));
+	}
+
+	/**
+	 * Returns the configured app config repository.
+	 */
+	get config(): Config {
+		return this.service('config', () => {
+			if (this.options.config instanceof Config) {
+				return this.options.config;
+			}
+
+			return new Config(this.options.config);
+		});
+	}
+
+	get queue(): Queue {
+		return this.service('queue', () => new Queue(
+			this.db,
+			this.options.queue,
+		));
+	}
+
+	/**
+	 * Returns the application scheduler and attaches queue lifecycle recording.
+	 *
+	 * @returns Scheduler backed by the active database and queue services.
+	 */
+	get scheduler(): Scheduler {
+		return this.service('scheduler', () => new Scheduler(
+			this.db,
+			this.queue,
+		));
+	}
+
+	/**
+	 * Returns the central application security service.
+	 *
+	 * @returns Shared authenticated encryption service.
+	 */
+	get security(): Security {
+		return this.service('security', () => new Security());
+	}
+
+	/**
+	 * Returns the application serializer and its scoped class/model registry.
+	 *
+	 * @returns Strict serializer configured for this application process.
+	 */
+	get serializer(): Serializer {
+		return this.service('serializer', () => new Serializer(
+			this.options.serializer,
+		));
+	}
+
+	/**
+	 * Returns the configured file storage service.
+	 */
+	get storage(): Storage {
+		return this.service('storage', () => new Storage(this.options.storage));
+	}
+
+	/**
+	 * Returns the configured media manager.
+	 *
+	 * Media options are resolved from `config.media`, allowing applications to
+	 * place derived image variants on a disposable storage disk.
+	 *
+	 * @returns Media manager backed by configured durable and temporary storage.
+	 */
+	get media(): MediaManager {
+		return this.service('media', () => new MediaManager(
+			this.storage,
+			this.config.get<MediaOptions>('media', {}),
+		));
+	}
+
+	/**
+	 * Registers a concrete service instance.
+	 *
+	 * Useful for tests and for services that are built by a provider.
+	 */
+	set<TService>(name: string, service: TService): this {
+		this.services.set(name, service);
+		return this;
+	}
+
+	/**
+	 * Returns a configured service, creating and caching it on first access.
+	 */
+	service<TService>(name: string, factory: () => TService): TService {
+		const existing = this.services.get(name);
+
+		if (existing) {
+			return existing as TService;
+		}
+
+		const created = factory();
+
+		this.services.set(name, created);
+
+		return created;
+	}
+
+	/**
+	 * Closes shared resources owned by the default app.
+	 */
+	async close(): Promise<void> {
+		clearActiveApp(this);
+
+		(this.services.get('scheduler') as Scheduler | undefined)?.close();
+		(this.services.get('events') as Events | undefined)?.clear();
+		await (this.services.get('cache') as Cache | undefined)?.close();
+		await (this.services.get('log') as Log | undefined)?.close();
+
+		if (!this.options.db) {
+			await destroyDatabase();
+		}
+
+		this.services.clear();
+	}
+
+	private resolveDbConnection(): Knex {
+		if (!this.options.db) {
+			return defaultDb();
+		}
+
+		return this.options.db;
+	}
+
+	private resolveDatabaseOptions(): DatabaseOptions {
+		return {
+			...this.options.dbOptions,
+			syncColumns: this.options.dbOptions?.syncColumns
+				?? parseOptionalBoolean(process.env.DB_SYNC_COLUMNS)
+				?? true,
+		};
+	}
+}
+
+function parseOptionalBoolean(input: string | undefined): boolean | undefined {
+	if (input === undefined || input === '') {
+		return undefined;
+	}
+
+	switch (input.toLowerCase().trim()) {
+		case '1':
+		case 'true':
+		case 'yes':
+		case 'on':
+			return true;
+
+		case '0':
+		case 'false':
+		case 'no':
+		case 'off':
+			return false;
+
+		default:
+			throw new Error(
+				`Invalid DB_SYNC_COLUMNS value "${input}". Use true or false.`,
+			);
+	}
+}