@db3.ai/app 0.1.0-beta.1

package/dist/db/SoftDeletes.d.ts

@@ -0,0 +1,30 @@
+import type { ActiveRecordClass } from './ActiveRecord.js';
+import type { DbWriteData, FieldType } from './FieldType.js';
+export type ActiveRecordSoftDeleteConfig = boolean | string;
+export type ActiveRecordSoftDeleteScope = 'without' | 'with' | 'only';
+export interface ActiveRecordSoftDeleteField {
+    fieldName: string;
+    field: FieldType<any, any, any, any, any>;
+    column: string;
+}
+export declare const DEFAULT_SOFT_DELETE_FIELD = "deletedAt";
+/**
+ * Returns true when the model has soft deletes enabled.
+ */
+export declare function modelUsesSoftDeletes(Model: ActiveRecordClass): boolean;
+/**
+ * Returns the configured soft-delete timestamp field for a model, when enabled.
+ */
+export declare function getSoftDeleteField(Model: ActiveRecordClass): ActiveRecordSoftDeleteField | null;
+/**
+ * Returns the configured soft-delete field or throws when the model is not soft deletable.
+ */
+export declare function requireSoftDeleteField(Model: ActiveRecordClass): ActiveRecordSoftDeleteField;
+/**
+ * Builds field-aware update data for soft delete or restore operations.
+ */
+export declare function getSoftDeleteWriteData(Model: ActiveRecordClass, deletedAt: Date | null, updatedAt?: Date): DbWriteData;
+/**
+ * Returns logical timestamp field names that should update on row updates.
+ */
+export declare function getAutomaticUpdateTimestampFieldNames(Model: ActiveRecordClass, ignoredFieldNames?: ReadonlySet<string>): string[];

package/dist/db/SoftDeletes.js

@@ -0,0 +1,93 @@
+export const DEFAULT_SOFT_DELETE_FIELD = 'deletedAt';
+/**
+ * Returns true when the model has soft deletes enabled.
+ */
+export function modelUsesSoftDeletes(Model) {
+    return resolveSoftDeleteFieldName(Model) !== null;
+}
+/**
+ * Returns the configured soft-delete timestamp field for a model, when enabled.
+ */
+export function getSoftDeleteField(Model) {
+    const fieldName = resolveSoftDeleteFieldName(Model);
+    if (!fieldName) {
+        return null;
+    }
+    const field = Model.getFields()[fieldName];
+    if (!field) {
+        throw new Error(`Model ${Model.name} enables soft deletes with field "${fieldName}", but that field is not defined.`);
+    }
+    return {
+        fieldName,
+        field,
+        column: field.column,
+    };
+}
+/**
+ * Returns the configured soft-delete field or throws when the model is not soft deletable.
+ */
+export function requireSoftDeleteField(Model) {
+    const softDeleteField = getSoftDeleteField(Model);
+    if (!softDeleteField) {
+        throw new Error(`Model ${Model.name} does not use soft deletes.`);
+    }
+    return softDeleteField;
+}
+/**
+ * Builds field-aware update data for soft delete or restore operations.
+ */
+export function getSoftDeleteWriteData(Model, deletedAt, updatedAt = new Date()) {
+    const softDeleteField = requireSoftDeleteField(Model);
+    const ignoredFieldNames = new Set([softDeleteField.fieldName]);
+    return {
+        [softDeleteField.column]: softDeleteField.field.getQueryValue(deletedAt),
+        ...getAutomaticUpdateTimestampWriteData(Model, updatedAt, ignoredFieldNames),
+    };
+}
+/**
+ * Returns logical timestamp field names that should update on row updates.
+ */
+export function getAutomaticUpdateTimestampFieldNames(Model, ignoredFieldNames = new Set()) {
+    return Object.entries(Model.getFields())
+        .flatMap(([fieldName, field]) => {
+        if (ignoredFieldNames.has(fieldName))
+            return [];
+        if (!isAutomaticUpdateTimestampField(field))
+            return [];
+        return [fieldName];
+    });
+}
+/**
+ * Builds update timestamp columns for soft delete and restore writes.
+ */
+function getAutomaticUpdateTimestampWriteData(Model, updatedAt, ignoredFieldNames) {
+    const row = {};
+    for (const fieldName of getAutomaticUpdateTimestampFieldNames(Model, ignoredFieldNames)) {
+        const field = Model.getField(fieldName);
+        row[field.column] = field.getQueryValue(updatedAt);
+    }
+    return row;
+}
+/**
+ * Resolves the model's soft-delete config to a logical timestamp field name.
+ */
+function resolveSoftDeleteFieldName(Model) {
+    const config = Model.softDeletes;
+    if (!config) {
+        return null;
+    }
+    if (config === true) {
+        return DEFAULT_SOFT_DELETE_FIELD;
+    }
+    if (typeof config === 'string' && config.trim()) {
+        return config.trim();
+    }
+    throw new Error(`Model ${Model.name} has an invalid soft delete configuration.`);
+}
+/**
+ * Returns true when a field should receive update timestamps automatically.
+ */
+function isAutomaticUpdateTimestampField(field) {
+    const config = field.config;
+    return config.auto === 'update' || config.auto === 'both';
+}

