@db3.ai/app 0.1.0-beta.1

package/dist/db/ActiveRecord.d.ts

@@ -0,0 +1,483 @@
+import type { Knex } from 'knex';
+import { DbRow, DbWriteData, DomFormRenderSpec, FieldError, type FieldClass, type FieldDbValue, type FieldDefinition, type FieldDisplayValue, type FieldMap, type FieldInputMap, type FieldInputValue, FieldType, type FieldValue, FrontendComponentSpec, type DbWriteOptions } from './FieldType.js';
+import { ActiveQueryBuilder } from './ActiveQueryBuilder.js';
+import { type ActiveRecordSoftDeleteConfig } from './SoftDeletes.js';
+import type { FieldBuilder } from './fields/field.js';
+import { type ActiveRecordLookup } from './errors.js';
+import type { ValidationRules } from '../validation/index.js';
+import type * as db from './contracts/index.js';
+export type { FieldBuilder } from './fields/field.js';
+export { RecordNotFoundError } from './errors.js';
+export type { ActiveRecordLookup } from './errors.js';
+export interface ModelFormOptions {
+    name?: string;
+    mode?: 'create' | 'edit' | 'search';
+    includeGenerated?: boolean;
+}
+/**
+ * Options accepted by the ActiveRecord constructor.
+ */
+export interface ActiveRecordOptions {
+    /** Optional database connection/session for this record instance. */
+    db?: Knex;
+    /** True when the provided input is a raw database row. */
+    fromDb?: boolean;
+    /** Whether the record already exists in the database. */
+    persisted?: boolean;
+}
+/**
+ * Options for assigning untrusted request/form values to a record.
+ */
+export interface ActiveRecordRequestOptions {
+    /** Whether primary-key fields may be set from request data. Defaults to false. */
+    includePrimary?: boolean;
+    /** Whether generated fields may be set from request data. Defaults to false. */
+    includeGenerated?: boolean;
+    /** Explicit fillable fields for this request. Defaults to the model config. */
+    fillable?: readonly string[];
+    /** Explicit guarded fields for this request. Defaults to the model config. */
+    guarded?: readonly string[];
+}
+export interface ActiveRecordValidationRulesOptions extends ActiveRecordRequestOptions {
+    /** Whether hidden fields should be included. Defaults to false. */
+    includeHidden?: boolean;
+}
+export type ActiveRecordRequestMap = Record<string, string>;
+export type ActiveRecordConstructor<TRecord extends ActiveRecord = ActiveRecord> = {
+    new (input?: Record<string, unknown>, options?: ActiveRecordOptions): TRecord;
+};
+export type ActiveRecordInstance<TModel extends ActiveRecordConstructor> = InstanceType<TModel>;
+/**
+ * Static side of an ActiveRecord model class.
+ *
+ * Each subclass acts as its own schema by defining static `table`, `primaryKey`,
+ * and a `fields(field)` method.
+ */
+export type ActiveRecordClass<TRecord extends ActiveRecord = ActiveRecord> = ActiveRecordConstructor<TRecord> & {
+    /** Runtime JavaScript class name. */
+    readonly name: string;
+    /** Database table name. */
+    table: string;
+    /** Developer-facing model note for generated schemas and tooling. */
+    comment?: string;
+    /** Logical primary-key field name. */
+    primaryKey: string;
+    /** Fields used to render row labels when this model is linked from another model. */
+    labelFields?: string[];
+    /** Logical fields that request filling may assign. Undefined means all non-guarded fields. */
+    requestFillable?: readonly string[];
+    /** Logical fields that request filling may not assign. */
+    requestGuarded?: readonly string[];
+    /** Static field definitions for the model. */
+    fields(field: FieldBuilder): FieldInputMap;
+    /** Creates an inferred subclass with inherited and additional field definitions. */
+    define: typeof ActiveRecord.define;
+    /** Resolved static field definitions for the model. */
+    getFields(): FieldMap;
+    /** Returns a DomForm render spec composed from the model's FieldTypes. */
+    getForm(options?: ModelFormOptions): DomFormRenderSpec;
+    /** Returns search filter render specs composed from the model's FieldTypes. */
+    getSearchFilters(options?: ModelFormOptions): Record<string, FrontendComponentSpec>;
+    /** Looks up one resolved static field definition. */
+    getField(fieldName: string): FieldType<any, any, any, any, any>;
+    /** Optional default database connection for this model. Falls back to the shared app connection. */
+    db?: Knex;
+    /** Whether inserts/updates should call `.returning('*')`. */
+    returning?: boolean;
+    /** Soft-delete setting. True uses the conventional `deletedAt` logical field. */
+    softDeletes: ActiveRecordSoftDeleteConfig;
+    /** Returns the database connection for this model in the current app/scope. */
+    getDb(): Knex;
+    /** Runs work with a temporary database connection for all ActiveRecord statics. */
+    withDb<TResult>(db: Knex, callback: () => TResult): TResult;
+    /** Binds a default database connection to the model class. */
+    useDb<TModel extends ActiveRecordConstructor>(this: TModel, db: Knex): TModel;
+    /** Creates a new unsaved record bound to the model's current database. */
+    create<TModel extends ActiveRecordConstructor>(this: TModel, input?: NoInfer<ConstructorParameters<TModel>[0]>, options?: Omit<ActiveRecordOptions, 'db'>): ActiveRecordInstance<TModel>;
+    /** Starts a field-aware query for the model. */
+    query<TModel extends ActiveRecordConstructor>(this: TModel, db?: Knex): ActiveQueryBuilder<ActiveRecordInstance<TModel>>;
+    /** Starts a query that includes soft-deleted rows. */
+    withTrashed<TModel extends ActiveRecordConstructor>(this: TModel, db?: Knex): ActiveQueryBuilder<ActiveRecordInstance<TModel>>;
+    /** Starts a query that only includes soft-deleted rows. */
+    onlyTrashed<TModel extends ActiveRecordConstructor>(this: TModel, db?: Knex): ActiveQueryBuilder<ActiveRecordInstance<TModel>>;
+    /** Starts a query that excludes soft-deleted rows. */
+    withoutTrashed<TModel extends ActiveRecordConstructor>(this: TModel, db?: Knex): ActiveQueryBuilder<ActiveRecordInstance<TModel>>;
+    /** Convenience helper for `query().where(...)`. */
+    where<TModel extends ActiveRecordConstructor>(this: TModel, criteria: Record<string, unknown>): ActiveQueryBuilder<ActiveRecordInstance<TModel>>;
+    where<TModel extends ActiveRecordConstructor>(this: TModel, fieldName: string, value: unknown): ActiveQueryBuilder<ActiveRecordInstance<TModel>>;
+    where<TModel extends ActiveRecordConstructor>(this: TModel, fieldName: string, operator: string, value: unknown): ActiveQueryBuilder<ActiveRecordInstance<TModel>>;
+    /** Finds one record by the configured primary key. */
+    findByPk<TModel extends ActiveRecordConstructor>(this: TModel, id: unknown, db?: Knex): Promise<ActiveRecordInstance<TModel> | null>;
+    /** Finds one record by the configured primary key. */
+    find<TModel extends ActiveRecordConstructor>(this: TModel, lookup: ActiveRecordLookup, db?: Knex): Promise<ActiveRecordInstance<TModel> | null>;
+    /** Finds one record by the configured primary key or throws an error if not found. */
+    findOrFail<TModel extends ActiveRecordConstructor>(this: TModel, lookup: ActiveRecordLookup, db?: Knex): Promise<ActiveRecordInstance<TModel>>;
+    /** Hydrates a model instance from a raw database row. */
+    fromDb<TModel extends ActiveRecordConstructor>(this: TModel, row: DbRow, db?: Knex): ActiveRecordInstance<TModel>;
+    /** Returns validation rules generated from model fields. */
+    validationRules(options?: ActiveRecordValidationRulesOptions): ValidationRules;
+};
+/**
+ * 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 declare abstract class ActiveRecord {
+    /** Database table name. Override in subclasses. */
+    static table: string;
+    /** Developer-facing model note for generated schemas and tooling. */
+    static comment: string;
+    /** Logical primary-key field name. Override if not `id`. */
+    static primaryKey: string;
+    /** Fields used to render row labels when this model is linked from another model. */
+    static labelFields: string[];
+    /** Logical fields that request filling may assign. Undefined means all non-guarded fields. */
+    static requestFillable?: readonly string[];
+    /** Logical fields that request filling may not assign. */
+    static requestGuarded: readonly string[];
+    /** Static field factory. Override in subclasses. */
+    static fields(_field: FieldBuilder): FieldInputMap;
+    /**
+     * 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<TBase extends db.ActiveRecordDefinitionBase, TFields extends FieldInputMap>(this: TBase, definition: db.ActiveRecordDefinition<TFields> & {
+        fields(field: FieldBuilder): db.ActiveRecordFieldOverrides<TBase, TFields>;
+    }): db.DefinedActiveRecord<TBase, TFields>;
+    /** Optional model-level database connection. Falls back to the shared app connection. */
+    static db?: Knex;
+    /**
+     * 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: boolean;
+    /** Soft-delete setting. True uses the conventional `deletedAt` logical field. */
+    static softDeletes: ActiveRecordSoftDeleteConfig;
+    /** Per-record live fields, keyed by logical field name. */
+    private readonly $fields;
+    /** Whether the record currently represents an existing database row. */
+    protected $persisted: boolean;
+    /** Optional instance-level database connection/session. */
+    protected $db?: Knex;
+    constructor(input?: Record<string, unknown>, options?: ActiveRecordOptions);
+    /**
+     * 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<TModel extends ActiveRecordConstructor>(this: TModel, db: Knex): TModel;
+    /**
+     * Returns the database connection for the current ActiveRecord operation.
+     */
+    static getDb(): Knex;
+    /**
+     * Runs work with a temporary database connection for all ActiveRecord statics.
+     */
+    static withDb<TResult>(db: Knex, callback: () => TResult): TResult;
+    /**
+     * 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<TModel extends ActiveRecordConstructor>(this: TModel, input?: NoInfer<NonNullable<ConstructorParameters<TModel>[0]>>, options?: Omit<ActiveRecordOptions, 'db'>): ActiveRecordInstance<TModel>;
+    /**
+     * Resolves the model's static field factory with the framework field helper.
+     */
+    static getFields<TRecord extends ActiveRecord>(this: ActiveRecordClass<TRecord>): FieldMap;
+    /**
+     * Returns a DomForm render spec composed from this model's FieldTypes.
+     */
+    static getForm<TRecord extends ActiveRecord>(this: ActiveRecordClass<TRecord>, options?: ModelFormOptions): DomFormRenderSpec;
+    /**
+     * Returns search filter render specs composed from this model's FieldTypes.
+     */
+    static getSearchFilters<TRecord extends ActiveRecord>(this: ActiveRecordClass<TRecord>, options?: ModelFormOptions): Record<string, FrontendComponentSpec>;
+    /**
+     * Looks up one resolved field definition by logical field name.
+     */
+    static getField<TRecord extends ActiveRecord>(this: ActiveRecordClass<TRecord>, fieldName: string): FieldType<any, any, any, any, any>;
+    /**
+     * Starts a field-aware query for this model.
+     */
+    static query<TModel extends ActiveRecordConstructor>(this: TModel, db?: Knex): ActiveQueryBuilder<ActiveRecordInstance<TModel>>;
+    /**
+     * Starts a query that includes soft-deleted rows.
+     */
+    static withTrashed<TModel extends ActiveRecordConstructor>(this: TModel, db?: Knex): ActiveQueryBuilder<ActiveRecordInstance<TModel>>;
+    /**
+     * Starts a query that only includes soft-deleted rows.
+     */
+    static onlyTrashed<TModel extends ActiveRecordConstructor>(this: TModel, db?: Knex): ActiveQueryBuilder<ActiveRecordInstance<TModel>>;
+    /**
+     * Starts a query that excludes soft-deleted rows.
+     */
+    static withoutTrashed<TModel extends ActiveRecordConstructor>(this: TModel, db?: Knex): ActiveQueryBuilder<ActiveRecordInstance<TModel>>;
+    /**
+     * Convenience helper for `Model.query().where(...)`.
+     */
+    static where<TModel extends ActiveRecordConstructor>(this: TModel, criteria: Record<string, unknown>): ActiveQueryBuilder<ActiveRecordInstance<TModel>>;
+    static where<TModel extends ActiveRecordConstructor>(this: TModel, fieldName: string, value: unknown): ActiveQueryBuilder<ActiveRecordInstance<TModel>>;
+    static where<TModel extends ActiveRecordConstructor>(this: TModel, fieldName: string, operator: string, value: unknown): ActiveQueryBuilder<ActiveRecordInstance<TModel>>;
+    /**
+     * Finds one record by the configured primary key.
+     */
+    static findByPk<TModel extends ActiveRecordConstructor>(this: TModel, id: unknown, db?: Knex): Promise<ActiveRecordInstance<TModel> | null>;
+    /**
+     * Finds one record by the configured primary key or field criteria.
+     */
+    static find<TModel extends ActiveRecordConstructor>(this: TModel, lookup: ActiveRecordLookup, db?: Knex): Promise<ActiveRecordInstance<TModel> | null>;
+    /**
+     * Finds one record by the configured primary key or field criteria.
+     *
+     * Throws a `RecordNotFoundError` if no matching row exists.
+     */
+    static findOrFail<TModel extends ActiveRecordConstructor>(this: TModel, lookup: ActiveRecordLookup, db?: Knex): Promise<ActiveRecordInstance<TModel>>;
+    private static queryForLookup;
+    /**
+     * Hydrates a model instance from a raw database row.
+     */
+    static fromDb<TModel extends ActiveRecordConstructor>(this: TModel, row: DbRow, db?: Knex): ActiveRecordInstance<TModel>;
+    /**
+     * Returns Laravel-style validation rules generated from this model's fields.
+     */
+    static validationRules<TRecord extends ActiveRecord>(this: ActiveRecordClass<TRecord>, options?: ActiveRecordValidationRulesOptions): ValidationRules;
+    /**
+     * 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: Record<string, unknown>): this;
+    /**
+     * Assigns request/form values using logical model field names.
+     */
+    assignFromRequest(input: unknown, options?: ActiveRecordRequestOptions): this;
+    /**
+     * 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: unknown, options?: ActiveRecordRequestOptions): this;
+    /**
+     * Fills this record from request/form values using a request-key to model-field map.
+     */
+    setFromRequestWithMap(input: unknown, dataToFieldMap: ActiveRecordRequestMap, options?: ActiveRecordRequestOptions): this;
+    /**
+     * 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: string, value: unknown): this;
+    /**
+     * Dynamically gets a field by logical name.
+     */
+    get(fieldName: string): unknown;
+    /**
+     * Dynamically binds this record instance to a database connection/session.
+     */
+    setDb(db: Knex): this;
+    /**
+     * Returns true if the model has the given logical field.
+     */
+    hasField(fieldName: string): boolean;
+    /**
+     * Returns the bound runtime field for framework-level hydration helpers.
+     */
+    getBoundField(fieldName: string): FieldType<any, any, any, any, any>;
+    /**
+     * Validates fields and stores field errors on each field state.
+     */
+    validate(options?: {
+        onlyDirty?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Clears all current validation errors.
+     */
+    clearErrors(): void;
+    /**
+     * Returns true if any field currently has validation errors.
+     */
+    hasErrors(): boolean;
+    /**
+     * Returns all field errors on this record.
+     */
+    getErrors(): FieldError[];
+    /**
+     * Returns current validation errors for one field.
+     */
+    getFieldErrors(fieldName: string): FieldError[];
+    /**
+     * 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.
+     */
+    getDataForDb(options?: Partial<DbWriteOptions>): Promise<DbWriteData>;
+    /**
+     * Inserts or updates this record.
+     *
+     * Validation runs before any SQL is executed. On validation failure this throws
+     * `RecordValidationError` containing all field errors.
+     */
+    save(): Promise<this>;
+    /**
+     * Deletes the current database row.
+     *
+     * Models with `softDeletes` enabled update their delete timestamp instead of
+     * physically removing the row.
+     */
+    delete(db?: Knex): Promise<number>;
+    /**
+     * Physically deletes the current database row.
+     */
+    forceDelete(db?: Knex): Promise<number>;
+    /**
+     * Restores the current soft-deleted database row.
+     */
+    restore(db?: Knex): Promise<number>;
+    /**
+     * Returns true when this soft-deletable record has been trashed.
+     */
+    trashed(): boolean;
+    /**
+     * Returns hydrated backend values keyed by logical field name.
+     */
+    toAppData(): Record<string, unknown>;
+    /**
+     * Serialises this record using each field's display value.
+     */
+    toDisplayData(): Record<string, unknown>;
+    /**
+     * JSON transport alias for display data.
+     */
+    toJSON(): Record<string, unknown>;
+    /**
+     * Returns true if this record was loaded from or saved to the database.
+     */
+    isPersisted(): boolean;
+    /**
+     * 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?: string): boolean;
+    /**
+     * Protected field getter used by generated accessors and `get()`.
+     */
+    protected $get(fieldName: string): unknown;
+    /**
+     * Protected field setter used by generated accessors and `set()`.
+     */
+    protected $set(fieldName: string, value: unknown): void;
+    /**
+     * Hydrates all fields from a raw database row.
+     */
+    protected $hydrateFromDb(row: DbRow): void;
+    /**
+     * Marks all fields as clean after a successful save/hydration.
+     */
+    protected $markClean(): void;
+    /**
+     * Returns a database where-clause object for the primary key.
+     */
+    protected $primaryKeyWhere(): Record<string, unknown>;
+    /**
+     * Returns one of this record's live field objects.
+     */
+    protected $field(fieldName: string): FieldType<any, any, any, any, any>;
+    /**
+     * Soft deletes the current database row.
+     */
+    private softDelete;
+    /**
+     * Mirrors soft-delete timestamp writes into this record's live field state.
+     */
+    private $setSoftDeleteFieldValues;
+    /**
+     * Returns the static model class for this instance.
+     */
+    private $model;
+    private $canFillFromRequest;
+    /**
+     * Defines an instance getter/setter for a configured field.
+     */
+    private $installAccessor;
+    /**
+     * 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.
+     */
+    private $hasModelAccessor;
+}
+type ResolvedFieldInput<TInput> = TInput extends FieldType<any, any, any, any, any> ? TInput : TInput extends FieldClass<infer TField> ? TField : TInput extends FieldDefinition<infer TField> ? TField : never;
+type ModelFieldInputs<TModel extends {
+    fields(field: FieldBuilder): FieldInputMap;
+}> = ReturnType<TModel['fields']>;
+export declare namespace ActiveRecord {
+    /** Concrete field represented by an instance, constructor or configured definition. */
+    type ResolvedField<TInput> = ResolvedFieldInput<TInput>;
+    type InferInput<TModel extends {
+        fields(field: FieldBuilder): FieldInputMap;
+    }> = {
+        [fieldName in keyof ModelFieldInputs<TModel>]: FieldInputValue<ResolvedFieldInput<ModelFieldInputs<TModel>[fieldName]>>;
+    };
+    type InferValue<TModel extends {
+        fields(field: FieldBuilder): FieldInputMap;
+    }> = {
+        [fieldName in keyof ModelFieldInputs<TModel>]: FieldValue<ResolvedFieldInput<ModelFieldInputs<TModel>[fieldName]>>;
+    };
+    type InferDbRow<TModel extends {
+        fields(field: FieldBuilder): FieldInputMap;
+    }> = {
+        [fieldName in keyof ModelFieldInputs<TModel>]: FieldDbValue<ResolvedFieldInput<ModelFieldInputs<TModel>[fieldName]>>;
+    };
+    type InferDisplay<TModel extends {
+        fields(field: FieldBuilder): FieldInputMap;
+    }> = {
+        [fieldName in keyof ModelFieldInputs<TModel>]: FieldDisplayValue<ResolvedFieldInput<ModelFieldInputs<TModel>[fieldName]>>;
+    };
+}