@db3.ai/app 0.1.0-beta.1

package/dist/db/ActiveRecord.js

@@ -0,0 +1,765 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { isRecord, recordFromUnknown } from '@db3.ai/pure';
+import { databaseDialectForConnection } from './dialects/index.js';
+import { RecordValidationError, } from './FieldType.js';
+import { ActiveQueryBuilder } from './ActiveQueryBuilder.js';
+import { db as defaultDb } from './connection.js';
+import { resolveModelFields } from './fields/resolveFields.js';
+import { getAutomaticUpdateTimestampFieldNames, getSoftDeleteWriteData, modelUsesSoftDeletes, requireSoftDeleteField, } from './SoftDeletes.js';
+import { RecordNotFoundError } from './errors.js';
+import { activeAppDatabase } from '../server/appContext.js';
+export { RecordNotFoundError } from './errors.js';
+const scopedDb = new AsyncLocalStorage();
+/**
+ * Minimal ActiveRecord base class.
+ *
+ * Subclasses define their table and fields statically. Each instance creates
+ * private live field objects, and public model properties proxy through to those
+ * fields.
+ *
+ * Example:
+ *
+ * ```ts
+ * class User extends ActiveRecord {
+ *   static table = 'users';
+ *   static fields(field: FieldBuilder) {
+ *     return {
+ *       email: field.email({ required: true }),
+ *     };
+ *   }
+ * }
+ *
+ * const user = new User();
+ * user.email = 'STEVE@EXAMPLE.COM';
+ * console.log(user.email); // 'steve@example.com'
+ * ```
+ */
+export class ActiveRecord {
+    /** Database table name. Override in subclasses. */
+    static table;
+    /** Developer-facing model note for generated schemas and tooling. */
+    static comment = '';
+    /** Logical primary-key field name. Override if not `id`. */
+    static primaryKey = 'id';
+    /** Fields used to render row labels when this model is linked from another model. */
+    static labelFields = [];
+    /** Logical fields that request filling may assign. Undefined means all non-guarded fields. */
+    static requestFillable;
+    /** Logical fields that request filling may not assign. */
+    static requestGuarded = [];
+    /** Static field factory. Override in subclasses. */
+    static fields(_field) {
+        return {};
+    }
+    /**
+     * Defines an inferred model subclass using the existing field lifecycle.
+     *
+     * Inherited fields are included automatically. A matching name replaces the
+     * complete definition while retaining its application and input value types.
+     * Ordinary static field factories continue to control their own inheritance.
+     *
+     * @param definition - This layer's fields and optional model settings.
+     * @returns A subclass that can be extended with application methods.
+     * @example
+     * class User extends ActiveRecord.define({
+     * 	table: 'users',
+     * 	fields: field => ({ id: field.ulid(), email: field.email({ required: true }) }),
+     * }) {}
+     */
+    static define(definition) {
+        const Base = this;
+        const { fields, ...settings } = definition;
+        /** Model layer resolved and cloned by the ordinary ActiveRecord path. */
+        class DefinedRecord extends Base {
+            /** Resolves parent fields for the final subclass before applying overrides. */
+            static fields(field) {
+                return { ...Base.fields.call(this, field), ...fields.call(this, field) };
+            }
+        }
+        Object.assign(DefinedRecord, settings);
+        return DefinedRecord;
+    }
+    /** Optional model-level database connection. Falls back to the shared app connection. */
+    static db;
+    /**
+     * Whether to call `.returning('*')` after inserts/updates.
+     *
+     * This is usually desirable for PostgreSQL. Set to `false` for dialects where
+     * returning is unsupported or unwanted.
+     */
+    static returning = true;
+    /** Soft-delete setting. True uses the conventional `deletedAt` logical field. */
+    static softDeletes = false;
+    /** Per-record live fields, keyed by logical field name. */
+    $fields = {};
+    /** Whether the record currently represents an existing database row. */
+    $persisted = false;
+    /** Optional instance-level database connection/session. */
+    $db;
+    constructor(input = {}, options = {}) {
+        const Model = this.$model();
+        this.$db = options.db ?? Model.db;
+        this.$persisted = options.persisted ?? options.fromDb ?? false;
+        for (const [fieldName, field] of Object.entries(Model.getFields())) {
+            const liveField = field.clone().bindToRecord(this, fieldName);
+            this.$fields[fieldName] = liveField;
+            this.$installAccessor(fieldName);
+        }
+        if (options.fromDb) {
+            this.$hydrateFromDb(input);
+        }
+        else {
+            this.assign(input);
+        }
+    }
+    /**
+     * Binds a custom default database connection to the model class.
+     *
+     * Most models can use the active app connection automatically. For tests,
+     * prefer creating an app with the test database. For scoped work such as
+     * transactions, use `withDb()`.
+     */
+    static useDb(db) {
+        this.db = db;
+        return this;
+    }
+    /**
+     * Returns the database connection for the current ActiveRecord operation.
+     */
+    static getDb() {
+        return scopedDb.getStore()
+            ?? this.db
+            ?? activeAppDatabase()
+            ?? defaultDb();
+    }
+    /**
+     * Runs work with a temporary database connection for all ActiveRecord statics.
+     */
+    static withDb(db, callback) {
+        return scopedDb.run(db, callback);
+    }
+    /**
+     * Creates a new unsaved record bound to this model's current database.
+     *
+     * @param input - Constructor input, inferred from fields for defined models.
+     * @param options - Record hydration/persistence flags; the database is resolved here.
+     * @returns The actual subclass instance, synchronously. Call `save()` to write it.
+     */
+    static create(input = {}, options = {}) {
+        return new this(input, {
+            ...options,
+            db: ActiveRecord.getDb.call(this),
+        });
+    }
+    /**
+     * Resolves the model's static field factory with the framework field helper.
+     */
+    static getFields() {
+        return resolveModelFields(this);
+    }
+    /**
+     * Returns a DomForm render spec composed from this model's FieldTypes.
+     */
+    static getForm(options = {}) {
+        const children = Object.entries(this.getFields()).flatMap(([fieldName, field]) => {
+            if (!options.includeGenerated && field.config.generated)
+                return [];
+            return [
+                field.getFormComponentFor(this, fieldName, {
+                    mode: options.mode ?? 'create',
+                }),
+            ];
+        });
+        return {
+            component: 'DomForm',
+            props: {
+                name: options.name ?? this.table,
+            },
+            children,
+        };
+    }
+    /**
+     * Returns search filter render specs composed from this model's FieldTypes.
+     */
+    static getSearchFilters(options = {}) {
+        const filters = {};
+        for (const [fieldName, field] of Object.entries(this.getFields())) {
+            const component = field.getSearchFilterComponentFor(this, fieldName, {
+                mode: options.mode ?? 'search',
+            });
+            if (component) {
+                filters[fieldName] = component;
+            }
+        }
+        return filters;
+    }
+    /**
+     * Looks up one resolved field definition by logical field name.
+     */
+    static getField(fieldName) {
+        const field = this.getFields()[fieldName];
+        if (!field) {
+            throw new Error(`Unknown field "${fieldName}" on model ${this.name}`);
+        }
+        return field;
+    }
+    /**
+     * Starts a field-aware query for this model.
+     */
+    static query(db) {
+        const Model = this;
+        const connection = db ?? ActiveRecord.getDb.call(this);
+        return new ActiveQueryBuilder(Model, connection);
+    }
+    /**
+     * Starts a query that includes soft-deleted rows.
+     */
+    static withTrashed(db) {
+        return ActiveRecord.query.call(this, db).withTrashed();
+    }
+    /**
+     * Starts a query that only includes soft-deleted rows.
+     */
+    static onlyTrashed(db) {
+        return ActiveRecord.query.call(this, db).onlyTrashed();
+    }
+    /**
+     * Starts a query that excludes soft-deleted rows.
+     */
+    static withoutTrashed(db) {
+        return ActiveRecord.query.call(this, db).withoutTrashed();
+    }
+    static where(fieldNameOrCriteria, operatorOrValue, value) {
+        const query = ActiveRecord.query.call(this);
+        if (typeof fieldNameOrCriteria === 'object' && fieldNameOrCriteria !== null) {
+            return query.where(fieldNameOrCriteria);
+        }
+        return arguments.length === 3
+            ? query.where(fieldNameOrCriteria, String(operatorOrValue), value)
+            : query.where(fieldNameOrCriteria, operatorOrValue);
+    }
+    /**
+     * Finds one record by the configured primary key.
+     */
+    static async findByPk(id, db) {
+        const query = ActiveRecord.query.call(this, db);
+        return query.wherePk(id).first();
+    }
+    /**
+     * Finds one record by the configured primary key or field criteria.
+     */
+    static async find(lookup, db) {
+        return ActiveRecord.queryForLookup.call(this, lookup, db).first();
+    }
+    /**
+     * Finds one record by the configured primary key or field criteria.
+     *
+     * Throws a `RecordNotFoundError` if no matching row exists.
+     */
+    static async findOrFail(lookup, db) {
+        const record = await ActiveRecord.find.call(this, lookup, db);
+        if (!record) {
+            throw new RecordNotFoundError(this.name, lookup);
+        }
+        return record;
+    }
+    static queryForLookup(lookup, db) {
+        const query = ActiveRecord.query.call(this, db);
+        if (isLookupCriteria(lookup)) {
+            if (Object.keys(lookup).length === 0) {
+                throw new Error('At least one lookup field is required.');
+            }
+            return query.where(lookup);
+        }
+        return query.wherePk(lookup);
+    }
+    /**
+     * Hydrates a model instance from a raw database row.
+     */
+    static fromDb(row, db) {
+        return new this(row, {
+            db,
+            fromDb: true,
+            persisted: true,
+        });
+    }
+    /**
+     * Returns Laravel-style validation rules generated from this model's fields.
+     */
+    static validationRules(options = {}) {
+        const rules = {};
+        for (const [fieldName, field] of Object.entries(this.getFields())) {
+            if (!shouldIncludeFieldValidationRules(this, fieldName, field, options))
+                continue;
+            rules[fieldName] = field.getValidationRules({
+                model: this,
+                fieldName,
+            });
+        }
+        return rules;
+    }
+    /**
+     * Assigns app/input values by logical field name.
+     *
+     * Unknown keys are ignored. Use `set(fieldName, value)` if you want an error
+     * for unknown fields.
+     */
+    assign(input) {
+        for (const fieldName of Object.keys(this.$fields)) {
+            if (Object.prototype.hasOwnProperty.call(input, fieldName)) {
+                this.$set(fieldName, input[fieldName]);
+            }
+        }
+        return this;
+    }
+    /**
+     * Assigns request/form values using logical model field names.
+     */
+    assignFromRequest(input, options = {}) {
+        return this.setFromRequest(input, options);
+    }
+    /**
+     * Fills this record from request/form values using logical model field names.
+     *
+     * Unknown keys are ignored. Primary/generated/guarded fields are skipped by
+     * default, and model/request fillable config controls what may be assigned.
+     */
+    setFromRequest(input, options = {}) {
+        const requestInput = recordFromUnknown(input);
+        for (const [fieldName, field] of Object.entries(this.$fields)) {
+            if (!this.$canFillFromRequest(fieldName, field, options))
+                continue;
+            if (!Object.prototype.hasOwnProperty.call(requestInput, fieldName))
+                continue;
+            this.$set(fieldName, requestInput[fieldName]);
+        }
+        return this;
+    }
+    /**
+     * Fills this record from request/form values using a request-key to model-field map.
+     */
+    setFromRequestWithMap(input, dataToFieldMap, options = {}) {
+        const requestInput = recordFromUnknown(input);
+        const mappedInput = {
+            ...requestInput,
+        };
+        for (const [dataKey, fieldName] of Object.entries(dataToFieldMap)) {
+            if (Object.prototype.hasOwnProperty.call(requestInput, dataKey)) {
+                mappedInput[fieldName] = requestInput[dataKey];
+            }
+        }
+        return this.setFromRequest(mappedInput, options);
+    }
+    /**
+     * Dynamically sets a field by logical name.
+     *
+     * Useful for runtime/database-stored schemas where TypeScript cannot know the
+     * field names at compile time.
+     */
+    set(fieldName, value) {
+        this.$set(fieldName, value);
+        return this;
+    }
+    /**
+     * Dynamically gets a field by logical name.
+     */
+    get(fieldName) {
+        return this.$get(fieldName);
+    }
+    /**
+     * Dynamically binds this record instance to a database connection/session.
+     */
+    setDb(db) {
+        this.$db = db;
+        return this;
+    }
+    /**
+     * Returns true if the model has the given logical field.
+     */
+    hasField(fieldName) {
+        return Boolean(this.$fields[fieldName]);
+    }
+    /**
+     * Returns the bound runtime field for framework-level hydration helpers.
+     */
+    getBoundField(fieldName) {
+        return this.$field(fieldName);
+    }
+    /**
+     * Validates fields and stores field errors on each field state.
+     */
+    async validate(options = {}) {
+        for (const field of Object.values(this.$fields)) {
+            if (options.onlyDirty && !field.dirty) {
+                continue;
+            }
+            await field.validateField();
+        }
+        return !this.hasErrors();
+    }
+    /**
+     * Clears all current validation errors.
+     */
+    clearErrors() {
+        for (const field of Object.values(this.$fields)) {
+            field.clearErrors();
+        }
+    }
+    /**
+     * Returns true if any field currently has validation errors.
+     */
+    hasErrors() {
+        return this.getErrors().length > 0;
+    }
+    /**
+     * Returns all field errors on this record.
+     */
+    getErrors() {
+        const errors = [];
+        for (const field of Object.values(this.$fields)) {
+            errors.push(...field.errors);
+        }
+        return errors;
+    }
+    /**
+     * Returns current validation errors for one field.
+     */
+    getFieldErrors(fieldName) {
+        return this.$field(fieldName).errors;
+    }
+    /**
+     * Returns database insert/update data for the record.
+     *
+     * This calls every field's `getDataForDb()` method. This is where passwords
+     * are hashed, JSON fields are stringified, link fields produce foreign keys,
+     * and compound fields can return multiple columns.
+     */
+    async getDataForDb(options = {}) {
+        const writeOptions = {
+            isInsert: options.isInsert ?? !this.$persisted,
+            onlyDirty: options.onlyDirty ?? false,
+            valueOptions: options.valueOptions,
+        };
+        const row = {};
+        for (const field of Object.values(this.$fields)) {
+            const fieldData = await field.getBoundDataForDb(writeOptions);
+            Object.assign(row, fieldData);
+        }
+        return row;
+    }
+    /**
+     * Inserts or updates this record.
+     *
+     * Validation runs before any SQL is executed. On validation failure this throws
+     * `RecordValidationError` containing all field errors.
+     */
+    async save() {
+        const Model = this.$model();
+        const connection = this.$db ?? Model.getDb();
+        const isInsert = !this.$persisted;
+        const valid = await this.validate({ onlyDirty: false });
+        if (!valid) {
+            throw new RecordValidationError(this.getErrors());
+        }
+        const row = await this.getDataForDb({
+            isInsert,
+            onlyDirty: !isInsert,
+            valueOptions: {
+                db: connection,
+                dialect: databaseDialectForConnection(connection),
+            },
+        });
+        if (isInsert) {
+            const query = connection(Model.table).insert(row);
+            const result = shouldUseReturningRows(Model, connection)
+                ? await query.returning('*')
+                : await query;
+            const createdRow = Array.isArray(result) ? result[0] : undefined;
+            if (createdRow && typeof createdRow === 'object') {
+                this.$hydrateFromDb(createdRow);
+            }
+            this.$persisted = true;
+            this.$markClean();
+            return this;
+        }
+        if (Object.keys(row).length === 0) {
+            return this;
+        }
+        const query = connection(Model.table)
+            .where(this.$primaryKeyWhere())
+            .update(row);
+        const result = shouldUseReturningRows(Model, connection)
+            ? await query.returning('*')
+            : await query;
+        const updatedRow = Array.isArray(result) ? result[0] : undefined;
+        if (updatedRow && typeof updatedRow === 'object') {
+            this.$hydrateFromDb(updatedRow);
+        }
+        this.$markClean();
+        return this;
+    }
+    /**
+     * Deletes the current database row.
+     *
+     * Models with `softDeletes` enabled update their delete timestamp instead of
+     * physically removing the row.
+     */
+    async delete(db) {
+        if (modelUsesSoftDeletes(this.$model())) {
+            return this.softDelete(db);
+        }
+        return this.forceDelete(db);
+    }
+    /**
+     * Physically deletes the current database row.
+     */
+    async forceDelete(db) {
+        const Model = this.$model();
+        const connection = db ?? this.$db ?? Model.getDb();
+        const count = await connection(Model.table)
+            .where(this.$primaryKeyWhere())
+            .delete();
+        this.$persisted = false;
+        return Number(count);
+    }
+    /**
+     * Restores the current soft-deleted database row.
+     */
+    async restore(db) {
+        const Model = this.$model();
+        const connection = db ?? this.$db ?? Model.getDb();
+        const softDeleteField = requireSoftDeleteField(Model);
+        const updatedAt = new Date();
+        const count = await connection(Model.table)
+            .where(this.$primaryKeyWhere())
+            .whereNotNull(softDeleteField.column)
+            .update(getSoftDeleteWriteData(Model, null, updatedAt));
+        const restoredCount = Number(count);
+        if (restoredCount > 0) {
+            this.$setSoftDeleteFieldValues(null, updatedAt);
+            this.$persisted = true;
+            this.$markClean();
+        }
+        return restoredCount;
+    }
+    /**
+     * Returns true when this soft-deletable record has been trashed.
+     */
+    trashed() {
+        const softDeleteField = requireSoftDeleteField(this.$model());
+        const value = this.$get(softDeleteField.fieldName);
+        return value !== null && value !== undefined;
+    }
+    /**
+     * Returns hydrated backend values keyed by logical field name.
+     */
+    toAppData() {
+        const data = {};
+        for (const [fieldName, field] of Object.entries(this.$fields)) {
+            if (field.config.hidden)
+                continue;
+            data[fieldName] = field.value;
+        }
+        return data;
+    }
+    /**
+     * Serialises this record using each field's display value.
+     */
+    toDisplayData() {
+        const data = {};
+        for (const [fieldName, field] of Object.entries(this.$fields)) {
+            const value = field.getBoundDisplayValue();
+            if (value !== undefined) {
+                data[fieldName] = value;
+            }
+        }
+        return data;
+    }
+    /**
+     * JSON transport alias for display data.
+     */
+    toJSON() {
+        return this.toDisplayData();
+    }
+    /**
+     * Returns true if this record was loaded from or saved to the database.
+     */
+    isPersisted() {
+        return this.$persisted;
+    }
+    /**
+     * Returns whether one field or any field has unsaved in-memory changes.
+     *
+     * @param fieldName - Optional logical field name to inspect.
+     * @returns True when the selected field scope contains unsaved changes.
+     */
+    isDirty(fieldName) {
+        if (fieldName !== undefined) {
+            return this.$field(fieldName).dirty;
+        }
+        return Object.values(this.$fields).some(field => field.dirty);
+    }
+    /**
+     * Protected field getter used by generated accessors and `get()`.
+     */
+    $get(fieldName) {
+        return this.$field(fieldName).value;
+    }
+    /**
+     * Protected field setter used by generated accessors and `set()`.
+     */
+    $set(fieldName, value) {
+        this.$field(fieldName).value = value;
+    }
+    /**
+     * Hydrates all fields from a raw database row.
+     */
+    $hydrateFromDb(row) {
+        for (const field of Object.values(this.$fields)) {
+            field.hydrate(row);
+        }
+        this.$persisted = true;
+    }
+    /**
+     * Marks all fields as clean after a successful save/hydration.
+     */
+    $markClean() {
+        for (const field of Object.values(this.$fields)) {
+            field.markBoundClean();
+        }
+    }
+    /**
+     * Returns a database where-clause object for the primary key.
+     */
+    $primaryKeyWhere() {
+        const Model = this.$model();
+        const pkName = Model.primaryKey;
+        const pkField = this.$field(pkName);
+        const pkValue = this.$get(pkName);
+        return {
+            [pkField.column]: pkField.getBoundQueryValue(pkValue),
+        };
+    }
+    /**
+     * Returns one of this record's live field objects.
+     */
+    $field(fieldName) {
+        const field = this.$fields[fieldName];
+        if (!field) {
+            throw new Error(`Unknown field "${fieldName}"`);
+        }
+        return field;
+    }
+    /**
+     * Soft deletes the current database row.
+     */
+    async softDelete(db) {
+        const Model = this.$model();
+        const connection = db ?? this.$db ?? Model.getDb();
+        const deletedAt = new Date();
+        const count = await connection(Model.table)
+            .where(this.$primaryKeyWhere())
+            .update(getSoftDeleteWriteData(Model, deletedAt, deletedAt));
+        const deletedCount = Number(count);
+        if (deletedCount > 0) {
+            this.$setSoftDeleteFieldValues(deletedAt, deletedAt);
+            this.$markClean();
+        }
+        return deletedCount;
+    }
+    /**
+     * Mirrors soft-delete timestamp writes into this record's live field state.
+     */
+    $setSoftDeleteFieldValues(deletedAt, updatedAt) {
+        const Model = this.$model();
+        const softDeleteField = requireSoftDeleteField(Model);
+        const ignoredFieldNames = new Set([softDeleteField.fieldName]);
+        this.$set(softDeleteField.fieldName, deletedAt);
+        for (const fieldName of getAutomaticUpdateTimestampFieldNames(Model, ignoredFieldNames)) {
+            this.$set(fieldName, updatedAt);
+        }
+    }
+    /**
+     * Returns the static model class for this instance.
+     */
+    $model() {
+        return this.constructor;
+    }
+    $canFillFromRequest(fieldName, field, options) {
+        if (!options.includePrimary && field.config.primary)
+            return false;
+        if (!options.includeGenerated && field.config.generated)
+            return false;
+        const Model = this.$model();
+        const fillable = options.fillable ?? Model.requestFillable;
+        const guarded = options.guarded ?? Model.requestGuarded ?? [];
+        if (fillable && !fillable.includes(fieldName))
+            return false;
+        if (guarded.includes(fieldName))
+            return false;
+        return true;
+    }
+    /**
+     * Defines an instance getter/setter for a configured field.
+     */
+    $installAccessor(fieldName) {
+        if (Object.prototype.hasOwnProperty.call(this, fieldName)
+            || this.$hasModelAccessor(fieldName)) {
+            return;
+        }
+        Object.defineProperty(this, fieldName, {
+            enumerable: true,
+            configurable: true,
+            get: () => this.$get(fieldName),
+            set: value => {
+                this.$set(fieldName, value);
+            },
+        });
+    }
+    /**
+     * Checks whether a model class owns a custom accessor for a field.
+     *
+     * Explicit model accessors may wrap the underlying field through `$get`
+     * and `$set` when a domain value needs a stable model-owned interface.
+     *
+     * @param fieldName - Logical field name being installed.
+     * @returns True when a subclass prototype defines a getter or setter.
+     */
+    $hasModelAccessor(fieldName) {
+        let prototype = Object.getPrototypeOf(this);
+        while (prototype && prototype !== ActiveRecord.prototype) {
+            const descriptor = Object.getOwnPropertyDescriptor(prototype, fieldName);
+            if (descriptor?.get || descriptor?.set)
+                return true;
+            prototype = Object.getPrototypeOf(prototype);
+        }
+        return false;
+    }
+}
+function shouldUseReturningRows(Model, connection) {
+    if (Model.returning === false)
+        return false;
+    return supportsReturningRows(connection);
+}
+function supportsReturningRows(connection) {
+    return databaseDialectForConnection(connection).supportsReturningRows;
+}
+function shouldIncludeFieldValidationRules(Model, fieldName, field, options) {
+    if (!options.includeHidden && field.config.hidden)
+        return false;
+    if (!options.includePrimary && field.config.primary)
+        return false;
+    if (!options.includeGenerated && field.config.generated)
+        return false;
+    const fillable = options.fillable ?? Model.requestFillable;
+    const guarded = options.guarded ?? Model.requestGuarded ?? [];
+    if (fillable && !fillable.includes(fieldName))
+        return false;
+    if (guarded.includes(fieldName))
+        return false;
+    return true;
+}
+function isLookupCriteria(input) {
+    return isRecord(input)
+        && !(input instanceof Date);
+}