@db3.ai/app 0.1.0-beta.1

package/src/cache/contracts/CacheDriver.ts

@@ -0,0 +1,11 @@
+import type { CacheRepository } from './CacheRepository';
+
+/**
+ * Cache backend boundary owned by the framework cache service.
+ */
+export interface CacheDriver extends CacheRepository {
+	/**
+	 * Releases connections and other resources held by the cache backend.
+	 */
+	close(): Promise<void>;
+}

package/src/cache/contracts/CacheOperations.ts

@@ -0,0 +1,28 @@
+/**
+ * Per-write cache options.
+ */
+export interface CacheSetOptions {
+	/** Time-to-live in milliseconds, overriding the configured store default. */
+	ttl?: number;
+}
+
+/**
+ * Options controlling one cache-through lookup.
+ */
+export interface CacheGetOrSetOptions<TValue> {
+	/**
+	 * Time-to-live in milliseconds or a function deriving it from the resolved value.
+	 */
+	ttl?: number | ((value: TValue) => number);
+	/**
+	 * Remaining TTL threshold that triggers a background refresh.
+	 *
+	 * The stale value is returned while the factory refreshes it.
+	 */
+	refreshThreshold?: number | ((value: TValue) => number);
+}
+
+/**
+ * Factory that computes a value after a cache miss.
+ */
+export type CacheValueFactory<TValue> = () => TValue | Promise<TValue>;

package/src/cache/contracts/CacheOptions.ts

@@ -0,0 +1,56 @@
+/**
+ * Bounded in-process cache store configuration.
+ */
+export interface MemoryCacheStoreOptions {
+	/** Cache driver selected for this named store. */
+	driver: 'memory';
+	/** Default time-to-live in milliseconds. Omit for no default expiry. */
+	ttl?: number;
+	/** Maximum entries retained by the least-recently-used cache. Defaults to 1,000. */
+	maxEntries?: number;
+	/** Whether values are cloned when stored and retrieved. Defaults to true. */
+	clone?: boolean;
+}
+
+/**
+ * Redis cache store configuration using the official Keyv adapter.
+ */
+export interface RedisCacheStoreOptions {
+	/** Cache driver selected for this named store. */
+	driver: 'redis';
+	/** Redis connection URL including credentials and database when required. */
+	url: string;
+	/**
+	 * Prefix isolating application cache keys from other Redis data.
+	 *
+	 * A namespace is required so clearing the cache cannot affect unrelated keys.
+	 */
+	namespace: string;
+	/** Default time-to-live in milliseconds. Omit for no default expiry. */
+	ttl?: number;
+	/** Milliseconds allowed for the initial Redis connection attempt. */
+	connectionTimeoutMs?: number;
+	/** Number of namespaced keys removed in each cache-clear batch. */
+	clearBatchSize?: number;
+	/** Whether Redis connection failures should reject cache operations. */
+	throwOnConnectError?: boolean;
+	/** Whether Redis command errors should reject cache operations. */
+	throwOnErrors?: boolean;
+}
+
+/**
+ * Supported framework cache store configurations.
+ */
+export type CacheStoreOptions =
+	| MemoryCacheStoreOptions
+	| RedisCacheStoreOptions;
+
+/**
+ * Named cache-store configuration resolved from the application config.
+ */
+export interface CacheOptions {
+	/** Named store used by `app().cache`. Defaults to `memory`. */
+	default?: string;
+	/** Cache stores available to the application. */
+	stores?: Record<string, CacheStoreOptions>;
+}

package/src/cache/contracts/CacheRepository.ts

