@db3.ai/app 0.1.0-beta.1

package/dist/db/dialects/mysql.js

@@ -0,0 +1,203 @@
+import { Buffer } from 'node:buffer';
+import { mysqlColumnTypes } from './columnTypes.js';
+const VECTOR_BYTES_PER_ENTRY = 4;
+const VECTOR_MAX_DIMENSIONS = 16383;
+/**
+ * MySQL dialect used by the framework database layer.
+ */
+export const mysqlDialect = {
+    name: 'mysql',
+    knexClient: 'mysql2',
+    defaultPort: 3306,
+    supportsReturningRows: false,
+    supportsTableComments: true,
+    supportsVectorIndexes: false,
+    vectorMaxDimensions: VECTOR_MAX_DIMENSIONS,
+    columnTypes: mysqlColumnTypes,
+    vectorColumnType,
+    vectorToDbValue: vectorToMysqlBuffer,
+    vectorFromDbValue,
+    createDatabase: createMysqlDatabase,
+    dropDatabase: dropMysqlDatabase,
+    quoteIdentifier: quoteMysqlIdentifier,
+    getTableIndexes: getMysqlTableIndexes,
+    getTableComments: getMysqlTableComments,
+};
+/**
+ * Returns the native MySQL VECTOR column type for configured dimensions.
+ */
+function vectorColumnType(dimensions) {
+    return dimensions === undefined ? 'vector' : `vector(${dimensions})`;
+}
+/**
+ * Creates a UTF-8 MySQL database for isolated integration tests.
+ */
+async function createMysqlDatabase(db, databaseName) {
+    await db.raw(`CREATE DATABASE ${quoteMysqlIdentifier(databaseName)} CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci`);
+}
+/**
+ * Drops an isolated MySQL integration-test database.
+ */
+async function dropMysqlDatabase(db, databaseName) {
+    await db.raw(`DROP DATABASE IF EXISTS ${quoteMysqlIdentifier(databaseName)}`);
+}
+/**
+ * Quotes a MySQL identifier after the caller has validated its shape.
+ */
+function quoteMysqlIdentifier(identifier) {
+    return `\`${identifier.replace(/`/g, '``')}\``;
+}
+/**
+ * Reads MySQL or MariaDB index metadata and normalizes it for schema diffing.
+ */
+async function getMysqlTableIndexes(db, tableName) {
+    const result = await db.raw('SHOW INDEX FROM ??', [tableName]);
+    const rows = extractMysqlRows(result);
+    const indexes = new Map();
+    for (const row of rows) {
+        const name = stringValue(row.Key_name);
+        const column = stringValue(row.Column_name);
+        if (!name || !column)
+            continue;
+        const index = indexes.get(name) ?? {
+            name,
+            columns: [],
+            unique: Number(row.Non_unique ?? 1) === 0,
+            primary: name === 'PRIMARY',
+            type: indexType(row.Index_type),
+        };
+        index.columns.push({
+            name: column,
+            order: indexColumnOrder(row.Collation),
+        });
+        indexes.set(name, index);
+    }
+    return [...indexes.values()].map(index => {
+        return {
+            ...index,
+            columns: index.columns.sort((a, b) => {
+                const aRow = rows.find(row => {
+                    return stringValue(row.Key_name) === index.name
+                        && stringValue(row.Column_name) === a.name;
+                });
+                const bRow = rows.find(row => {
+                    return stringValue(row.Key_name) === index.name
+                        && stringValue(row.Column_name) === b.name;
+                });
+                return Number(aRow?.Seq_in_index ?? 0) - Number(bRow?.Seq_in_index ?? 0);
+            }),
+        };
+    });
+}
+/**
+ * Reads MySQL or MariaDB table comments in one metadata query.
+ *
+ * @param db - Database connection used for metadata inspection.
+ * @param tableNames - Existing table names whose comments are required.
+ * @returns Existing comments keyed by table name.
+ */
+async function getMysqlTableComments(db, tableNames) {
+    if (tableNames.length === 0) {
+        return new Map();
+    }
+    const rows = await db('information_schema.TABLES')
+        .select({
+        tableName: 'TABLE_NAME',
+        comment: 'TABLE_COMMENT',
+    })
+        .whereRaw('TABLE_SCHEMA = DATABASE()')
+        .whereIn('TABLE_NAME', tableNames);
+    return new Map(rows.flatMap(row => {
+        const tableName = stringValue(row.tableName);
+        if (!tableName)
+            return [];
+        return [[
+                tableName,
+                stringValue(row.comment),
+            ]];
+    }));
+}
+/**
+ * Converts database index-type metadata into a framework index kind.
+ *
+ * @param input - Raw index type from `SHOW INDEX`.
+ * @returns Framework index type.
+ */
+function indexType(input) {
+    const value = String(input ?? '').trim().toLowerCase();
+    return value === 'vector' ? 'vector' : 'normal';
+}
+/**
+ * Encodes a numeric vector as little-endian float32 bytes.
+ */
+export function vectorToMysqlBuffer(vector) {
+    const buffer = Buffer.allocUnsafe(vector.length * VECTOR_BYTES_PER_ENTRY);
+    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.`);
+        }
+        buffer.writeFloatLE(value, index * VECTOR_BYTES_PER_ENTRY);
+    }
+    return buffer;
+}
+/**
+ * Decodes a vector from a binary value, text JSON, or already-decoded array.
+ */
+export function vectorFromDbValue(input) {
+    if (input === null || input === undefined || input === '') {
+        return null;
+    }
+    if (input instanceof Uint8Array) {
+        return vectorFromMysqlBuffer(input);
+    }
+    if (typeof input === 'string') {
+        const value = input.trim();
+        if (!value)
+            return null;
+        return JSON.parse(value);
+    }
+    return input;
+}
+/**
+ * Decodes little-endian float32 vector bytes into app-memory numbers.
+ */
+function vectorFromMysqlBuffer(input) {
+    const buffer = Buffer.isBuffer(input) ? input : Buffer.from(input);
+    if (buffer.length % VECTOR_BYTES_PER_ENTRY !== 0) {
+        throw new Error('VECTOR binary data length must be divisible by 4.');
+    }
+    const vector = [];
+    for (let offset = 0; offset < buffer.length; offset += VECTOR_BYTES_PER_ENTRY) {
+        vector.push(buffer.readFloatLE(offset));
+    }
+    return vector;
+}
+/**
+ * Extracts row arrays from mysql2 raw result tuples.
+ */
+function extractMysqlRows(result) {
+    if (!Array.isArray(result))
+        return [];
+    const [rows] = result;
+    return Array.isArray(rows) ? rows : [];
+}
+/**
+ * Returns a non-empty string value from database metadata.
+ */
+function stringValue(input) {
+    return typeof input === 'string' && input !== '' ? input : null;
+}
+/**
+ * Converts MySQL index collation metadata into an order direction.
+ */
+function indexColumnOrder(input) {
+    if (typeof input !== 'string')
+        return undefined;
+    const value = input.trim().toUpperCase();
+    if (value === 'A')
+        return 'asc';
+    if (value === 'D')
+        return 'desc';
+    return undefined;
+}

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

@@ -0,0 +1,5 @@
+import type { DatabaseDialect } from './types.js';
+/**
+ * PostgreSQL dialect placeholder for pg/pgvector-backed applications.
+ */
+export declare const postgresDialect: DatabaseDialect;

package/dist/db/dialects/postgres.js

@@ -0,0 +1,106 @@
+import { postgresColumnTypes } from './columnTypes.js';
+import { vectorFromDbValue } from './mysql.js';
+const VECTOR_MAX_DIMENSIONS = 16000;
+/**
+ * PostgreSQL dialect placeholder for pg/pgvector-backed applications.
+ */
+export const postgresDialect = {
+    name: 'postgres',
+    knexClient: 'pg',
+    defaultPort: 5432,
+    supportsReturningRows: true,
+    supportsTableComments: false,
+    supportsVectorIndexes: false,
+    vectorMaxDimensions: VECTOR_MAX_DIMENSIONS,
+    columnTypes: postgresColumnTypes,
+    vectorColumnType,
+    vectorToDbValue,
+    vectorFromDbValue,
+    createDatabase,
+    dropDatabase,
+    quoteIdentifier,
+    getTableIndexes,
+    getTableComments,
+};
+/**
+ * Returns the pgvector column type for configured dimensions.
+ */
+function vectorColumnType(dimensions) {
+    return dimensions === undefined ? 'vector' : `vector(${dimensions})`;
+}
+/**
+ * Converts app-memory vectors into pgvector text input.
+ */
+function vectorToDbValue(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 JSON.stringify(vector);
+}
+/**
+ * Creates a PostgreSQL database for isolated integration tests.
+ */
+async function createDatabase(db, databaseName) {
+    await db.raw(`CREATE DATABASE ${quoteIdentifier(databaseName)}`);
+}
+/**
+ * Drops an isolated PostgreSQL integration-test database.
+ */
+async function dropDatabase(db, databaseName) {
+    await db.raw(`DROP DATABASE IF EXISTS ${quoteIdentifier(databaseName)}`);
+}
+/**
+ * Quotes a PostgreSQL identifier after the caller has validated its shape.
+ */
+function quoteIdentifier(identifier) {
+    return `"${identifier.replace(/"/g, '""')}"`;
+}
+/**
+ * Returns no table comments because PostgreSQL comment sync is not enabled.
+ *
+ * @param _db - Unused database connection.
+ * @param _tableNames - Unused table names.
+ * @returns Empty comment map.
+ */
+async function getTableComments(_db, _tableNames) {
+    return new Map();
+}
+/**
+ * Reads PostgreSQL index metadata and normalizes it for schema diffing.
+ */
+async function getTableIndexes(db, tableName) {
+    const rows = await db
+        .select([
+        db.raw('i.relname AS index_name'),
+        db.raw('a.attname AS column_name'),
+        db.raw('array_position(ix.indkey, a.attnum) AS column_order'),
+        db.raw('ix.indisunique AS is_unique'),
+        db.raw('ix.indisprimary AS is_primary'),
+    ])
+        .from({ t: 'pg_class' })
+        .join({ n: 'pg_namespace' }, 'n.oid', 't.relnamespace')
+        .join({ ix: 'pg_index' }, 'ix.indrelid', 't.oid')
+        .join({ i: 'pg_class' }, 'i.oid', 'ix.indexrelid')
+        .joinRaw('JOIN pg_attribute AS a ON a.attrelid = t.oid AND a.attnum = ANY(ix.indkey)')
+        .where('t.relname', tableName)
+        .where('n.nspname', 'public')
+        .orderBy('i.relname')
+        .orderBy('column_order');
+    const indexes = new Map();
+    for (const row of rows) {
+        const index = indexes.get(row.index_name) ?? {
+            name: row.index_name,
+            columns: [],
+            unique: Boolean(row.is_unique),
+            primary: Boolean(row.is_primary),
+        };
+        index.columns.push({
+            name: row.column_name,
+        });
+        indexes.set(row.index_name, index);
+    }
+    return [...indexes.values()];
+}

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