package/dist/db/commands/check.d.ts

@@ -0,0 +1,6 @@
+import type { DatabaseCheckResult } from '../migrations/contracts/index.js';
+/**
+ * Checks the active app's database, models, snapshot and migration history.
+ * @returns Consistency findings for CLI, application or authorized UI callers.
+ */
+export default function check(): Promise<DatabaseCheckResult>;

package/dist/db/commands/check.js

@@ -0,0 +1,8 @@
+import { app } from '../../server/index.js';
+/**
+ * Checks the active app's database, models, snapshot and migration history.
+ * @returns Consistency findings for CLI, application or authorized UI callers.
+ */
+export default async function check() {
+    return app().db.migrations.check();
+}

package/dist/db/commands/index.d.ts

@@ -0,0 +1,6 @@
+import migrate from './migrate.js';
+import check from './check.js';
+import makeMigration from './makeMigration.js';
+export { migrate, check, makeMigration };
+/** Explicit service command index; action files remain directly importable programmatic operations. */
+export declare const databaseCommands: import("../../cli/index.js").CliCommand[];

package/dist/db/commands/index.js

@@ -0,0 +1,17 @@
+import { defineCommand } from '../../cli/index.js';
+import migrate from './migrate.js';
+import check from './check.js';
+import makeMigration from './makeMigration.js';
+export { migrate, check, makeMigration };
+/** Explicit service command index; action files remain directly importable programmatic operations. */
+export const databaseCommands = [
+    defineCommand({ name: 'db:migrate', description: 'Apply committed pending database migrations.', handle: migrate }),
+    defineCommand({ name: 'db:check', description: 'Check model, snapshot and live database consistency.', handle: check, exitCode: result => result.matches ? 0 : 1 }),
+    defineCommand({
+        name: 'db:make-migration', description: 'Generate a migration and snapshot from model changes.',
+        parameters: [{ name: 'name' }],
+        /** Maps the CLI name to the action's normal options object. */
+        handle: parameters => makeMigration({ name: parameters.name }),
+        exitCode: result => result.blocked ? 1 : 0,
+    }),
+];

package/dist/db/commands/makeMigration.d.ts

@@ -0,0 +1,7 @@
+import type { MakeMigrationOptions, MakeMigrationResult } from '../migrations/contracts/index.js';
+/**
+ * Generates reviewable migration source from the active app's model changes.
+ * @param options - Optional name and explicitly requested source-generation policy.
+ * @returns Generated source location or blocked changes; production restrictions remain enforced.
+ */
+export default function makeMigration(options?: MakeMigrationOptions): Promise<MakeMigrationResult>;

package/dist/db/commands/makeMigration.js

@@ -0,0 +1,9 @@
+import { app } from '../../server/index.js';
+/**
+ * Generates reviewable migration source from the active app's model changes.
+ * @param options - Optional name and explicitly requested source-generation policy.
+ * @returns Generated source location or blocked changes; production restrictions remain enforced.
+ */
+export default async function makeMigration(options = {}) {
+    return app().db.migrations.makeMigration(options);
+}

package/dist/db/commands/migrate.d.ts

@@ -0,0 +1,6 @@
+import type { MigrateResult } from '../migrations/contracts/index.js';
+/**
+ * Applies the active app's committed pending migrations and returns their results.
+ * @returns Applied and baselined filenames without terminal formatting.
+ */
+export default function migrate(): Promise<MigrateResult>;

package/dist/db/commands/migrate.js

@@ -0,0 +1,8 @@
+import { app } from '../../server/index.js';
+/**
+ * Applies the active app's committed pending migrations and returns their results.
+ * @returns Applied and baselined filenames without terminal formatting.
+ */
+export default async function migrate() {
+    return app().db.migrations.migrate();
+}