@@ -0,0 +1,62 @@
+import type {
+	CacheGetOrSetOptions,
+	CacheSetOptions,
+	CacheValueFactory,
+} from './CacheOperations';
+
+/**
+ * Application-facing cache operations shared by framework and app code.
+ */
+export interface CacheRepository {
+	/**
+	 * Retrieves a cached value.
+	 *
+	 * @param key - Stable application cache key.
+	 * @returns Cached value or undefined when the key is absent or expired.
+	 */
+	get<TValue>(key: string): Promise<TValue | undefined>;
+
+	/**
+	 * Stores one defined cache value.
+	 *
+	 * @param key - Stable application cache key.
+	 * @param value - Defined value to retain.
+	 * @param options - Optional per-write TTL.
+	 * @returns The stored value.
+	 */
+	set<TValue>(
+		key: string,
+		value: TValue,
+		options?: CacheSetOptions,
+	): Promise<TValue>;
+
+	/**
+	 * Returns a cached value or computes and stores it after a miss.
+	 *
+	 * Concurrent lookups for the same key share one in-flight factory execution
+	 * within the current process.
+	 *
+	 * @param key - Stable application cache key.
+	 * @param factory - Value producer invoked after a cache miss.
+	 * @param options - TTL and optional background-refresh controls.
+	 * @returns Cached or newly resolved value.
+	 */
+	getOrSet<TValue>(
+		key: string,
+		factory: CacheValueFactory<TValue>,
+		options?: CacheGetOrSetOptions<TValue>,
+	): Promise<TValue>;
+
+	/**
+	 * Removes one cache key.
+	 *
+	 * @param key - Cache key to remove.
+	 * @returns True when the underlying cache accepted the deletion.
+	 */
+	forget(key: string): Promise<boolean>;
+
+	/**
+	 * Removes every key owned by the configured cache store.
+	 */
+	clear(): Promise<void>;
+}

package/src/cache/contracts/index.ts

@@ -0,0 +1,4 @@
+export * from './CacheDriver';
+export * from './CacheOperations';
+export * from './CacheOptions';
+export * from './CacheRepository';

package/src/cache/drivers/CacheManagerDriver.ts

@@ -0,0 +1,84 @@
+import type { Cache as ManagedCache } from 'cache-manager';
+
+import type * as cache from '../contracts';
+
+/**
+ * Cache driver backed by the Cache Manager package.
+ */
+export class CacheManagerDriver implements cache.CacheDriver {
+	#closePromise: Promise<void> | null = null;
+
+	/**
+	 * Creates a driver around one configured Cache Manager instance.
+	 *
+	 * @param manager - Cache Manager instance containing the selected Keyv store.
+	 */
+	constructor(private readonly manager: ManagedCache) {}
+
+	/**
+	 * Retrieves a cached value from Cache Manager.
+	 *
+	 * @param key - Stable application cache key.
+	 * @returns Cached value or undefined after a miss.
+	 */
+	async get<TValue>(key: string): Promise<TValue | undefined> {
+		return this.manager.get<TValue>(key);
+	}
+
+	/**
+	 * Stores one value through Cache Manager.
+	 *
+	 * @param key - Stable application cache key.
+	 * @param value - Value to retain.
+	 * @param options - Optional per-write TTL.
+	 * @returns The stored value.
+	 */
+	async set<TValue>(
+		key: string,
+		value: TValue,
+		options: cache.CacheSetOptions = {},
+	): Promise<TValue> {
+		return this.manager.set(key, value, options.ttl);
+	}
+
+	/**
+	 * Uses Cache Manager's coalesced wrapper for one cache-through lookup.
+	 *
+	 * @param key - Stable application cache key.
+	 * @param factory - Value producer invoked after a miss.
+	 * @param options - TTL and background-refresh controls.
+	 * @returns Cached or newly resolved value.
+	 */
+	async getOrSet<TValue>(
+		key: string,
+		factory: cache.CacheValueFactory<TValue>,
+		options: cache.CacheGetOrSetOptions<TValue> = {},
+	): Promise<TValue> {
+		return this.manager.wrap(key, factory, options);
+	}
+
+	/**
+	 * Deletes one cache key through Cache Manager.
+	 *
+	 * @param key - Cache key to remove.
+	 * @returns True when Cache Manager accepted the deletion.
+	 */
+	async forget(key: string): Promise<boolean> {
+		return this.manager.del(key);
+	}
+
+	/**
+	 * Clears keys owned by the selected store.
+	 */
+	async clear(): Promise<void> {
+		await this.manager.clear();
+	}
+
+	/**
+	 * Disconnects every Keyv store exactly once.
+	 */
+	async close(): Promise<void> {
+		this.#closePromise ??= this.manager.disconnect().then(() => {});
+		await this.#closePromise;
+	}
+}

package/src/cache/drivers/createCacheDriver.ts

