@db3.ai/app 0.1.0-beta.1

package/dist/db/fields/IntegerField.js

@@ -0,0 +1,139 @@
+import { FieldType, fieldSchemaIndexes, } from '../FieldType.js';
+/**
+ * Integer field for numeric model attributes.
+ */
+export class IntegerField extends FieldType {
+    config;
+    constructor(config = {}) {
+        super(config);
+        this.config = config;
+    }
+    parse(input) {
+        if (input === null || input === undefined || input === '') {
+            return null;
+        }
+        const value = typeof input === 'number'
+            ? input
+            : Number(String(input).trim());
+        if (!Number.isFinite(value)) {
+            return null;
+        }
+        return Math.trunc(value);
+    }
+    defaultFormComponent() {
+        return 'DomNumberInput';
+    }
+    defaultSearchFilterComponent() {
+        return 'DomNumberInput';
+    }
+    defaultFormComponentProps(options) {
+        const props = super.defaultFormComponentProps(options);
+        if (this.config.min !== undefined) {
+            props.min = this.config.min;
+        }
+        if (this.config.max !== undefined) {
+            props.max = this.config.max;
+        }
+        return props;
+    }
+    min(value) {
+        this.config.min = value;
+        return this;
+    }
+    max(value) {
+        this.config.max = value;
+        return this;
+    }
+    getValidationRules(ctx) {
+        const rules = super.getValidationRules(ctx);
+        rules.push('integer');
+        if (this.config.min !== undefined) {
+            rules.push({
+                rule: 'min',
+                value: this.config.min,
+            });
+        }
+        if (this.config.max !== undefined) {
+            rules.push({
+                rule: 'max',
+                value: this.config.max,
+            });
+        }
+        return rules;
+    }
+    async collectErrors(state) {
+        const errors = await super.collectErrors(state);
+        const value = state.value;
+        if (value === null) {
+            return errors;
+        }
+        if (this.config.min !== undefined && value < this.config.min) {
+            errors.push({
+                field: this.fieldName,
+                message: `${this.fieldName} must be at least ${this.config.min}`,
+                code: 'min',
+                value,
+                details: {
+                    min: this.config.min,
+                },
+            });
+        }
+        if (this.config.max !== undefined && value > this.config.max) {
+            errors.push({
+                field: this.fieldName,
+                message: `${this.fieldName} must be ${this.config.max} or lower`,
+                code: 'max',
+                value,
+                details: {
+                    max: this.config.max,
+                },
+            });
+        }
+        return errors;
+    }
+    getDbSchema(ctx) {
+        return this.withContext(ctx, () => {
+            const types = this.schemaDialect().columnTypes;
+            return this.completeDbSchema({
+                columns: [
+                    {
+                        name: this.column,
+                        type: types.integer({
+                            unsigned: this.config.unsigned,
+                            big: this.config.big,
+                        }),
+                        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);
+        });
+    }
+}
+export class BigIncrementsField extends IntegerField {
+    constructor(config = {}) {
+        super({
+            primary: true,
+            generated: 'db',
+            ...config,
+        });
+    }
+    getDbSchema(ctx) {
+        return this.withContext(ctx, () => {
+            const types = this.schemaDialect().columnTypes;
+            return this.completeDbSchema({
+                columns: [
+                    {
+                        name: this.column,
+                        type: types.bigIncrements(),
+                        primary: true,
+                    },
+                ],
+                indexes: fieldSchemaIndexes(this.column, this.config),
+            }, ctx);
+        });
+    }
+}

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

@@ -0,0 +1,40 @@
+import { BasicFieldState, DbSchemaPart, FieldConfig, FieldContext, FieldType } from '../FieldType.js';
+/**
+ * Configuration for permissive JSON fields stored in native JSON columns.
+ */
+export interface JsonFieldConfig extends FieldConfig {
+}
+/**
+ * Field that stores JSON-compatible values and persists them as JSON text.
+ */
+export declare class JsonField<TValue = unknown> extends FieldType<TValue, string | TValue | null, TValue, unknown, BasicFieldState<TValue>> {
+    readonly config: JsonFieldConfig;
+    /**
+     * Creates a permissive JSON field.
+     */
+    constructor(config?: JsonFieldConfig);
+    /**
+     * Parses app input. Strings are treated as JSON documents.
+     */
+    protected parse(input: unknown): TValue;
+    /**
+     * Converts a database JSON string or decoded JSON value into app memory.
+     */
+    protected fromDbValue(input: string | TValue | null): TValue;
+    /**
+     * Converts app memory into database JSON storage.
+     */
+    protected toDbValue(input: TValue): string | null;
+    /**
+     * Provides the default form control for editing arbitrary JSON.
+     */
+    protected defaultFormComponent(): string;
+    /**
+     * Disables default search filtering for JSON fields.
+     */
+    protected defaultSearchFilterComponent(): string | null;
+    /**
+     * Describes the database column used by this JSON field.
+     */
+    getDbSchema(ctx?: FieldContext): DbSchemaPart;
+}

package/dist/db/fields/JsonField.js

@@ -0,0 +1,79 @@
+import { FieldType, fieldSchemaIndexes, } from '../FieldType.js';
+/**
+ * Field that stores JSON-compatible values and persists them as JSON text.
+ */
+export class JsonField extends FieldType {
+    config;
+    /**
+     * Creates a permissive JSON field.
+     */
+    constructor(config = {}) {
+        super(config);
+        this.config = config;
+    }
+    /**
+     * Parses app input. Strings are treated as JSON documents.
+     */
+    parse(input) {
+        if (input === null || input === undefined || input === '') {
+            return null;
+        }
+        if (typeof input === 'string') {
+            return JSON.parse(input);
+        }
+        return input;
+    }
+    /**
+     * Converts a database JSON string or decoded JSON value into app memory.
+     */
+    fromDbValue(input) {
+        if (input === null || input === undefined || input === '') {
+            return null;
+        }
+        if (typeof input === 'string') {
+            return JSON.parse(input);
+        }
+        return input;
+    }
+    /**
+     * Converts app memory into database JSON storage.
+     */
+    toDbValue(input) {
+        if (input === null || input === undefined) {
+            return null;
+        }
+        return JSON.stringify(input);
+    }
+    /**
+     * Provides the default form control for editing arbitrary JSON.
+     */
+    defaultFormComponent() {
+        return 'DomJsonInput';
+    }
+    /**
+     * Disables default search filtering for JSON fields.
+     */
+    defaultSearchFilterComponent() {
+        return null;
+    }
+    /**
+     * Describes the database column used by this JSON field.
+     */
+    getDbSchema(ctx) {
+        return this.withContext(ctx, () => {
+            const types = this.schemaDialect().columnTypes;
+            return this.completeDbSchema({
+                columns: [
+                    {
+                        name: this.column,
+                        type: types.json(),
+                        nullable: !this.config.required && !this.config.primary,
+                        primary: this.config.primary,
+                        unique: this.config.unique,
+                    },
+                ],
+                indexes: fieldSchemaIndexes(this.column, this.config),
+            }, ctx);
+        });
+    }
+}

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

@@ -0,0 +1,21 @@
+import { DbSchemaPart, FieldConfig, FieldContext } from '../FieldType.js';
+import { JsonField } from './JsonField.js';
+export type JsonStringFieldDbType = 'json' | 'text' | 'longtext';
+/**
+ * Configuration for JSON values serialised into database storage.
+ */
+export interface JsonStringFieldConfig extends FieldConfig {
+    /** Database storage type. Defaults to `json`. Prefer `field.jsonText()` or `field.jsonLongText()` over setting this directly. */
+    dbType?: JsonStringFieldDbType;
+}
+/**
+ * Field that stores an object/array in app memory but persists JSON to the DB.
+ */
+export declare class JsonStringField<TValue> extends JsonField<TValue | null> {
+    readonly config: JsonStringFieldConfig;
+    constructor(config?: JsonStringFieldConfig);
+    /**
+     * Describes the database column used by this JSON string field.
+     */
+    getDbSchema(ctx?: FieldContext): DbSchemaPart;
+}

package/dist/db/fields/JsonStringField.js

@@ -0,0 +1,41 @@
+import { fieldSchemaIndexes, } from '../FieldType.js';
+import { JsonField, } from './JsonField.js';
+/**
+ * Field that stores an object/array in app memory but persists JSON to the DB.
+ */
+export class JsonStringField extends JsonField {
+    constructor(config = {}) {
+        super(config);
+    }
+    /**
+     * Describes the database column used by this JSON string field.
+     */
+    getDbSchema(ctx) {
+        return this.withContext(ctx, () => {
+            const types = this.schemaDialect().columnTypes;
+            const storage = this.config.dbType ?? 'json';
+            let type;
+            if (storage === 'longtext') {
+                type = types.longText();
+            }
+            else if (storage === 'text') {
+                type = types.text();
+            }
+            else {
+                type = types.json();
+            }
+            return this.completeDbSchema({
+                columns: [
+                    {
+                        name: this.column,
+                        type,
+                        nullable: !this.config.required && !this.config.primary,
+                        primary: this.config.primary,
+                        unique: this.config.unique,
+                    },
+                ],
+                indexes: fieldSchemaIndexes(this.column, this.config),
+            }, ctx);
+        });
+    }
+}

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

@@ -0,0 +1,180 @@
+import type { Knex } from 'knex';
+import type { ActiveRecord, ActiveRecordClass } from '../ActiveRecord.js';
+import { DbRow, DbSchemaPart, DbWriteData, DbWriteOptions, FieldConfig, FieldContext, FieldError, FieldRenderOptions, FieldType } from '../FieldType.js';
+/**
+ * Lightweight reference to another ActiveRecord.
+ *
+ * A link field stores this instead of implicitly loading related records. This
+ * avoids hidden N+1 queries while still giving a convenient `load()` method.
+ */
+export declare class EntityRef<TRecord extends ActiveRecord> {
+    /** Target model class. */
+    readonly target: () => ActiveRecordClass<TRecord>;
+    /** Primary-key value of the target record. */
+    readonly id: unknown;
+    /** Optional already-loaded record. */
+    private loadedRecord?;
+    /**
+     * Returns the primary-key value from a nullable entity reference.
+     *
+     * @param ref - Entity reference to read.
+     * @param message - Error message when the reference or id is missing.
+     * @returns Primary-key value stored on the reference.
+     */
+    static idOrFail<TRecord extends ActiveRecord>(ref: EntityRef<TRecord> | null | undefined, message?: string): unknown;
+    /**
+     * Returns the primary-key value from a nullable entity reference as a string.
+     *
+     * @param ref - Entity reference to read.
+     * @param message - Error message when the reference or id is missing.
+     * @returns Primary-key value converted to a string.
+     */
+    static stringIdOrFail<TRecord extends ActiveRecord>(ref: EntityRef<TRecord> | null | undefined, message?: string): string;
+    constructor(
+    /** Target model class. */
+    target: () => ActiveRecordClass<TRecord>, 
+    /** Primary-key value of the target record. */
+    id: unknown, 
+    /** Optional already-loaded record. */
+    loadedRecord?: (TRecord | null) | undefined);
+    /**
+     * Returns the primary-key value stored on this reference.
+     *
+     * @param message - Error message when the id is missing.
+     * @returns Primary-key value stored on the reference.
+     */
+    idOrFail(message?: string): unknown;
+    /**
+     * Returns the primary-key value stored on this reference as a string.
+     *
+     * @param message - Error message when the id is missing.
+     * @returns Primary-key value converted to a string.
+     */
+    stringIdOrFail(message?: string): string;
+    /**
+     * Returns true if the referenced record has already been loaded.
+     *
+     * @returns True when a loaded-record state is present.
+     */
+    isLoaded(): boolean;
+    /**
+     * Returns the loaded record if available, otherwise null.
+     *
+     * @returns Loaded record or null.
+     */
+    getLoaded(): TRecord | null;
+    /**
+     * Explicitly loads the referenced record.
+     *
+     * @param db - Optional database connection/session.
+     * @returns Referenced record or null when it cannot be found.
+     */
+    load(db?: Knex): Promise<TRecord | null>;
+    /**
+     * Explicitly loads the referenced record and fails when it cannot be found.
+     *
+     * @returns Referenced record.
+     */
+    loadOrFail(): Promise<TRecord>;
+}
+/**
+ * Per-record state for a link field.
+ */
+export interface LinkFieldState<TRecord extends ActiveRecord = ActiveRecord> {
+    /** Referenced primary-key value. */
+    id: unknown | null;
+    /** Optional already-loaded record. */
+    loadedRecord: TRecord | null;
+    /** Whether the optional related record was explicitly loaded. */
+    loaded: boolean;
+    /** Whether JSON/display output should include the loaded record. */
+    displayLoaded: boolean;
+    /** Whether the link changed since hydration. */
+    dirty: boolean;
+    /** Validation errors for this field state. */
+    errors: FieldError[];
+}
+/**
+ * Configuration for link/foreign-key fields.
+ */
+export interface LinkFieldConfig<TRecord extends ActiveRecord> extends FieldConfig {
+    /** Target model class. Wrapped in a function to allow circular model refs. */
+    target: () => ActiveRecordClass<TRecord>;
+    /** Name of the local FK column. Defaults to `${fieldName}_id`. */
+    column?: string;
+    /** Optional ON DELETE action for schema generation. */
+    onDelete?: 'CASCADE' | 'RESTRICT' | 'SET NULL' | 'NO ACTION';
+    /** Optional ON UPDATE action for schema generation. */
+    onUpdate?: 'CASCADE' | 'RESTRICT' | 'SET NULL' | 'NO ACTION';
+}
+/**
+ * Link/foreign-key field.
+ *
+ * App-facing values accepted by `setValue()`:
+ * - an ID value
+ * - an ActiveRecord-like object with the target primary-key property
+ * - an `EntityRef`
+ *
+ * Normal reads return an `EntityRef`, not the loaded record. Loading is explicit:
+ *
+ * ```ts
+ * const author = await post.author.load();
+ * ```
+ */
+export declare class LinkField<TRecord extends ActiveRecord> extends FieldType<EntityRef<TRecord> | null, unknown | null, unknown | null, unknown, LinkFieldState<TRecord>> {
+    readonly config: LinkFieldConfig<TRecord>;
+    constructor(config: LinkFieldConfig<TRecord>);
+    /**
+     * Creates link-specific per-record state.
+     */
+    createState(): LinkFieldState<TRecord>;
+    /**
+     * Default FK column convention: `author` -> `author_id`.
+     */
+    getColumn(ctx?: FieldContext): string;
+    protected defaultFormComponent(): string;
+    protected defaultSearchFilterComponent(): string | null;
+    protected defaultFormComponentProps(options: FieldRenderOptions): Record<string, unknown>;
+    protected defaultSearchFilterComponentProps(options: FieldRenderOptions): Record<string, unknown>;
+    /**
+     * Stores the referenced primary-key value and optional loaded record.
+     */
+    setValue(state: LinkFieldState<TRecord>, input: unknown, ctx?: FieldContext): void;
+    /**
+     * Returns a lightweight reference object for app reads.
+     */
+    getValue(state: LinkFieldState<TRecord>, ctx?: FieldContext): EntityRef<TRecord> | null;
+    /**
+     * Hydrates the FK value from the database row.
+     */
+    setFromDb(state: LinkFieldState<TRecord>, row: DbRow, ctx?: FieldContext): void;
+    /**
+     * Validates required link fields.
+     */
+    validate(state: LinkFieldState<TRecord>, ctx?: FieldContext): Promise<FieldError[]>;
+    /**
+     * Returns FK database data.
+     */
+    getDataForDb(state: LinkFieldState<TRecord>, options: DbWriteOptions): Promise<DbWriteData>;
+    getDataForDb(state: LinkFieldState<TRecord>, ctx: FieldContext, options: DbWriteOptions): Promise<DbWriteData>;
+    /**
+     * Marks the FK as clean after save.
+     */
+    markClean(state: LinkFieldState<TRecord>): void;
+    /**
+     * Stores a loaded relation for JSON/display output without dirtying the FK.
+     */
+    setBoundLoadedRecord(record: TRecord | null): void;
+    /**
+     * Serialises link fields as IDs unless the relation was explicitly included.
+     */
+    getDisplayValue(state: LinkFieldState<TRecord>): unknown;
+    /**
+     * Converts query input to a FK ID.
+     */
+    getQueryValue(input: unknown): unknown;
+    /**
+     * Describes the FK column and foreign-key metadata.
+     */
+    getDbSchema(ctx?: FieldContext): DbSchemaPart;
+}