package/dist/db/connection.d.ts

@@ -0,0 +1,10 @@
+import 'dotenv/config';
+import { type Knex } from 'knex';
+/**
+ * Returns the shared application database connection.
+ */
+export declare function db(): Knex;
+/**
+ * Closes and clears the shared application database connection.
+ */
+export declare function destroyDatabase(): Promise<void>;

package/dist/db/connection.js

@@ -0,0 +1,55 @@
+import 'dotenv/config';
+import knex from 'knex';
+import { rememberDatabaseDialect, resolveDatabaseDialect, } from './dialects/index.js';
+let database = null;
+/**
+ * Reads a required environment variable for database connection setup.
+ */
+function requiredEnv(name) {
+    const value = process.env[name];
+    if (!value) {
+        throw new Error(`Missing required database environment variable ${name}.`);
+    }
+    return value;
+}
+/**
+ * Builds a Knex connection value from the current process environment.
+ */
+function databaseConnection(dialect) {
+    if (process.env.DATABASE_URL)
+        return process.env.DATABASE_URL;
+    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: requiredEnv('DB_DATABASE'),
+    };
+}
+/**
+ * Returns the shared application database connection.
+ */
+export function db() {
+    if (!database) {
+        const dialect = resolveDatabaseDialect();
+        database = knex({
+            client: dialect.knexClient,
+            connection: databaseConnection(dialect),
+            pool: {
+                min: Number(process.env.DB_POOL_MIN || 0),
+                max: Number(process.env.DB_POOL_MAX || 10),
+            },
+        });
+        rememberDatabaseDialect(database, dialect);
+    }
+    return database;
+}
+/**
+ * Closes and clears the shared application database connection.
+ */
+export async function destroyDatabase() {
+    if (!database)
+        return;
+    await database.destroy();
+    database = null;
+}

package/dist/db/contracts/ActiveRecordDefinition.d.ts

@@ -0,0 +1,64 @@
+import type { ActiveRecord, ActiveRecordOptions } from '../ActiveRecord.js';
+import type { FieldInputMap, FieldInputValue, FieldValue } from '../FieldType.js';
+import type { FieldBuilder } from '../fields/field.js';
+/** A model constructor whose fields can be extended by `ActiveRecord.define()`. */
+export type ActiveRecordDefinitionBase = (abstract new (input?: Record<string, unknown>, options?: ActiveRecordOptions) => ActiveRecord) & {
+    /** Existing field factory, including definitions inherited by the model. */
+    fields(field: FieldBuilder): FieldInputMap;
+};
+/** Field definitions known statically; a dynamic base contributes no inferred keys. */
+export type ActiveRecordDefinedFields<TBase extends ActiveRecordDefinitionBase> = string extends keyof ReturnType<TBase['fields']> ? {} : ReturnType<TBase['fields']>;
+/** Complete field map after a definition replaces matching inherited fields. */
+export type ActiveRecordMergedFields<TBase extends ActiveRecordDefinitionBase, TFields extends FieldInputMap> = Omit<ActiveRecordDefinedFields<TBase>, keyof TFields> & TFields;
+/**
+ * Schema options for an inferred model. Omitted settings inherit from the base.
+ * Fields use the same builder, field classes and configured definitions as
+ * ordinary static `fields()` declarations.
+ */
+export interface ActiveRecordDefinition<TFields extends FieldInputMap> {
+    table?: string;
+    primaryKey?: string;
+    comment?: string;
+    labelFields?: string[];
+    requestFillable?: readonly string[];
+    requestGuarded?: readonly string[];
+    returning?: boolean;
+    softDeletes?: typeof ActiveRecord.softDeletes;
+    /** Supplies this layer's fields; inherited names replace the whole definition. */
+    fields(field: FieldBuilder): TFields;
+}
+/**
+ * Rejects overrides that change application or input types, and fields that
+ * collide with existing non-field members. Inherited methods can therefore
+ * continue to use the properties they were written against.
+ */
+export type ActiveRecordFieldOverrides<TBase extends ActiveRecordDefinitionBase, TFields extends FieldInputMap> = {
+    [TKey in keyof TFields]: [ActiveRecord.ResolvedField<TFields[TKey]>] extends [never] ? never : TKey extends keyof ActiveRecordDefinedFields<TBase> ? SameFieldBoundary<TFields[TKey], ActiveRecordDefinedFields<TBase>[TKey]> : TKey extends keyof InstanceType<TBase> ? never : TFields[TKey];
+};
+/** Compares both directions because inherited methods may read and write values. */
+type SameFieldBoundary<TField, TParent> = [
+    FieldValue<ActiveRecord.ResolvedField<TField>>,
+    FieldInputValue<ActiveRecord.ResolvedField<TField>>
+] extends [
+    FieldValue<ActiveRecord.ResolvedField<TParent>>,
+    FieldInputValue<ActiveRecord.ResolvedField<TParent>>
+] ? [FieldValue<ActiveRecord.ResolvedField<TParent>>, FieldInputValue<ActiveRecord.ResolvedField<TParent>>] extends [
+    FieldValue<ActiveRecord.ResolvedField<TField>>,
+    FieldInputValue<ActiveRecord.ResolvedField<TField>>
+] ? TField : never : never;
+/**
+ * Inferred subclass with the original static methods and a single constructor
+ * signature. Keeping statics generic in their receiver preserves later ordinary
+ * subclasses, their custom methods, and further calls to `define()`.
+ */
+export type DefinedActiveRecord<TBase extends ActiveRecordDefinitionBase, TFields extends FieldInputMap> = Omit<TBase, 'prototype' | 'fields'> & {
+    /** Creates a record in memory; persistence still requires `save()`. */
+    new (input?: Partial<ActiveRecord.InferInput<{
+        fields: (field: FieldBuilder) => ActiveRecordMergedFields<TBase, TFields>;
+    }>>, options?: ActiveRecordOptions): InstanceType<TBase> & ActiveRecord.InferValue<{
+        fields: (field: FieldBuilder) => ActiveRecordMergedFields<TBase, TFields>;
+    }>;
+    /** Preserves concrete field types for inference and future bound-field APIs. */
+    fields(field: FieldBuilder): ActiveRecordMergedFields<TBase, TFields>;
+};
+export {};

