@db3.ai/app 0.1.0-beta.1

package/dist/db/FieldType.js

@@ -0,0 +1,706 @@
+import { isFinallyPromise, normalizeDatabaseComment, startCase, } from '@db3.ai/pure';
+import { isDeepStrictEqual } from 'node:util';
+import { resolveDatabaseDialect } from './dialects/index.js';
+/**
+ * Error thrown by `ActiveRecord.save()` when one or more fields are invalid.
+ */
+export class RecordValidationError extends Error {
+    errors;
+    constructor(errors) {
+        super('Record validation failed');
+        this.errors = errors;
+        this.name = 'RecordValidationError';
+    }
+}
+/**
+ * Captures a clean comparison snapshot for mutable field values.
+ *
+ * Ordinary JSON objects, arrays, dates, maps, and sets are cloned so in-place
+ * mutations remain visible to dirty tracking. Values that cannot be cloned
+ * without changing their initial semantics retain their existing identity and
+ * continue to rely on explicit assignment.
+ *
+ * @param value - Current field value to retain as the clean baseline.
+ * @returns Independent comparison snapshot when the value supports it.
+ */
+function snapshotFieldValue(value) {
+    if (typeof value !== 'object' || value === null) {
+        return value;
+    }
+    try {
+        const snapshot = structuredClone(value);
+        return isDeepStrictEqual(value, snapshot)
+            ? snapshot
+            : value;
+    }
+    catch {
+        return value;
+    }
+}
+/**
+ * Writes a column spec onto a Knex table builder.
+ */
+export function writeDbColumn(table, column, options = {}) {
+    const columnBuilder = table.specificType(column.name, column.type);
+    if (column.primary && !options.alter) {
+        columnBuilder.primary();
+    }
+    if (!options.alter || options.alterNullable) {
+        if (column.nullable === false || column.primary) {
+            columnBuilder.notNullable();
+        }
+        else {
+            columnBuilder.nullable();
+        }
+    }
+    if (column.unique && !options.alter) {
+        columnBuilder.unique();
+    }
+    if (column.default !== undefined && options.applyDefault !== false) {
+        columnBuilder.defaultTo(column.default);
+    }
+    const comment = normalizeDatabaseComment(column.comment);
+    if (comment && options.applyComment !== false) {
+        columnBuilder.comment(comment);
+    }
+    if (options.alter) {
+        columnBuilder.alter({
+            alterNullable: options.alterNullable ?? false,
+            alterType: options.alterType ?? false,
+        });
+    }
+}
+export function fieldSchemaIndexes(column, config) {
+    const indexes = [...(config.indexes ?? [])];
+    if (config.index) {
+        indexes.push({
+            columns: [column],
+            name: config.indexName,
+        });
+    }
+    return indexes.length > 0 ? indexes : undefined;
+}
+/**
+ * Base class for reusable field behaviour.
+ *
+ * Static model fields are schema definitions. Each ActiveRecord instance creates
+ * private live field objects that own their value, dirty state, errors, field
+ * name, and parent record reference.
+ *
+ * The low-level lifecycle remains:
+ *
+ * - `createState()` creates per-record storage.
+ * - `setValue()` handles input assignment and stores the hydrated backend value.
+ * - `getValue()` handles normal property reads.
+ * - `validate()` stores field errors.
+ * - `getDataForDb()` returns database write data.
+ * - `setFromDb()` hydrates state from a database row.
+ * - `getDisplayValue()` serializes for frontend/form/API-safe output.
+ */
+export class FieldType {
+    config;
+    $fieldName;
+    $model;
+    $record;
+    $state;
+    $activeContext;
+    constructor(config = {}) {
+        this.config = config;
+    }
+    /**
+     * Logical field name on the parent record.
+     */
+    get name() {
+        return this.fieldName;
+    }
+    /**
+     * Logical field name on the parent record/model.
+     */
+    get fieldName() {
+        return this.context.fieldName;
+    }
+    /**
+     * Parent model metadata.
+     */
+    get model() {
+        return this.context.model;
+    }
+    /**
+     * Parent ActiveRecord instance.
+     */
+    get record() {
+        const record = this.context.record;
+        if (record === undefined) {
+            throw new Error('Field is not bound to a record.');
+        }
+        return record;
+    }
+    required(value = true) {
+        this.config.required = value;
+        return this;
+    }
+    /**
+     * Primary database column for this bound field.
+     */
+    get column() {
+        return this.getColumn();
+    }
+    /**
+     * Current app-memory value for this bound field.
+     */
+    get value() {
+        return this.getValue(this.state);
+    }
+    set value(input) {
+        this.setValue(this.state, input);
+    }
+    /**
+     * Whether this bound field has changed since hydration/default creation.
+     */
+    get dirty() {
+        return this.isDirty(this.state);
+    }
+    /**
+     * Current validation errors for this bound field.
+     */
+    get errors() {
+        return this.getErrors(this.state);
+    }
+    /**
+     * Clears validation errors for this bound field.
+     */
+    clearErrors() {
+        this.state.errors = [];
+    }
+    /**
+     * Hydrates this bound field from a database row.
+     */
+    hydrate(row) {
+        this.setFromDb(this.state, row);
+    }
+    /**
+     * Validates this bound field.
+     */
+    async validateField() {
+        return this.validate(this.state);
+    }
+    /**
+     * Returns database write data for this bound field.
+     */
+    async getBoundDataForDb(options) {
+        return this.getDataForDb(this.state, options);
+    }
+    /**
+     * Returns a frontend/form/API-safe value for this bound field.
+     */
+    getBoundDisplayValue() {
+        return this.getDisplayValue(this.state);
+    }
+    /**
+     * Converts a query value for this bound field.
+     */
+    getBoundQueryValue(input) {
+        return this.getQueryValue(input);
+    }
+    /**
+     * Marks this bound field as clean.
+     */
+    markBoundClean() {
+        this.markClean(this.state);
+    }
+    /**
+     * Returns the column for this field blueprint on a model.
+     */
+    getColumnFor(model, fieldName) {
+        return this.getColumn({
+            model,
+            fieldName,
+        });
+    }
+    /**
+     * Converts a query value for this field blueprint on a model.
+     */
+    getQueryValueFor(model, fieldName, input) {
+        return this.getQueryValue(input, {
+            model,
+            fieldName,
+        });
+    }
+    /**
+     * Returns schema metadata for this field blueprint on a model.
+     */
+    getDbSchemaFor(model, fieldName) {
+        return this.getDbSchema({
+            model,
+            fieldName,
+        });
+    }
+    /**
+     * Returns the DomStudio component spec for rendering this field in a form.
+     */
+    getFormComponent(options = {}, ctx) {
+        return this.withContext(ctx, () => ({
+            component: this.config.frontend?.component || this.defaultFormComponent(),
+            props: {
+                ...this.defaultFormComponentProps(options),
+                ...(this.config.frontend?.props ?? {}),
+            },
+        }));
+    }
+    /**
+     * Returns the DomStudio component spec for rendering this field as a search filter.
+     */
+    getSearchFilterComponent(options = {}, ctx) {
+        return this.withContext(ctx, () => {
+            const component = this.config.frontend?.searchComponent || this.defaultSearchFilterComponent();
+            if (!component)
+                return null;
+            return {
+                component,
+                props: {
+                    ...this.defaultSearchFilterComponentProps(options),
+                    ...(this.config.frontend?.searchProps ?? {}),
+                },
+            };
+        });
+    }
+    /**
+     * Returns a form component spec for an unbound model field.
+     */
+    getFormComponentFor(model, fieldName, options = {}) {
+        return this.getFormComponent(options, {
+            model,
+            fieldName,
+        });
+    }
+    /**
+     * Returns a search component spec for an unbound model field.
+     */
+    getSearchFilterComponentFor(model, fieldName, options = {}) {
+        return this.getSearchFilterComponent(options, {
+            model,
+            fieldName,
+        });
+    }
+    /**
+     * Returns the primary database column for this field.
+     *
+     * Compound fields may still return additional columns from `getDataForDb()`.
+     */
+    getColumn(ctx) {
+        return this.withContext(ctx, () => this.config.column ?? this.fieldName);
+    }
+    /**
+     * Creates per-record runtime state for this field.
+     */
+    createState(ctx) {
+        return this.withContext(ctx, () => {
+            const value = this.getDefaultValue();
+            return {
+                value,
+                originalValue: snapshotFieldValue(value),
+                dirty: false,
+                errors: [],
+            };
+        });
+    }
+    /**
+     * Handles app-level assignment, e.g. `user.email = 'x@example.com'`.
+     *
+     * Keep this mostly synchronous. Async work such as hashing should usually
+     * happen in `getDataForDb()` during save.
+     */
+    setValue(state, input, ctx) {
+        return this.withContext(ctx, () => {
+            const value = this.parse(input);
+            state.value = value;
+            state.dirty = true;
+        });
+    }
+    /**
+     * Handles app-level property reads, e.g. `user.email`.
+     */
+    getValue(state, ctx) {
+        return state.value;
+    }
+    /**
+     * Hydrates field state from a raw database row.
+     */
+    setFromDb(state, row, ctx) {
+        return this.withContext(ctx, () => {
+            const hasColumn = Object.prototype.hasOwnProperty.call(row, this.column);
+            const dbValue = hasColumn ? row[this.column] : undefined;
+            const value = hasColumn
+                ? dbValue === null || dbValue === undefined
+                    ? this.config.default === undefined
+                        ? this.fromDbValue(dbValue)
+                        : this.getDefaultValue()
+                    : this.fromDbValue(dbValue)
+                : this.getDefaultValue();
+            state.value = value;
+            state.originalValue = snapshotFieldValue(value);
+            state.dirty = false;
+            state.errors = [];
+        });
+    }
+    /**
+     * Validates the field and stores the resulting errors on the field state.
+     */
+    async validate(state, ctx) {
+        return this.withContext(ctx, async () => {
+            state.errors = [];
+            const errors = await this.collectErrors(state);
+            state.errors.push(...errors);
+            return state.errors;
+        });
+    }
+    /**
+     * Returns current validation errors for this field state.
+     */
+    getErrors(state) {
+        return state.errors;
+    }
+    /**
+     * Returns true if this field state currently has validation errors.
+     */
+    hasErrors(state) {
+        return state.errors.length > 0;
+    }
+    /**
+     * Returns true if the field has changed since hydration/default creation.
+     */
+    isDirty(state) {
+        return (Boolean(state.dirty)
+            || !isDeepStrictEqual(state.value, state.originalValue));
+    }
+    /**
+     * Marks the state as clean after a successful save or hydration.
+     */
+    markClean(state) {
+        state.originalValue = snapshotFieldValue(state.value);
+        state.dirty = false;
+        state.errors = [];
+    }
+    async getDataForDb(state, ctxOrOptions, options) {
+        const args = this.resolveDbWriteArgs(ctxOrOptions, options);
+        return this.withContext(args.ctx, async () => {
+            if (this.config.generated && this.isEmpty(state.value)) {
+                return {};
+            }
+            if (args.options.onlyDirty && !this.isDirty(state)) {
+                return {};
+            }
+            const value = this.toDbValue(state.value, args.options.valueOptions);
+            return {
+                [this.column]: value,
+            };
+        });
+    }
+    /**
+     * Returns a frontend/form/API-safe value for this field.
+     */
+    getDisplayValue(state, ctx) {
+        return this.withContext(ctx, () => {
+            if (this.config.hidden) {
+                return undefined;
+            }
+            const value = this.getValue(state);
+            if (this.isEmpty(value) && this.config.default !== undefined) {
+                return this.toDisplayValue(this.getDefaultValue());
+            }
+            return this.toDisplayValue(value);
+        });
+    }
+    /**
+     * Alias used by JSON transport. Framework docs call this display data.
+     */
+    getJsonValue(state, ctx) {
+        return this.getDisplayValue(state, ctx);
+    }
+    /**
+     * Converts an input query value into its database representation.
+     *
+     * Query builder methods call this so `where('email', 'STEVE@EXAMPLE.COM')`
+     * can compare against the normalized database value.
+     */
+    getQueryValue(input, ctx) {
+        return this.withContext(ctx, () => this.toDbValue(this.parse(input)));
+    }
+    /**
+     * Returns database schema metadata for dev sync and diff tooling.
+     *
+     * When `ctx.table` is present the field also writes its column(s) onto that
+     * Knex builder using the dialect-owned SQL type string.
+     */
+    getDbSchema(ctx) {
+        return this.withContext(ctx, () => {
+            return this.completeDbSchema({
+                columns: [
+                    {
+                        name: this.column,
+                        type: this.schemaDialect().columnTypes.text(),
+                        nullable: !this.config.required && !this.config.primary,
+                        primary: this.config.primary,
+                        unique: this.config.unique,
+                    },
+                ],
+                indexes: fieldSchemaIndexes(this.column, this.config),
+            }, ctx);
+        });
+    }
+    /**
+     * Returns request/input validation rules for this field.
+     */
+    getValidationRules(ctx) {
+        return this.withContext(ctx, () => [
+            this.config.required || this.config.primary ? 'required' : 'nullable',
+        ]);
+    }
+    /**
+     * Parses app/input assignment into the field's app-memory value.
+     */
+    parse(input) {
+        return input;
+    }
+    /**
+     * Default form component for this field type.
+     */
+    defaultFormComponent() {
+        return 'DomTextInput';
+    }
+    /**
+     * Default form props derived from FieldType config.
+     */
+    defaultFormComponentProps(_options) {
+        return {
+            name: this.fieldName,
+            label: this.fieldLabel(),
+            required: Boolean(this.config.required),
+            readOnly: Boolean(this.config.primary || this.config.generated),
+        };
+    }
+    /**
+     * Default search component for this field type.
+     */
+    defaultSearchFilterComponent() {
+        return 'DomTextInput';
+    }
+    /**
+     * Default search props derived from FieldType config.
+     */
+    defaultSearchFilterComponentProps(_options) {
+        return {
+            name: this.fieldName,
+            label: this.fieldLabel(),
+        };
+    }
+    fieldLabel() {
+        return typeof this.config.label === 'string' && this.config.label.trim()
+            ? this.config.label.trim()
+            : startCase(this.fieldName);
+    }
+    /**
+     * Converts a raw database value into app memory.
+     */
+    fromDbValue(input) {
+        return input;
+    }
+    /**
+     * Converts an app-memory value into database storage form.
+     */
+    toDbValue(input, _options) {
+        return input;
+    }
+    /**
+     * Converts a hydrated backend value into frontend/form display data.
+     */
+    toDisplayValue(input) {
+        return input;
+    }
+    /**
+     * Collects validation errors for this field state.
+     *
+     * Concrete fields should call `super.collectErrors()` then append their own
+     * errors.
+     */
+    async collectErrors(state) {
+        const value = state.value;
+        if (this.config.required && this.isEmpty(value)) {
+            return [
+                {
+                    field: this.fieldName,
+                    message: `${this.fieldName} is required`,
+                    code: 'required',
+                    value,
+                },
+            ];
+        }
+        return [];
+    }
+    /**
+     * Tests whether a value should count as empty for required validation.
+     */
+    isEmpty(value) {
+        return value === null || value === undefined || value === '';
+    }
+    /**
+     * Returns the database schema default implied by the runtime field default.
+     */
+    getDbDefaultValue() {
+        if (this.config.default === undefined) {
+            return undefined;
+        }
+        if (typeof this.config.default === 'function') {
+            return undefined;
+        }
+        return this.toDbValue(this.config.default);
+    }
+    /**
+     * Context for this bound field.
+     */
+    get context() {
+        if (this.$activeContext) {
+            return {
+                ...this.$activeContext,
+                record: this.$activeContext.record ?? this.$record,
+            };
+        }
+        return {
+            model: this.requireModel(),
+            record: this.$record,
+            fieldName: this.requireFieldName(),
+        };
+    }
+    /**
+     * Dialect for schema generation, falling back to the configured connection.
+     */
+    schemaDialect() {
+        return this.context.dialect ?? resolveDatabaseDialect();
+    }
+    /**
+     * Returns schema metadata and optionally writes columns onto `ctx.table`.
+     */
+    completeDbSchema(part, ctx) {
+        if (ctx?.table) {
+            for (const column of part.columns ?? []) {
+                writeDbColumn(ctx.table, column, ctx.columnWriteOptions);
+            }
+        }
+        return part;
+    }
+    /**
+     * State for this bound field.
+     */
+    get state() {
+        if (!this.$state) {
+            throw new Error('Field is not bound to a record.');
+        }
+        return this.$state;
+    }
+    /**
+     * Attaches this field instance to a model without creating record state.
+     */
+    bindToModel(model, fieldName) {
+        this.$model = model;
+        this.$fieldName = fieldName;
+        return this;
+    }
+    /**
+     * Returns an unbound copy of this field definition.
+     */
+    clone() {
+        const Field = this.constructor;
+        return new Field(this.config);
+    }
+    /**
+     * Returns a cloned field definition with config overrides applied.
+     */
+    withConfig(config) {
+        const Field = this.constructor;
+        return new Field({
+            ...this.config,
+            ...config,
+        });
+    }
+    bindToRecord(modelOrRecord, recordOrFieldName, fieldName) {
+        const hasExplicitModel = typeof fieldName === 'string';
+        const resolvedModel = hasExplicitModel
+            ? modelOrRecord
+            : this.modelFromRecord(modelOrRecord);
+        const resolvedRecord = hasExplicitModel ? recordOrFieldName : modelOrRecord;
+        const resolvedFieldName = hasExplicitModel
+            ? fieldName
+            : recordOrFieldName;
+        this.bindToModel(resolvedModel, resolvedFieldName);
+        this.$record = resolvedRecord;
+        this.$state = this.createState();
+        return this;
+    }
+    resolveDbWriteArgs(ctxOrOptions, options) {
+        if (options) {
+            return {
+                ctx: ctxOrOptions,
+                options,
+            };
+        }
+        return {
+            options: ctxOrOptions,
+        };
+    }
+    /**
+     * We are trying to deprecate this function in favour of using object functions like this.get
+     * @param ctx @deprecated this.schemaDialect()
+     * @returns
+     */
+    withContext(ctx, callback) {
+        if (!ctx) {
+            return callback();
+        }
+        const previousContext = this.$activeContext;
+        this.$activeContext = ctx;
+        try {
+            const result = callback();
+            if (isFinallyPromise(result)) {
+                return result.finally(() => {
+                    this.$activeContext = previousContext;
+                });
+            }
+            this.$activeContext = previousContext;
+            return result;
+        }
+        catch (error) {
+            this.$activeContext = previousContext;
+            throw error;
+        }
+    }
+    modelFromRecord(record) {
+        const Model = record?.constructor;
+        if (!Model?.table || !Model.primaryKey) {
+            throw new Error('Field record is not backed by an ActiveRecord model.');
+        }
+        return Model;
+    }
+    requireModel() {
+        if (!this.$model) {
+            throw new Error('Field is not bound to a model.');
+        }
+        return this.$model;
+    }
+    requireFieldName() {
+        if (!this.$fieldName) {
+            throw new Error('Field is not bound to a record.');
+        }
+        return this.$fieldName;
+    }
+    /**
+     * Resolves a per-record default, copying cloneable literal values.
+     *
+     * Use a default factory for custom objects that cannot be copied safely.
+     */
+    getDefaultValue() {
+        if (typeof this.config.default === 'function') {
+            return this.config.default();
+        }
+        return snapshotFieldValue((this.config.default ?? null));
+    }
+}