@@ -0,0 +1,191 @@
+import { createKeyv as createMemoryStore } from 'cacheable';
+import { createCache } from 'cache-manager';
+import { createKeyv as createRedisStore } from '@keyv/redis';
+
+import type * as cache from '../contracts';
+import { CacheManagerDriver } from './CacheManagerDriver';
+
+const defaultMemoryStore: cache.MemoryCacheStoreOptions = {
+	driver: 'memory',
+	maxEntries: 1000,
+};
+
+/**
+ * Creates the concrete cache driver selected by named application config.
+ *
+ * @param options - Named store configuration from `config.cache`.
+ * @returns Cache Manager driver using the selected memory or Redis store.
+ */
+export function createCacheDriver(
+	options: cache.CacheOptions = {},
+): cache.CacheDriver {
+	const storeName = nonEmptyString(options.default ?? 'memory', 'Cache default store');
+	const stores = options.stores ?? {
+		memory: defaultMemoryStore,
+	};
+	const store = stores[storeName];
+
+	if (!store) {
+		throw new Error(`Cache store "${storeName}" is not configured.`);
+	}
+
+	switch (store.driver) {
+		case 'memory':
+			return memoryCacheDriver(store);
+
+		case 'redis':
+			return redisCacheDriver(store);
+
+		default:
+			return unsupportedCacheDriver(store);
+	}
+}
+
+/**
+ * Creates a bounded CacheableMemory store behind Cache Manager.
+ *
+ * @param options - Memory TTL, LRU bound, and clone configuration.
+ * @returns Cache Manager driver using an in-process store.
+ */
+function memoryCacheDriver(
+	options: cache.MemoryCacheStoreOptions,
+): cache.CacheDriver {
+	const ttl = optionalPositiveNumber(options.ttl, 'Memory cache TTL');
+	const maxEntries = positiveInteger(
+		options.maxEntries ?? defaultMemoryStore.maxEntries,
+		'Memory cache maxEntries',
+	);
+	const store = createMemoryStore({
+		ttl,
+		lruSize: maxEntries,
+		useClone: options.clone,
+	});
+
+	store.on('error', ignoreStoreError);
+
+	return new CacheManagerDriver(createCache({
+		stores: [store],
+		ttl,
+	}));
+}
+
+/**
+ * Creates a namespaced Redis Keyv store behind Cache Manager.
+ *
+ * `noNamespaceAffectsAll` remains false so a cache clear never becomes a broad
+ * Redis database flush.
+ *
+ * @param options - Redis connection, namespace, TTL, and failure configuration.
+ * @returns Cache Manager driver using the official Redis adapter.
+ */
+function redisCacheDriver(
+	options: cache.RedisCacheStoreOptions,
+): cache.CacheDriver {
+	const url = nonEmptyString(options.url, 'Redis cache URL');
+	const namespace = nonEmptyString(options.namespace, 'Redis cache namespace');
+	const ttl = optionalPositiveNumber(options.ttl, 'Redis cache TTL');
+	const connectionTimeout = optionalPositiveNumber(
+		options.connectionTimeoutMs,
+		'Redis cache connectionTimeoutMs',
+	);
+	const clearBatchSize = options.clearBatchSize === undefined
+		? undefined
+		: positiveInteger(options.clearBatchSize, 'Redis cache clearBatchSize');
+	const store = createRedisStore(url, {
+		namespace,
+		keyPrefixSeparator: ':',
+		connectionTimeout,
+		clearBatchSize,
+		noNamespaceAffectsAll: false,
+		throwOnConnectError: options.throwOnConnectError,
+		throwOnErrors: options.throwOnErrors,
+		useUnlink: true,
+	});
+
+	store.on('error', ignoreStoreError);
+
+	return new CacheManagerDriver(createCache({
+		stores: [store],
+		ttl,
+	}));
+}
+
+/**
+ * Produces an exhaustive runtime error for config values outside the public union.
+ *
+ * @param store - Invalid store configuration received from untyped runtime config.
+ * @returns Never because unsupported drivers cannot be created.
+ */
+function unsupportedCacheDriver(store: never): never {
+	const driver = (store as {
+		driver?: unknown;
+	}).driver;
+
+	throw new Error(`Unsupported cache driver "${String(driver)}".`);
+}
+
+/**
+ * Prevents storage-adapter EventEmitter errors from terminating the process.
+ *
+ * Cache operations still follow Cache Manager's own resolve/reject semantics.
+ *
+ * @param _error - Adapter error governed by the selected store's failure options.
+ */
+function ignoreStoreError(_error: unknown): void {}
+
+/**
+ * Validates a required non-empty string config value.
+ *
+ * @param value - Candidate config value.
+ * @param label - Human-readable option name.
+ * @returns Trimmed non-empty string.
+ */
+function nonEmptyString(value: unknown, label: string): string {
+	const normalized = typeof value === 'string'
+		? value.trim()
+		: '';
+
+	if (!normalized) {
+		throw new Error(`${label} must be a non-empty string.`);
+	}
+
+	return normalized;
+}
+
+/**
+ * Validates an optional positive finite number.
+ *
+ * @param value - Candidate numeric config value.
+ * @param label - Human-readable option name.
+ * @returns Validated value or undefined when omitted.
+ */
+function optionalPositiveNumber(
+	value: number | undefined,
+	label: string,
+): number | undefined {
+	if (value === undefined) return undefined;
+
+	if (!Number.isFinite(value) || value <= 0) {
+		throw new Error(`${label} must be greater than zero.`);
+	}
+
+	return value;
+}
+
+/**
+ * Validates a positive integer config value.
+ *
+ * @param value - Candidate numeric config value.
+ * @param label - Human-readable option name.
+ * @returns Validated positive integer.
+ */
+function positiveInteger(
+	value: number | undefined,
+	label: string,
+): number {
+	if (!Number.isInteger(value) || Number(value) <= 0) {
+		throw new Error(`${label} must be a positive integer.`);
+	}
+
+	return Number(value);
+}