package/dist/db/contracts/ActiveRecordDefinition.js

@@ -0,0 +1 @@
+export {};

package/dist/db/contracts/DatabaseBackup.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Application-provided implementation behind the database backup API.
+ *
+ * The database package owns the stable invocation surface while each app owns
+ * the concrete dump format, storage destinations, and retention policy.
+ */
+export type DatabaseBackupHandler = (request: Record<string, unknown>) => Promise<unknown>;

package/dist/db/contracts/DatabaseBackup.js

@@ -0,0 +1 @@
+export {};

package/dist/db/contracts/DatabaseMigrationsConfig.d.ts

@@ -0,0 +1,9 @@
+import type { DatabaseMigrationManagerOptions } from '../migrations/contracts/index.js';
+/**
+ * App-owned model registry and migration policy.
+ *
+ * The database service supplies its connection and dialect. Committed migrations
+ * always live in server/database/migrations and the snapshot in
+ * server/database/schema.snapshot.json, relative to the application directory.
+ */
+export type DatabaseMigrationsConfig = Omit<DatabaseMigrationManagerOptions, 'db' | 'dialect' | 'migrationsDirectory' | 'snapshotFile'>;

package/dist/db/contracts/DatabaseMigrationsConfig.js

@@ -0,0 +1 @@
+export {};

package/dist/db/contracts/index.d.ts

@@ -0,0 +1,3 @@
+export * from './DatabaseBackup.js';
+export * from './ActiveRecordDefinition.js';
+export * from './DatabaseMigrationsConfig.js';

package/dist/db/contracts/index.js

@@ -0,0 +1,3 @@
+export * from './DatabaseBackup.js';
+export * from './ActiveRecordDefinition.js';
+export * from './DatabaseMigrationsConfig.js';

package/dist/db/dialects/columnTypes.d.ts

@@ -0,0 +1,20 @@
+/**
+ * SQL column type helpers owned by each database dialect.
+ */
+export interface DatabaseColumnTypes {
+    varchar(length: number): string;
+    char(length: number): string;
+    text(): string;
+    longText(): string;
+    json(): string;
+    boolean(): string;
+    integer(options?: {
+        unsigned?: boolean;
+        big?: boolean;
+    }): string;
+    bigIncrements(): string;
+    decimal(precision: number, scale: number): string;
+    timestamp(precision?: number): string;
+}
+export declare const mysqlColumnTypes: DatabaseColumnTypes;
+export declare const postgresColumnTypes: DatabaseColumnTypes;

package/dist/db/dialects/columnTypes.js

