@db3.ai/app 0.1.0-beta.1

package/src/config/README.md

@@ -0,0 +1,142 @@
+# Configuration
+
+Read settings once at boot. Parse environment values, validate what your
+application needs and pass the result into the services that use it.
+`@db3.ai/app/config` supplies `Config`, `defineConfig()`, `env` and `createEnv()`.
+It does not discover configuration files or load `.env` for you.
+
+## Run the notes configuration example
+
+Complete the [installation guide](https://db3.ai/docs/installation), including
+`tsx`, TypeScript and Vitest. From that independent app directory:
+
+```sh
+mkdir -p examples
+cp -R node_modules/@db3.ai/app/src/config/examples/. examples/
+npx tsx examples/runConfig.ts
+APP_PORT=3100 NOTES_PAGE_SIZE=50 APP_DEBUG=yes npx tsx examples/runConfig.ts
+```
+
+The default run prints `My notes`, port `3000`, page size `20` and debug `false`.
+The override uses port `3100`, page size `50` and debug `true`. A generated URL is
+only a value: this lab does not start HTTP, open SQL or contact a provider.
+The runner loads `.env` through `dotenv/config`; existing environment variables
+take precedence. Keep `.env` out of Git.
+
+Now try an invalid setting:
+
+```sh
+APP_PORT=abc npx tsx examples/runConfig.ts
+```
+
+It fails with an error naming `APP_PORT` before constructing App. Correct the
+value and repeat the command. No partial service startup needs cleaning up.
+
+## Own the application settings
+
+The shipped [loadNotesConfig.ts](./examples/loadNotesConfig.ts) uses
+`createEnv(source)` so tests can provide an ordinary object. It validates a
+port and page size after parsing them. An integer parser does not know whether
+`0` is a valid application port or `100000` is a sensible page size.
+
+Only call `env.required()` when the owning feature needs the value. The example
+requires `WEBHOOK_KEY` only when `WEBHOOK_ENABLED` is true. It does not send a
+webhook, and it never includes the key in its printed result.
+
+```ts
+import { createEnv, defineConfig } from '@db3.ai/app/config';
+
+const env = createEnv({ APP_DEBUG: 'yes', NOTES_PAGE_SIZE: '20' });
+const notes = defineConfig({
+	debug: env.boolean('APP_DEBUG', false),
+	pageSize: env.integer('NOTES_PAGE_SIZE', 20),
+});
+```
+
+`defineConfig()` preserves inferred types and returns the same object. It does
+not validate, freeze or clone it. Import configuration files explicitly; there
+is no directory discovery or automatic merge order.
+
+## Wire services explicitly
+
+The shipped [runConfig.ts](./examples/runConfig.ts) passes the settings into
+`new App({ config: { notes } })`. The repository becomes `application.config`.
+It passes URL settings separately through the supported `url` option.
+Putting a value under `config.url` would not configure the URL service.
+
+Use the typed settings object directly where practical. At service boundaries:
+
+```ts
+const pageSize = application.config.get<number>('notes.pageSize');
+const label = application.config.get('notes.missing', 'fallback');
+const present = application.config.has('notes.webhook');
+```
+
+The generic in `get<number>()` is a TypeScript assertion, not runtime validation
+or checked path autocomplete. See the [App/config guide](https://db3.ai/docs/app-config)
+for the distinction between configuration data, service construction and process
+startup.
+
+## Presence and defaults
+
+`get(path, fallback)` uses the fallback only when the property is absent.
+Existing `null`, `undefined`, `false`, zero and empty strings are preserved.
+`has()` checks property presence, not whether the value is truthy.
+
+Paths traverse own object properties. They do not index arrays: retrieve the
+whole array and work with it normally. Empty paths and empty path segments such
+as `notes..title` throw. A missing intermediate object uses the fallback.
+
+`all()` exposes the original object. Treat configuration as read-only, and never
+return `all()` from an endpoint, log it or put it in browser hydration data.
+
+## Environment parsers
+
+| Reader | Behaviour |
+| --- | --- |
+| `env()` / `env.string()` | Raw string, including an empty string. Fallback applies only to `undefined`. |
+| `env.required()` | Rejects missing or exactly empty values. It does not trim whitespace; add domain validation when needed. |
+| `env.boolean()` | Case-insensitive `1/true/yes/on` or `0/false/no/off`; rejects other nonempty values. |
+| `env.number()` | Converts to a finite number; rejects invalid or non-finite values. |
+| `env.integer()` | Also rejects fractional values. Validate application ranges separately. |
+| `env.array()` | Comma-separated, trimmed, nonempty entries. |
+| `env.json<T>()` | Parses JSON, not a schema. `T` does not validate the parsed shape. |
+
+Typed boolean/number/integer/array/JSON readers trim strings and return their
+fallback for missing or empty values. With no fallback the result is
+`undefined`. Invalid nonempty input throws rather than silently using a default.
+
+`createEnv()` reads its supplied object on each call. The exported `env` reads
+`process.env`. A constructed config object is a snapshot of the values read at
+boot; changing environment variables does not recreate an initialized service.
+Restart the process after changing settings.
+
+## Testing and cleanup
+
+The website's [Config guide](https://db3.ai/docs/config#testing) supplies the exact
+three-test file. Save it as `tests/config/runConfig.test.ts`, keeping the copied
+examples in `examples/`, then run:
+
+```sh
+npx vitest run tests/config/runConfig.test.ts
+npx tsc --noEmit --target ES2022 --module ESNext --moduleResolution Bundler --types node --skipLibCheck examples/*.ts
+```
+
+It checks defaults, overrides, public output, malformed values, range limits,
+optional credentials, fallback/presence and raw versus parsed values. The tests
+do not mutate `process.env` or mock framework services. The runner closes App
+in `finally`; Config itself owns no handles.
+
+For framework maintainers, the service suite is
+`npm run test:service --workspace packages/app -- config --maxWorkers=1`.
+
+## Coverage and advanced reference
+
+The walkthrough exercises typed boot settings, validation, App integration,
+Config reuse, safe output and the common parsers. Existing service tests cover
+the remaining malformed parser inputs. There is no automatic hot reload,
+schema validation, config discovery or secret manager.
+
+The [Config API reference](https://db3.ai/docs/config-api) renders the exact
+emitted repository methods and environment-reader overloads from the staged
+package. Application types and permissions remain in your app.

package/src/config/env.ts

@@ -0,0 +1,164 @@
+export type EnvSource = Record<string, string | undefined>;
+
+export interface EnvReader {
+	(name: string): string | undefined;
+	<TDefault>(name: string, fallback: TDefault): string | TDefault;
+	required(name: string): string;
+	string(name: string): string | undefined;
+	string<TDefault>(name: string, fallback: TDefault): string | TDefault;
+	boolean(name: string): boolean | undefined;
+	boolean<TDefault>(name: string, fallback: TDefault): boolean | TDefault;
+	number(name: string): number | undefined;
+	number<TDefault>(name: string, fallback: TDefault): number | TDefault;
+	integer(name: string): number | undefined;
+	integer<TDefault>(name: string, fallback: TDefault): number | TDefault;
+	array(name: string): string[] | undefined;
+	array<TDefault>(name: string, fallback: TDefault): string[] | TDefault;
+	json<TValue = unknown>(name: string): TValue | undefined;
+	json<TValue = unknown, TDefault = TValue>(name: string, fallback: TDefault): TValue | TDefault;
+}
+
+/**
+ * Creates an env reader over a supplied source object.
+ *
+ * @param source - Environment-like key/value source.
+ * @returns Callable env reader with typed parsing helpers.
+ */
+export function createEnv(source: EnvSource = process.env): EnvReader {
+	const reader = (<TDefault>(name: string, fallback?: TDefault) => {
+		const value = source[name];
+
+		return value === undefined ? fallback : value;
+	}) as EnvReader;
+
+	reader.required = (name: string): string => {
+		const value = source[name];
+
+		if (value === undefined || value === '') {
+			throw new Error(`Environment variable "${name}" is required.`);
+		}
+
+		return value;
+	};
+
+	reader.string = (<TDefault>(name: string, fallback?: TDefault) => {
+		const value = source[name];
+
+		return value === undefined ? fallback : value;
+	}) as EnvReader['string'];
+
+	reader.boolean = (<TDefault>(name: string, fallback?: TDefault) => {
+		const value = optionalEnvValue(source, name);
+
+		if (value === undefined) return fallback;
+
+		return parseEnvBoolean(name, value);
+	}) as EnvReader['boolean'];
+
+	reader.number = (<TDefault>(name: string, fallback?: TDefault) => {
+		const value = optionalEnvValue(source, name);
+
+		if (value === undefined) return fallback;
+
+		return parseEnvNumber(name, value);
+	}) as EnvReader['number'];
+
+	reader.integer = (<TDefault>(name: string, fallback?: TDefault) => {
+		const value = optionalEnvValue(source, name);
+
+		if (value === undefined) return fallback;
+
+		const parsed = parseEnvNumber(name, value);
+
+		if (!Number.isInteger(parsed)) {
+			throw new Error(`Environment variable "${name}" must be an integer.`);
+		}
+
+		return parsed;
+	}) as EnvReader['integer'];
+
+	reader.array = (<TDefault>(name: string, fallback?: TDefault) => {
+		const value = optionalEnvValue(source, name);
+
+		if (value === undefined) return fallback;
+
+		return value
+			.split(',')
+			.map(item => item.trim())
+			.filter(item => item.length > 0);
+	}) as EnvReader['array'];
+
+	reader.json = (<TValue = unknown, TDefault = TValue>(name: string, fallback?: TDefault) => {
+		const value = optionalEnvValue(source, name);
+
+		if (value === undefined) return fallback;
+
+		try {
+			return JSON.parse(value) as TValue;
+		} catch (error) {
+			throw new Error(`Environment variable "${name}" must contain valid JSON.`, {
+				cause: error,
+			});
+		}
+	}) as EnvReader['json'];
+
+	return reader;
+}
+
+export const env = createEnv();
+
+/**
+ * Returns a normalized optional env value for typed parsers.
+ *
+ * @param source - Environment-like source object.
+ * @param name - Environment variable name.
+ * @returns Trimmed string value or undefined when absent or empty.
+ */
+function optionalEnvValue(source: EnvSource, name: string): string | undefined {
+	const value = source[name]?.trim();
+
+	return value === '' ? undefined : value;
+}
+
+/**
+ * Parses a boolean environment variable.
+ *
+ * @param name - Environment variable name for error messages.
+ * @param value - Raw environment variable value.
+ * @returns Parsed boolean value.
+ */
+function parseEnvBoolean(name: string, value: string): boolean {
+	switch (value.toLowerCase()) {
+		case '1':
+		case 'true':
+		case 'yes':
+		case 'on':
+			return true;
+
+		case '0':
+		case 'false':
+		case 'no':
+		case 'off':
+			return false;
+
+		default:
+			throw new Error(`Environment variable "${name}" must be a boolean.`);
+	}
+}
+
+/**
+ * Parses a finite number environment variable.
+ *
+ * @param name - Environment variable name for error messages.
+ * @param value - Raw environment variable value.
+ * @returns Parsed number.
+ */
+function parseEnvNumber(name: string, value: string): number {
+	const parsed = Number(value);
+
+	if (!Number.isFinite(parsed)) {
+		throw new Error(`Environment variable "${name}" must be a number.`);
+	}
+
+	return parsed;
+}

package/src/config/examples/loadNotesConfig.ts

@@ -0,0 +1,29 @@
+import { createEnv, defineConfig, type EnvSource } from '@db3.ai/app/config';
+
+/**
+ * Reads application settings once at boot, before constructing services.
+ *
+ * Parsing a number does not establish its business range. Optional integration
+ * credentials are required only when that integration is explicitly enabled.
+ *
+ * @param source - Environment values; inject a plain object in application tests.
+ * @returns Validated, typed settings owned by this notes application.
+ */
+export function loadNotesConfig(source: EnvSource = process.env) {
+	const env = createEnv(source);
+	const port = env.integer('APP_PORT', 3000);
+	const pageSize = env.integer('NOTES_PAGE_SIZE', 20);
+	if (port < 1 || port > 65_535) throw new Error('APP_PORT must be between 1 and 65535.');
+	if (pageSize < 1 || pageSize > 100) throw new Error('NOTES_PAGE_SIZE must be between 1 and 100.');
+	const webhookEnabled = env.boolean('WEBHOOK_ENABLED', false);
+	const webhookKey = webhookEnabled ? env.required('WEBHOOK_KEY') : undefined;
+	if (webhookEnabled && !webhookKey?.trim()) throw new Error('WEBHOOK_KEY cannot contain only whitespace.');
+	return defineConfig({
+		name: env('APP_NAME', 'My notes'),
+		port,
+		pageSize,
+		debug: env.boolean('APP_DEBUG', false),
+		allowedOrigins: env.array('ALLOWED_ORIGINS', []),
+		webhook: { enabled: webhookEnabled, key: webhookKey },
+	});
+}

package/src/config/examples/runConfig.ts

@@ -0,0 +1,40 @@
+import 'dotenv/config';
+import { pathToFileURL } from 'node:url';
+import type { EnvSource } from '@db3.ai/app/config';
+import { App } from '@db3.ai/app/server';
+import { loadNotesConfig } from './loadNotesConfig';
+
+/**
+ * Boots configuration and URL generation without opening HTTP or SQL connections.
+ *
+ * @param source - App settings; no process-global environment changes are needed.
+ * @returns A deliberately selected public summary, never the complete config.
+ */
+export async function runConfig(source: EnvSource = process.env) {
+	const notes = loadNotesConfig(source);
+	const application = new App({
+		config: { notes },
+		url: { baseUrl: `http://localhost:${notes.port}` },
+		dbOptions: { syncColumns: false },
+	});
+	try {
+		return {
+			name: application.config.get<string>('notes.name'),
+			port: notes.port,
+			notesUrl: application.url.to('/notes'),
+			pageSize: notes.pageSize,
+			debug: notes.debug,
+			allowedOrigins: notes.allowedOrigins,
+			missingValue: application.config.get('notes.missing', 'fallback'),
+			hasWebhook: application.config.has('notes.webhook'),
+			webhookEnabled: notes.webhook.enabled,
+			configReused: application.config === application.config,
+		};
+	} finally {
+		await application.close();
+	}
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+	console.log(JSON.stringify(await runConfig(), null, 2));
+}

package/src/config/index.ts

@@ -0,0 +1,2 @@
+export * from './Config';
+export * from './env';

package/src/db/ActiveProjection.ts

@@ -0,0 +1,311 @@
+import {
+	DbRow,
+	FieldConfig,
+	type FieldClass,
+	type FieldDbValue,
+	type FieldDefinition,
+	type FieldDisplayValue,
+	type FieldInputMap,
+	type FieldInputValue,
+	type FieldMap,
+	FieldType,
+	type FieldValue,
+} from './FieldType';
+import type {
+	ActiveRecordClass,
+} from './ActiveRecord';
+import {
+	field,
+	type FieldBuilder,
+} from './fields/field';
+
+export interface ProjectionSourceFieldOptions {
+	/** Row key used when a query aliases the source column. */
+	alias?: string;
+
+	/** Explicit row key. Defaults to `alias`, then the source field's DB column. */
+	column?: string;
+
+	/** Projection-only default used when the row omits the projected column. */
+	default?: FieldConfig['default'];
+}
+
+export interface ProjectionFromModelOptions {
+	/** Optional logical fields to include from the source model. Defaults to all fields. */
+	fields?: readonly string[];
+
+	/** Optional logical fields to omit from the source model. */
+	except?: readonly string[];
+
+	/** Prefix for projected logical field names. */
+	prefix?: string;
+
+	/** Per-field aliases used by the query row. */
+	aliases?: Record<string, string>;
+
+	/** Per-field projection defaults. */
+	defaults?: Record<string, FieldConfig['default']>;
+}
+
+export interface ProjectionFieldBuilder extends FieldBuilder {
+	from<
+		TModel extends { fields(field: FieldBuilder): FieldInputMap } & ActiveRecordClass,
+		TFieldName extends keyof ModelFieldInputs<TModel> & string,
+	>(
+		Model: TModel,
+		fieldName: TFieldName,
+		options?: ProjectionSourceFieldOptions,
+	): ResolvedFieldInput<ModelFieldInputs<TModel>[TFieldName]>;
+
+	fromModel<TModel extends ActiveRecordClass>(
+		Model: TModel,
+		options?: ProjectionFromModelOptions,
+	): FieldInputMap;
+}
+
+export type ActiveProjectionConstructor<TProjection extends ActiveProjection = ActiveProjection> = {
+	new(row?: DbRow): TProjection;
+};
+
+export type ActiveProjectionClass<TProjection extends ActiveProjection = ActiveProjection> =
+	ActiveProjectionConstructor<TProjection> & {
+		readonly name: string;
+		table: string;
+		primaryKey: string;
+		fields(field: ProjectionFieldBuilder): FieldInputMap;
+		getFields(): FieldMap;
+		fromDb<TClass extends ActiveProjectionConstructor>(
+			this: TClass,
+			row: DbRow,
+		): InstanceType<TClass>;
+		fromDbRows<TClass extends ActiveProjectionConstructor>(
+			this: TClass,
+			rows: readonly DbRow[],
+		): InstanceType<TClass>[];
+	};
+
+const resolvedProjectionFields = new WeakMap<ActiveProjectionClass, FieldMap>();
+
+export abstract class ActiveProjection {
+	static table = 'projection';
+	static primaryKey = 'id';
+
+	static fields(_field: ProjectionFieldBuilder): FieldInputMap {
+		return {};
+	}
+
+	private readonly $fields: Record<string, FieldType<any, any, any, any, any>> = {};
+
+	constructor(row: DbRow = {}) {
+		const Projection = this.$projection();
+
+		for (const [fieldName, field] of Object.entries(Projection.getFields())) {
+			const liveField = field.clone().bindToRecord(Projection, this, fieldName);
+
+			this.$fields[fieldName] = liveField;
+			this.$installAccessor(fieldName);
+		}
+
+		this.setFromDb(row);
+	}
+
+	static getFields<TProjection extends ActiveProjection>(
+		this: ActiveProjectionClass<TProjection>,
+	): FieldMap {
+		const cached = resolvedProjectionFields.get(this);
+
+		if (cached) {
+			return cached;
+		}
+
+		const fields: FieldMap = {};
+
+		for (const [fieldName, fieldInput] of Object.entries(this.fields(projectionField))) {
+			fields[fieldName] = resolveProjectionFieldInput(fieldInput).bindToModel(
+				this,
+				fieldName,
+			);
+		}
+
+		resolvedProjectionFields.set(this, fields);
+
+		return fields;
+	}
+
+	static fromDb<TClass extends ActiveProjectionConstructor>(
+		this: TClass,
+		row: DbRow,
+	): InstanceType<TClass> {
+		return new this(row) as InstanceType<TClass>;
+	}
+
+	static fromDbRows<TClass extends ActiveProjectionConstructor>(
+		this: TClass,
+		rows: readonly DbRow[],
+	): InstanceType<TClass>[] {
+		return rows.map(row => new this(row) as InstanceType<TClass>);
+	}
+
+	setFromDb(row: DbRow): this {
+		for (const field of Object.values(this.$fields)) {
+			field.hydrate(row);
+			field.markBoundClean();
+		}
+
+		return this;
+	}
+
+	get(fieldName: string): unknown {
+		return this.$field(fieldName).value;
+	}
+
+	toAppData(): Record<string, unknown> {
+		const data: Record<string, unknown> = {};
+
+		for (const [fieldName, field] of Object.entries(this.$fields)) {
+			if (field.config.hidden) continue;
+
+			data[fieldName] = field.value;
+		}
+
+		return data;
+	}
+
+	toDisplayData(): Record<string, unknown> {
+		const data: Record<string, unknown> = {};
+
+		for (const [fieldName, field] of Object.entries(this.$fields)) {
+			const value = field.getBoundDisplayValue();
+
+			if (value !== undefined) {
+				data[fieldName] = value;
+			}
+		}
+
+		return data;
+	}
+
+	toJSON(): Record<string, unknown> {
+		return this.toDisplayData();
+	}
+
+	protected $field(fieldName: string): FieldType<any, any, any, any, any> {
+		const field = this.$fields[fieldName];
+
+		if (!field) {
+			throw new Error(`Unknown projection field "${fieldName}"`);
+		}
+
+		return field;
+	}
+
+	private $projection<TProjection extends ActiveProjection>(): ActiveProjectionClass<TProjection> {
+		return this.constructor as ActiveProjectionClass<TProjection>;
+	}
+
+	private $installAccessor(fieldName: string): void {
+		if (Object.prototype.hasOwnProperty.call(this, fieldName)) {
+			return;
+		}
+
+		Object.defineProperty(this, fieldName, {
+			enumerable: true,
+			configurable: true,
+
+			get: () => this.get(fieldName),
+		});
+	}
+}
+
+export const projectionField: ProjectionFieldBuilder = {
+	...field,
+
+	from(Model, fieldName, options = {}) {
+		const source = Model.getField(fieldName);
+		const column = options.column
+			?? options.alias
+			?? source.getColumnFor(Model, fieldName);
+
+		return source.withConfig({
+			column,
+			default: options.default ?? source.config.default,
+		}) as ResolvedFieldInput<ModelFieldInputs<typeof Model>[typeof fieldName]>;
+	},
+
+	fromModel(Model, options = {}) {
+		const fields: FieldInputMap = {};
+		const included = options.fields ? new Set(options.fields) : null;
+		const excluded = new Set(options.except ?? []);
+
+		for (const fieldName of Object.keys(Model.getFields())) {
+			if (included && !included.has(fieldName)) continue;
+			if (excluded.has(fieldName)) continue;
+
+			const projectedName = options.prefix
+				? `${options.prefix}${fieldName.slice(0, 1).toUpperCase()}${fieldName.slice(1)}`
+				: fieldName;
+
+			fields[projectedName] = projectionField.from(Model, fieldName, {
+				alias: options.aliases?.[fieldName],
+				default: options.defaults?.[fieldName],
+			});
+		}
+
+		return fields;
+	},
+};
+
+function resolveProjectionFieldInput<TField extends FieldType<any, any, any, any, any>>(
+	input: FieldClass<TField> | FieldDefinition<TField> | TField,
+): TField {
+	if (typeof input === 'function') {
+		return new input();
+	}
+
+	if (input instanceof FieldType) {
+		return input.clone() as TField;
+	}
+
+	if (input && typeof input === 'object' && 'type' in input) {
+		return new input.type(input.config);
+	}
+
+	throw new Error('Invalid projection field definition.');
+}
+
+type ResolvedFieldInput<TInput> =
+	TInput extends FieldType<any, any, any, any, any>
+		? TInput
+		: TInput extends FieldClass<infer TField>
+			? TField
+			: TInput extends FieldDefinition<infer TField>
+				? TField
+				: never;
+
+type ModelFieldInputs<TModel extends { fields(field: FieldBuilder): FieldInputMap }> =
+	ReturnType<TModel['fields']>;
+
+type ProjectionFieldInputs<TProjection extends { fields(field: ProjectionFieldBuilder): FieldInputMap }> =
+	ReturnType<TProjection['fields']>;
+
+export namespace ActiveProjection {
+	export type InferInput<TProjection extends { fields(field: ProjectionFieldBuilder): FieldInputMap }> = {
+		[fieldName in keyof ProjectionFieldInputs<TProjection>]:
+			FieldInputValue<ResolvedFieldInput<ProjectionFieldInputs<TProjection>[fieldName]>>;
+	};
+
+	export type InferValue<TProjection extends { fields(field: ProjectionFieldBuilder): FieldInputMap }> = {
+		[fieldName in keyof ProjectionFieldInputs<TProjection>]:
+			FieldValue<ResolvedFieldInput<ProjectionFieldInputs<TProjection>[fieldName]>>;
+	};
+
+	export type InferDbRow<TProjection extends { fields(field: ProjectionFieldBuilder): FieldInputMap }> = {
+		[fieldName in keyof ProjectionFieldInputs<TProjection>]:
+			FieldDbValue<ResolvedFieldInput<ProjectionFieldInputs<TProjection>[fieldName]>>;
+	};
+
+	export type InferDisplay<TProjection extends { fields(field: ProjectionFieldBuilder): FieldInputMap }> = {
+		[fieldName in keyof ProjectionFieldInputs<TProjection>]:
+			FieldDisplayValue<ResolvedFieldInput<ProjectionFieldInputs<TProjection>[fieldName]>>;
+	};
+}