@@ -0,0 +1,14 @@
+import type { Knex } from 'knex';
+import type { DatabaseDialect } from './types.js';
+/**
+ * Resolves a configured database connection name to a framework dialect.
+ */
+export declare function resolveDatabaseDialect(connectionName?: string): DatabaseDialect;
+/**
+ * Associates a Knex connection with the framework dialect that created it.
+ */
+export declare function rememberDatabaseDialect(connection: Knex, dialect: DatabaseDialect): void;
+/**
+ * Resolves the best-known dialect for an existing Knex connection.
+ */
+export declare function databaseDialectForConnection(connection: Knex): DatabaseDialect;

package/dist/db/dialects/resolveDialect.js

@@ -0,0 +1,57 @@
+import { mariaDbDialect } from './mariadb.js';
+import { mysqlDialect } from './mysql.js';
+import { postgresDialect } from './postgres.js';
+const dialectByConnectionName = {
+    mysql: mysqlDialect,
+    mysql2: mysqlDialect,
+    mariadb: mariaDbDialect,
+    postgres: postgresDialect,
+    pgsql: postgresDialect,
+    pg: postgresDialect,
+};
+const dialectByConnection = new WeakMap();
+/**
+ * Resolves a configured database connection name to a framework dialect.
+ */
+export function resolveDatabaseDialect(connectionName = process.env.DB_CONNECTION || 'mysql2') {
+    const normalized = connectionName.trim().toLowerCase();
+    const dialect = dialectByConnectionName[normalized];
+    if (!dialect) {
+        throw new Error(`Unsupported DB_CONNECTION "${connectionName}". Use mysql, mysql2, mariadb, postgres, or pg.`);
+    }
+    return dialect;
+}
+/**
+ * Associates a Knex connection with the framework dialect that created it.
+ */
+export function rememberDatabaseDialect(connection, dialect) {
+    dialectByConnection.set(connection, dialect);
+}
+/**
+ * Resolves the best-known dialect for an existing Knex connection.
+ */
+export function databaseDialectForConnection(connection) {
+    const remembered = dialectByConnection.get(connection);
+    if (remembered)
+        return remembered;
+    const configured = resolveDatabaseDialect();
+    const clientName = databaseClientName(connection);
+    if (clientName === configured.knexClient) {
+        return configured;
+    }
+    if (clientName === 'mysql' || clientName === 'mysql2') {
+        return mysqlDialect;
+    }
+    if (clientName === 'pg' || clientName === 'postgres') {
+        return postgresDialect;
+    }
+    return configured;
+}
+/**
+ * Extracts Knex's low-level client name from a connection.
+ */
+function databaseClientName(connection) {
+    const client = connection.client;
+    const name = client.config?.client ?? client.dialect ?? '';
+    return String(name).toLowerCase();
+}

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

