@db3.ai/app 0.1.0-beta.1

package/dist/config/Config.d.ts

@@ -0,0 +1,48 @@
+export type ConfigValues = Record<string, unknown>;
+/**
+ * Runtime configuration repository with dot-path reads.
+ */
+export declare class Config<TValues extends ConfigValues = ConfigValues> {
+    private readonly values;
+    /**
+     * Creates a config repository from a plain object.
+     *
+     * @param values - Config values to expose.
+     */
+    constructor(values?: TValues);
+    /**
+     * Returns all config values.
+     *
+     * @returns Config object supplied to this repository.
+     */
+    all(): TValues;
+    /**
+     * Reads a config value by dot path.
+     *
+     * @param path - Dot-separated config path.
+     * @returns Config value or undefined when the path is missing.
+     */
+    get<TValue = unknown>(path: string): TValue | undefined;
+    /**
+     * Reads a config value by dot path with a fallback.
+     *
+     * @param path - Dot-separated config path.
+     * @param fallback - Value to return when the path is missing.
+     * @returns Config value or fallback.
+     */
+    get<TValue>(path: string, fallback: TValue): TValue;
+    /**
+     * Returns true when a dot path exists in this config repository.
+     *
+     * @param path - Dot-separated config path.
+     * @returns True when the path exists.
+     */
+    has(path: string): boolean;
+}
+/**
+ * Defines a typed config object without changing its runtime shape.
+ *
+ * @param values - Config values to preserve.
+ * @returns The same config values.
+ */
+export declare function defineConfig<TValues extends ConfigValues>(values: TValues): TValues;

package/dist/config/Config.js

@@ -0,0 +1,80 @@
+/**
+ * Runtime configuration repository with dot-path reads.
+ */
+export class Config {
+    values;
+    /**
+     * Creates a config repository from a plain object.
+     *
+     * @param values - Config values to expose.
+     */
+    constructor(values = {}) {
+        this.values = values;
+    }
+    /**
+     * Returns all config values.
+     *
+     * @returns Config object supplied to this repository.
+     */
+    all() {
+        return this.values;
+    }
+    get(path, fallback) {
+        const result = resolveConfigPath(this.values, path);
+        if (!result.exists)
+            return fallback;
+        return result.value;
+    }
+    /**
+     * Returns true when a dot path exists in this config repository.
+     *
+     * @param path - Dot-separated config path.
+     * @returns True when the path exists.
+     */
+    has(path) {
+        return resolveConfigPath(this.values, path).exists;
+    }
+}
+/**
+ * Defines a typed config object without changing its runtime shape.
+ *
+ * @param values - Config values to preserve.
+ * @returns The same config values.
+ */
+export function defineConfig(values) {
+    return values;
+}
+/**
+ * Resolves a dot path against a config object.
+ *
+ * @param values - Config object to inspect.
+ * @param path - Dot-separated config path.
+ * @returns Resolution result containing existence and value.
+ */
+function resolveConfigPath(values, path) {
+    if (!path) {
+        throw new Error('Config path cannot be empty.');
+    }
+    const segments = path.split('.');
+    if (segments.some(segment => !segment)) {
+        throw new Error(`Config path "${path}" contains an empty segment.`);
+    }
+    let current = values;
+    for (const segment of segments) {
+        if (typeof current !== 'object' || current === null || Array.isArray(current)) {
+            return {
+                exists: false,
+            };
+        }
+        if (!Object.hasOwn(current, segment)) {
+            return {
+                exists: false,
+            };
+        }
+        current = current[segment];
+    }
+    return {
+        exists: true,
+        value: current,
+    };
+}

package/dist/config/env.d.ts

@@ -0,0 +1,26 @@
+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 declare function createEnv(source?: EnvSource): EnvReader;
+export declare const env: EnvReader;

package/dist/config/env.js