package/src/cache/examples/runNoteCache.ts

@@ -0,0 +1,37 @@
+import { pathToFileURL } from 'node:url';
+import { Cache } from '@db3.ai/app/cache';
+
+/**
+ * Runs cache-through reads, owner-key isolation, invalidation and failure recovery.
+ *
+ * The counted factory represents an expensive lookup without needing a database.
+ * It is deterministic and uses the real bounded memory driver.
+ *
+ * @returns Observable cache outcomes, after closing the owned store.
+ */
+export async function runNoteCache() {
+	const cache = new Cache({ default: 'memory', stores: { memory: { driver: 'memory', ttl: 60_000, maxEntries: 100 } } });
+	let loads = 0;
+	/** Computes one example summary when the cache has no value. */
+	const loadSummary = async () => ({ count: ++loads });
+	try {
+		const key = 'notes:v1:owner:ada:summary';
+		const concurrent = await Promise.all([cache.getOrSet(key, loadSummary), cache.getOrSet(key, loadSummary)]);
+		const firstLoads = loads;
+		await cache.set('notes:v1:owner:grace:summary', { count: 9 });
+		await cache.forget(key);
+		const refreshed = await cache.getOrSet(key, loadSummary);
+		let rejectedUndefined = false;
+		try { await cache.set('invalid', undefined); } catch { rejectedUndefined = true; }
+		let rejectedFactory = false;
+		try { await cache.getOrSet('recover', () => { throw new Error('Lookup failed'); }); } catch { rejectedFactory = true; }
+		const recovered = await cache.getOrSet('recover', () => 'ready');
+		const otherOwner = await cache.get('notes:v1:owner:grace:summary');
+		await cache.clear();
+		return { concurrent, firstLoads, refreshed, otherOwner, rejectedUndefined, rejectedFactory, recovered, cleared: await cache.get(key) === undefined };
+	} finally {
+		await cache.close();
+	}
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) console.log(JSON.stringify(await runNoteCache(), null, 2));

package/src/cache/index.ts

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

package/src/cli/Cli.ts