@@ -0,0 +1,44 @@
+import type { Knex } from 'knex';
+import type { DatabaseColumnTypes } from './columnTypes.js';
+export type DatabaseDialectName = 'mysql' | 'mariadb' | 'postgres';
+export type DatabaseConnectionName = 'mysql' | 'mysql2' | 'mariadb' | 'postgres' | 'pgsql' | 'pg';
+export interface NormalizedIndexColumn {
+    name: string;
+    order?: 'asc' | 'desc';
+}
+export interface TableIndexSpec {
+    name: string;
+    columns: NormalizedIndexColumn[];
+    unique: boolean;
+    primary: boolean;
+    type?: 'normal' | 'vector';
+}
+export interface DatabaseDialect {
+    name: DatabaseDialectName;
+    knexClient: string;
+    defaultPort: number;
+    supportsReturningRows: boolean;
+    supportsTableComments: boolean;
+    supportsVectorIndexes: boolean;
+    vectorMaxDimensions: number;
+    columnTypes: DatabaseColumnTypes;
+    vectorColumnType(dimensions?: number): string;
+    vectorToDbValue(vector: readonly number[], db?: Knex): unknown;
+    vectorFromDbValue(input: unknown): number[] | null;
+    createDatabase(db: Knex, databaseName: string): Promise<void>;
+    dropDatabase(db: Knex, databaseName: string): Promise<void>;
+    quoteIdentifier(identifier: string): string;
+    getTableIndexes(db: Knex, tableName: string): Promise<TableIndexSpec[]>;
+    /**
+     * Reads comments for the requested existing tables.
+     *
+     * @param db - Database connection used for metadata inspection.
+     * @param tableNames - Model table names whose comments are required.
+     * @returns Existing comments keyed by table name.
+     */
+    getTableComments(db: Knex, tableNames: string[]): Promise<Map<string, string | null>>;
+}
+export interface DatabaseValueOptions {
+    db?: Knex;
+    dialect?: DatabaseDialect;
+}