@@ -0,0 +1,67 @@
+export const mysqlColumnTypes = {
+    varchar(length) {
+        return `varchar(${length})`;
+    },
+    char(length) {
+        return `char(${length})`;
+    },
+    text() {
+        return 'text';
+    },
+    longText() {
+        return 'longtext';
+    },
+    json() {
+        return 'json';
+    },
+    boolean() {
+        return 'boolean';
+    },
+    integer(options = {}) {
+        if (options.unsigned) {
+            return options.big ? 'bigint unsigned' : 'int unsigned';
+        }
+        return options.big ? 'bigint' : 'int';
+    },
+    bigIncrements() {
+        return 'bigint unsigned auto_increment';
+    },
+    decimal(precision, scale) {
+        return `decimal(${precision},${scale})`;
+    },
+    timestamp(precision = 0) {
+        return precision > 0 ? `timestamp(${precision})` : 'timestamp';
+    },
+};
+export const postgresColumnTypes = {
+    varchar(length) {
+        return `varchar(${length})`;
+    },
+    char(length) {
+        return `char(${length})`;
+    },
+    text() {
+        return 'text';
+    },
+    longText() {
+        return 'text';
+    },
+    json() {
+        return 'jsonb';
+    },
+    boolean() {
+        return 'boolean';
+    },
+    integer(options = {}) {
+        return options.big ? 'bigint' : 'integer';
+    },
+    bigIncrements() {
+        return 'bigserial';
+    },
+    decimal(precision, scale) {
+        return `decimal(${precision},${scale})`;
+    },
+    timestamp(precision = 0) {
+        return precision > 0 ? `timestamp(${precision})` : 'timestamp';
+    },
+};

package/dist/db/dialects/index.d.ts

@@ -0,0 +1,6 @@
+export * from './columnTypes.js';
+export * from './types.js';
+export * from './mysql.js';
+export * from './mariadb.js';
+export * from './postgres.js';
+export * from './resolveDialect.js';

package/dist/db/dialects/index.js

@@ -0,0 +1,6 @@
+export * from './columnTypes.js';
+export * from './types.js';
+export * from './mysql.js';
+export * from './mariadb.js';
+export * from './postgres.js';
+export * from './resolveDialect.js';

package/dist/db/dialects/mariadb.d.ts

@@ -0,0 +1,7 @@
+import type { DatabaseDialect } from './types.js';
+import { vectorFromDbValue } from './mysql.js';
+/**
+ * MariaDB dialect used by the framework database layer.
+ */
+export declare const mariaDbDialect: DatabaseDialect;
+export { vectorFromDbValue };

package/dist/db/dialects/mariadb.js

@@ -0,0 +1,35 @@
+import { mysqlDialect, vectorFromDbValue, } from './mysql.js';
+/**
+ * MariaDB dialect used by the framework database layer.
+ */
+export const mariaDbDialect = {
+    ...mysqlDialect,
+    name: 'mariadb',
+    knexClient: 'mysql2',
+    supportsVectorIndexes: true,
+    vectorToDbValue: vectorToMariaDbValue,
+};
+/**
+ * Converts app-memory vectors into MariaDB's native VECTOR constructor.
+ */
+function vectorToMariaDbValue(vector, db) {
+    const vectorText = JSON.stringify(validateVector(vector));
+    if (!db) {
+        return vectorText;
+    }
+    // translates strings like [0.1, -0.5, 0.8] into the little-endian IEEE float sequence of bytes required by the VECTOR data type
+    return db.raw('VEC_FromText(?)', [vectorText]);
+}
+/**
+ * Validates a vector before serializing it for MariaDB.
+ */
+function validateVector(vector) {
+    for (let index = 0; index < vector.length; index += 1) {
+        const value = vector[index];
+        if (typeof value !== 'number' || !Number.isFinite(value)) {
+            throw new Error(`Vector value at index ${index} must be a finite number.`);
+        }
+    }
+    return vector;
+}
+export { vectorFromDbValue };

package/dist/db/dialects/mysql.d.ts

@@ -0,0 +1,14 @@
+import { Buffer } from 'node:buffer';
+import type { DatabaseDialect } from './types.js';
+/**
+ * MySQL dialect used by the framework database layer.
+ */
+export declare const mysqlDialect: DatabaseDialect;
+/**
+ * Encodes a numeric vector as little-endian float32 bytes.
+ */
+export declare function vectorToMysqlBuffer(vector: readonly number[]): Buffer;
+/**
+ * Decodes a vector from a binary value, text JSON, or already-decoded array.
+ */
+export declare function vectorFromDbValue(input: unknown): number[] | null;