@@ -0,0 +1,117 @@
+/**
+ * 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 = process.env) {
+    const reader = ((name, fallback) => {
+        const value = source[name];
+        return value === undefined ? fallback : value;
+    });
+    reader.required = (name) => {
+        const value = source[name];
+        if (value === undefined || value === '') {
+            throw new Error(`Environment variable "${name}" is required.`);
+        }
+        return value;
+    };
+    reader.string = ((name, fallback) => {
+        const value = source[name];
+        return value === undefined ? fallback : value;
+    });
+    reader.boolean = ((name, fallback) => {
+        const value = optionalEnvValue(source, name);
+        if (value === undefined)
+            return fallback;
+        return parseEnvBoolean(name, value);
+    });
+    reader.number = ((name, fallback) => {
+        const value = optionalEnvValue(source, name);
+        if (value === undefined)
+            return fallback;
+        return parseEnvNumber(name, value);
+    });
+    reader.integer = ((name, fallback) => {
+        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;
+    });
+    reader.array = ((name, fallback) => {
+        const value = optionalEnvValue(source, name);
+        if (value === undefined)
+            return fallback;
+        return value
+            .split(',')
+            .map(item => item.trim())
+            .filter(item => item.length > 0);
+    });
+    reader.json = ((name, fallback) => {
+        const value = optionalEnvValue(source, name);
+        if (value === undefined)
+            return fallback;
+        try {
+            return JSON.parse(value);
+        }
+        catch (error) {
+            throw new Error(`Environment variable "${name}" must contain valid JSON.`, {
+                cause: error,
+            });
+        }
+    });
+    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, name) {
+    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, value) {
+    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, value) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed)) {
+        throw new Error(`Environment variable "${name}" must be a number.`);
+    }
+    return parsed;
+}

package/dist/config/index.d.ts

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

package/dist/config/index.js

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

package/dist/db/ActiveProjection.d.ts

@@ -0,0 +1,90 @@
+import { DbRow, FieldConfig, type FieldClass, type FieldDbValue, type FieldDefinition, type FieldDisplayValue, type FieldInputMap, type FieldInputValue, type FieldMap, FieldType, type FieldValue } from './FieldType.js';
+import type { ActiveRecordClass } from './ActiveRecord.js';
+import { type FieldBuilder } from './fields/field.js';
+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>[];
+};
+export declare abstract class ActiveProjection {
+    static table: string;
+    static primaryKey: string;
+    static fields(_field: ProjectionFieldBuilder): FieldInputMap;
+    private readonly $fields;
+    constructor(row?: DbRow);
+    static getFields<TProjection extends ActiveProjection>(this: ActiveProjectionClass<TProjection>): FieldMap;
+    static fromDb<TClass extends ActiveProjectionConstructor>(this: TClass, row: DbRow): InstanceType<TClass>;
+    static fromDbRows<TClass extends ActiveProjectionConstructor>(this: TClass, rows: readonly DbRow[]): InstanceType<TClass>[];
+    setFromDb(row: DbRow): this;
+    get(fieldName: string): unknown;
+    toAppData(): Record<string, unknown>;
+    toDisplayData(): Record<string, unknown>;
+    toJSON(): Record<string, unknown>;
+    protected $field(fieldName: string): FieldType<any, any, any, any, any>;
+    private $projection;
+    private $installAccessor;
+}
+export declare const projectionField: ProjectionFieldBuilder;
+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 declare namespace ActiveProjection {
+    type InferInput<TProjection extends {
+        fields(field: ProjectionFieldBuilder): FieldInputMap;
+    }> = {
+        [fieldName in keyof ProjectionFieldInputs<TProjection>]: FieldInputValue<ResolvedFieldInput<ProjectionFieldInputs<TProjection>[fieldName]>>;
+    };
+    type InferValue<TProjection extends {
+        fields(field: ProjectionFieldBuilder): FieldInputMap;
+    }> = {
+        [fieldName in keyof ProjectionFieldInputs<TProjection>]: FieldValue<ResolvedFieldInput<ProjectionFieldInputs<TProjection>[fieldName]>>;
+    };
+    type InferDbRow<TProjection extends {
+        fields(field: ProjectionFieldBuilder): FieldInputMap;
+    }> = {
+        [fieldName in keyof ProjectionFieldInputs<TProjection>]: FieldDbValue<ResolvedFieldInput<ProjectionFieldInputs<TProjection>[fieldName]>>;
+    };
+    type InferDisplay<TProjection extends {
+        fields(field: ProjectionFieldBuilder): FieldInputMap;
+    }> = {
+        [fieldName in keyof ProjectionFieldInputs<TProjection>]: FieldDisplayValue<ResolvedFieldInput<ProjectionFieldInputs<TProjection>[fieldName]>>;
+    };
+}
+export {};

package/dist/db/ActiveProjection.js

@@ -0,0 +1,134 @@
+import { FieldType, } from './FieldType.js';
+import { field, } from './fields/field.js';
+const resolvedProjectionFields = new WeakMap();
+export class ActiveProjection {
+    static table = 'projection';
+    static primaryKey = 'id';
+    static fields(_field) {
+        return {};
+    }
+    $fields = {};
+    constructor(row = {}) {
+        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() {
+        const cached = resolvedProjectionFields.get(this);
+        if (cached) {
+            return cached;
+        }
+        const fields = {};
+        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(row) {
+        return new this(row);
+    }
+    static fromDbRows(rows) {
+        return rows.map(row => new this(row));
+    }
+    setFromDb(row) {
+        for (const field of Object.values(this.$fields)) {
+            field.hydrate(row);
+            field.markBoundClean();
+        }
+        return this;
+    }
+    get(fieldName) {
+        return this.$field(fieldName).value;
+    }
+    toAppData() {
+        const data = {};
+        for (const [fieldName, field] of Object.entries(this.$fields)) {
+            if (field.config.hidden)
+                continue;
+            data[fieldName] = field.value;
+        }
+        return data;
+    }
+    toDisplayData() {
+        const data = {};
+        for (const [fieldName, field] of Object.entries(this.$fields)) {
+            const value = field.getBoundDisplayValue();
+            if (value !== undefined) {
+                data[fieldName] = value;
+            }
+        }
+        return data;
+    }
+    toJSON() {
+        return this.toDisplayData();
+    }
+    $field(fieldName) {
+        const field = this.$fields[fieldName];
+        if (!field) {
+            throw new Error(`Unknown projection field "${fieldName}"`);
+        }
+        return field;
+    }
+    $projection() {
+        return this.constructor;
+    }
+    $installAccessor(fieldName) {
+        if (Object.prototype.hasOwnProperty.call(this, fieldName)) {
+            return;
+        }
+        Object.defineProperty(this, fieldName, {
+            enumerable: true,
+            configurable: true,
+            get: () => this.get(fieldName),
+        });
+    }
+}
+export const projectionField = {
+    ...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,
+        });
+    },
+    fromModel(Model, options = {}) {
+        const fields = {};
+        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(input) {
+    if (typeof input === 'function') {
+        return new input();
+    }
+    if (input instanceof FieldType) {
+        return input.clone();
+    }
+    if (input && typeof input === 'object' && 'type' in input) {
+        return new input.type(input.config);
+    }
+    throw new Error('Invalid projection field definition.');
+}