package/dist/db/dialects/types.js

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

package/dist/db/errors.d.ts

@@ -0,0 +1,15 @@
+export type ActiveRecordLookup = unknown | Record<string, unknown>;
+/**
+ * Error thrown when an ActiveRecord lookup cannot find a matching row.
+ */
+export declare class RecordNotFoundError extends Error {
+    readonly modelName: string;
+    readonly lookup?: ActiveRecordLookup | undefined;
+    /**
+     * Creates a not-found error for a model lookup.
+     *
+     * @param modelName - Name of the model that was queried.
+     * @param lookup - Lookup value or criteria used by the query.
+     */
+    constructor(modelName: string, lookup?: ActiveRecordLookup | undefined);
+}

package/dist/db/errors.js

@@ -0,0 +1,20 @@
+import { displayNameFromIdentifier } from '@db3.ai/pure';
+/**
+ * Error thrown when an ActiveRecord lookup cannot find a matching row.
+ */
+export class RecordNotFoundError extends Error {
+    modelName;
+    lookup;
+    /**
+     * Creates a not-found error for a model lookup.
+     *
+     * @param modelName - Name of the model that was queried.
+     * @param lookup - Lookup value or criteria used by the query.
+     */
+    constructor(modelName, lookup) {
+        super(`The requested ${displayNameFromIdentifier(modelName)} could not be found.`);
+        this.modelName = modelName;
+        this.lookup = lookup;
+        this.name = 'RecordNotFoundError';
+    }
+}