@@ -0,0 +1,110 @@
+import { resolve } from 'node:path';
+import type { App } from '../server';
+import type * as cli from './contracts';
+
+/** Validates and executes registered service commands with one owned app lifecycle. */
+export class Cli {
+	readonly #commands = new Map<string, cli.CliCommand>();
+	readonly #config: cli.CliConfig;
+	readonly #directory: string;
+	readonly #write: (message: string) => void;
+	readonly #writeError: (message: string) => void;
+
+	/**
+	 * Registers explicit commands without booting an application or its services.
+	 * @param config - App factory and service-owned command definitions.
+	 * @param options - Root directory and output adapters.
+	 */
+	constructor(config: cli.CliConfig, options: cli.CliOptions = {}) {
+		if (!config || !Array.isArray(config.commands)) throw new Error('CLI configuration must export a commands array.');
+		if (config.createApp !== undefined && typeof config.createApp !== 'function') throw new Error('CLI createApp must be a function.');
+		this.#config = config;
+		this.#directory = resolve(options.directory ?? process.cwd());
+		this.#write = options.write ?? console.log;
+		this.#writeError = options.writeError ?? console.error;
+		for (const command of config.commands) {
+			if (!command || !/^[a-z][a-z0-9]*(?::[a-z][a-z0-9-]*)*$/.test(command.name) || typeof command.description !== 'string' || typeof command.run !== 'function') throw new Error('Invalid CLI command definition.');
+			if (this.#commands.has(command.name)) throw new Error(`Duplicate CLI command: ${command.name}`);
+			let optional = false;
+			for (const argument of command.arguments ?? []) {
+				if (!/^[a-zA-Z][a-zA-Z0-9-]*$/.test(argument.name) || (optional && argument.required)) throw new Error(`Invalid argument declaration for ${command.name}.`);
+				if (!argument.required) optional = true;
+			}
+			this.#commands.set(command.name, command);
+		}
+	}
+
+	/**
+	 * Runs one invocation, printing help without app startup and closing a created app on failure too.
+	 * @param argv - Arguments after the executable name.
+	 * @returns Process-compatible exit status; this method never exits the process.
+	 */
+	async run(argv: readonly string[]): Promise<number> {
+		if (argv.length === 0 || (argv.length === 1 && ['--help', '-h'].includes(argv[0]!))) {
+			this.#write(['Usage: db3 <command> [arguments]', '', ...[...this.#commands.values()].map(command => `${usage(command)}\n  ${command.description}`)].join('\n'));
+			return 0;
+		}
+		const command = this.#commands.get(argv[0]!);
+		if (!command) {
+			this.#writeError(`Unknown command: ${argv[0]}. Run db3 --help from your app root; service commands are registered in server/cli.config.ts.`);
+			return 1;
+		}
+		const args = argv.slice(1);
+		if (args.length === 1 && ['--help', '-h'].includes(args[0]!)) {
+			this.#write(`${usage(command)}\n${command.description}`);
+			return 0;
+		}
+		const parameters = command.arguments ?? [];
+		if (args.some(value => value.startsWith('-')) || args.length < parameters.filter(argument => argument.required).length || args.length > parameters.length) {
+			this.#writeError(`Invalid arguments. Usage: ${usage(command)}`);
+			return 1;
+		}
+		let application: App | undefined;
+		let pendingApplication: Promise<App> | undefined;
+		let status = 0;
+		let reportedError: unknown;
+		try {
+			const result = await command.run({
+				args, directory: this.#directory, write: this.#write,
+				/** Creates the invocation's app once, even when multiple callers await it. */
+				app: () => {
+					pendingApplication ??= Promise.resolve().then(async () => {
+						if (!this.#config.createApp) throw new Error('This command requires createApp in server/cli.config.ts.');
+						application = await this.#config.createApp();
+						return application;
+					});
+					return pendingApplication;
+				},
+			});
+			status = result ?? 0;
+			if (!Number.isInteger(status) || status < 0 || status > 255) throw new Error(`Command ${command.name} returned an invalid exit status.`);
+		} catch (error) {
+			reportedError = error;
+			this.#writeError(errorMessage(error));
+			status = 1;
+		} finally {
+			// Finish pending startup before releasing resources, including failed commands.
+			try { await pendingApplication; } catch (error) {
+				if (error !== reportedError) this.#writeError(errorMessage(error));
+				status = 1;
+			}
+			if (application) {
+				try { await application.close(); } catch (error) {
+					this.#writeError(`Application shutdown failed: ${errorMessage(error)}`);
+					status = 1;
+				}
+			}
+		}
+		return status;
+	}
+}
+
+/** Formats command usage from its declared positional arguments. */
+function usage(command: cli.CliCommand): string {
+	return [`db3 ${command.name}`, ...(command.arguments ?? []).map(argument => argument.required ? `<${argument.name}>` : `[${argument.name}]`)].join(' ');
+}
+
+/** Produces a concise terminal error without dumping application objects or configuration. */
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : 'Command failed.';
+}