package/dist/db/fields/BooleanField.d.ts

@@ -0,0 +1,29 @@
+import { BasicFieldState, DbSchemaPart, FieldConfig, FieldContext, FieldType } from '../FieldType.js';
+import type { ValidationRule } from '../../validation/index.js';
+/**
+ * Configuration for boolean fields.
+ */
+export interface BooleanFieldConfig extends FieldConfig {
+}
+/**
+ * Boolean field with light coercion for common form values.
+ */
+export declare class BooleanField extends FieldType<boolean | null, boolean | number | string | null, boolean | null, unknown, BasicFieldState<boolean | null>> {
+    readonly config: BooleanFieldConfig;
+    constructor(config?: BooleanFieldConfig);
+    /**
+     * Parses booleans from booleans, numbers, and common strings.
+     */
+    protected parse(input: unknown): boolean | null;
+    /**
+     * Normalises database driver boolean values such as MySQL's 1/0 integers.
+     */
+    protected fromDbValue(input: unknown): boolean | null;
+    protected defaultFormComponent(): string;
+    protected defaultSearchFilterComponent(): string | null;
+    getValidationRules(ctx?: FieldContext): ValidationRule[];
+    /**
+     * Describes the boolean database column.
+     */
+    getDbSchema(ctx?: FieldContext): DbSchemaPart;
+}

package/dist/db/fields/BooleanField.js

@@ -0,0 +1,89 @@
+import { FieldType, fieldSchemaIndexes, } from '../FieldType.js';
+/**
+ * Boolean field with light coercion for common form values.
+ */
+export class BooleanField extends FieldType {
+    config;
+    constructor(config = {}) {
+        super(config);
+        this.config = config;
+    }
+    /**
+     * Parses booleans from booleans, numbers, and common strings.
+     */
+    parse(input) {
+        if (input === null || input === undefined || input === '') {
+            return null;
+        }
+        if (typeof input === 'boolean') {
+            return input;
+        }
+        if (typeof input === 'number') {
+            return input !== 0;
+        }
+        const value = String(input).toLowerCase().trim();
+        if (['true', '1', 'yes', 'on'].includes(value)) {
+            return true;
+        }
+        if (['false', '0', 'no', 'off'].includes(value)) {
+            return false;
+        }
+        return null;
+    }
+    /**
+     * Normalises database driver boolean values such as MySQL's 1/0 integers.
+     */
+    fromDbValue(input) {
+        return this.parse(input);
+    }
+    defaultFormComponent() {
+        return 'DomToggle';
+    }
+    defaultSearchFilterComponent() {
+        return 'DomToggle';
+    }
+    getValidationRules(ctx) {
+        return [
+            ...super.getValidationRules(ctx),
+            'boolean',
+        ];
+    }
+    /**
+     * Describes the boolean database column.
+     */
+    getDbSchema(ctx) {
+        return this.withContext(ctx, () => {
+            const dialect = this.schemaDialect();
+            const types = dialect.columnTypes;
+            return this.completeDbSchema({
+                columns: [
+                    {
+                        name: this.column,
+                        type: types.boolean(),
+                        nullable: !this.config.required && !this.config.primary,
+                        primary: this.config.primary,
+                        unique: this.config.unique,
+                        default: booleanDatabaseDefault(this.getDbDefaultValue(), dialect),
+                    },
+                ],
+                indexes: fieldSchemaIndexes(this.column, this.config),
+            }, ctx);
+        });
+    }
+}
+/**
+ * Converts logical boolean defaults into values accepted by each SQL dialect.
+ *
+ * MySQL and MariaDB expose booleans as numeric columns and reject a quoted
+ * `true` or `false` emitted by Knex for `specificType()` columns. Postgres owns
+ * a native boolean type and retains the logical value.
+ *
+ * @param value - Static field default produced by the base field lifecycle.
+ * @param dialect - Database dialect that will create or migrate the column.
+ * @returns Dialect-safe schema default.
+ */
+function booleanDatabaseDefault(value, dialect) {
+    if (typeof value !== 'boolean')
+        return value;
+    return dialect.name === 'postgres' ? value : Number(value);
+}

package/dist/db/fields/CharUuidField.d.ts

@@ -0,0 +1,29 @@
+import { BasicFieldState, DbSchemaPart, FieldContext, FieldError } from '../FieldType.js';
+import type { ValidationRule } from '../../validation/index.js';
+import { StringField, StringFieldConfig } from './StringField.js';
+/**
+ * Configuration for textual UUID fields stored as `char(36)` by default.
+ */
+export interface CharUuidFieldConfig extends StringFieldConfig {
+    /** Character length. Defaults to 36. */
+    length?: number;
+}
+/**
+ * UUID-like string field stored as `char(36)`.
+ *
+ * This fits schemas that store UUIDs as text rather than using the native
+ * PostgreSQL `uuid` type.
+ */
+export declare class CharUuidField extends StringField {
+    readonly config: CharUuidFieldConfig;
+    constructor(config?: CharUuidFieldConfig);
+    getValidationRules(ctx?: FieldContext): ValidationRule[];
+    /**
+     * Adds simple UUID-format validation when a value is present.
+     */
+    protected collectErrors(state: BasicFieldState<string | null>): Promise<FieldError[]>;
+    /**
+     * Describes a `char(36)` database column.
+     */
+    getDbSchema(ctx?: FieldContext): DbSchemaPart;
+}

package/dist/db/fields/CharUuidField.js

@@ -0,0 +1,63 @@
+import { fieldSchemaIndexes, } from '../FieldType.js';
+import { StringField } from './StringField.js';
+/**
+ * UUID-like string field stored as `char(36)`.
+ *
+ * This fits schemas that store UUIDs as text rather than using the native
+ * PostgreSQL `uuid` type.
+ */
+export class CharUuidField extends StringField {
+    constructor(config = {}) {
+        super({
+            length: 36,
+            maxLength: 36,
+            trim: true,
+            ...config,
+        });
+    }
+    getValidationRules(ctx) {
+        return [
+            ...super.getValidationRules(ctx),
+            'uuid',
+        ];
+    }
+    /**
+     * Adds simple UUID-format validation when a value is present.
+     */
+    async collectErrors(state) {
+        const errors = await super.collectErrors(state);
+        const value = state.value;
+        if (value &&
+            !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value)) {
+            errors.push({
+                field: this.fieldName,
+                message: `${this.fieldName} must be a valid UUID`,
+                code: 'uuid',
+                value,
+            });
+        }
+        return errors;
+    }
+    /**
+     * Describes a `char(36)` database column.
+     */
+    getDbSchema(ctx) {
+        return this.withContext(ctx, () => {
+            const length = this.config.length ?? 36;
+            const types = this.schemaDialect().columnTypes;
+            return this.completeDbSchema({
+                columns: [
+                    {
+                        name: this.column,
+                        type: types.char(length),
+                        nullable: !this.config.required && !this.config.primary,
+                        primary: this.config.primary,
+                        unique: this.config.unique,
+                        default: this.getDbDefaultValue(),
+                    },
+                ],
+                indexes: fieldSchemaIndexes(this.column, this.config),
+            }, ctx);
+        });
+    }
+}