@db3.ai/app 0.1.0-beta.1

package/dist/db/FieldType.d.ts

@@ -0,0 +1,540 @@
+import type { Knex } from 'knex';
+import type { ValidationRule } from '../validation/index.js';
+import type { DatabaseDialect, DatabaseValueOptions } from './dialects/index.js';
+/**
+ * Generic database row shape returned by the SQL driver.
+ */
+export type DbRow = Record<string, unknown>;
+/**
+ * Partial database row used for inserts and updates.
+ *
+ * A field returns an object instead of a scalar because some fields may map to
+ * multiple database columns. For example, a map/location field could return
+ * `{ location_lat, location_lng }`.
+ */
+export type DbWriteData = Record<string, unknown>;
+/**
+ * A structured validation error attached to a specific model field.
+ */
+export interface FieldError {
+    /** Logical field name on the model, for example `email` or `password`. */
+    field: string;
+    /** Human-readable error message. */
+    message: string;
+    /** Stable machine-readable error code, for example `required`. */
+    code?: string;
+    /** Offending value, where safe to expose. Avoid storing secrets here. */
+    value?: unknown;
+    /** Extra structured data for UI/API consumers. */
+    details?: unknown;
+}
+/**
+ * Error thrown by `ActiveRecord.save()` when one or more fields are invalid.
+ */
+export declare class RecordValidationError extends Error {
+    readonly errors: FieldError[];
+    constructor(errors: FieldError[]);
+}
+export type FieldDefault = null | string | number | boolean | Record<string, unknown> | unknown[];
+export type FieldDefaultFactory = () => unknown;
+export type GeneratedValue = boolean | 'db' | 'ulid' | 'uuid-v4' | 'now';
+export interface FrontendComponentSpec {
+    component: string;
+    props: Record<string, unknown>;
+}
+export interface DomFormRenderSpec {
+    component: 'DomForm';
+    props: Record<string, unknown>;
+    children: FrontendComponentSpec[];
+}
+export interface FieldFrontendConfig {
+    component?: string;
+    props?: Record<string, unknown>;
+    searchComponent?: string;
+    searchProps?: Record<string, unknown>;
+}
+export interface FieldRenderOptions {
+    mode?: 'create' | 'edit' | 'search';
+}
+/**
+ * Core configuration shared by all fields.
+ *
+ * Concrete field types should extend this with their own options.
+ */
+export interface FieldConfig {
+    /** Database column name. Defaults to the model field name. */
+    column?: string;
+    /** Developer-facing note for generated models and schema tooling. */
+    comment?: string;
+    /** Whether the field must have a non-empty value. */
+    required?: boolean;
+    /** Whether the field is the model primary key. */
+    primary?: boolean;
+    /** Whether the value should be omitted from `toJSON()`. */
+    hidden?: boolean;
+    /** Whether normal ActiveRecord fetches should include this field's columns. */
+    selectedByDefault?: boolean;
+    /** Whether the generated database schema should include a unique constraint. */
+    unique?: boolean;
+    /** Whether the generated database schema should include an index on this field's primary column. */
+    index?: boolean;
+    /** Optional name for the generated single-column index. */
+    indexName?: string;
+    /** Additional generated database schema indexes for this field. */
+    indexes?: DbIndexSpec[];
+    /** Optional human-friendly label for UI/admin/form generation. */
+    label?: string;
+    /** Static default value or runtime factory. Use static values for serializable config. */
+    default?: FieldDefault | FieldDefaultFactory;
+    /** Named generation strategy. This is serializable and lets the field/framework decide how to generate the value. */
+    generated?: GeneratedValue;
+    /** Frontend rendering hints composed by FieldType render helpers. */
+    frontend?: FieldFrontendConfig;
+}
+export type FieldClass<TField extends FieldType<any, any, any, any, any> = FieldType<any, any, any, any, any>> = new (config?: any) => TField;
+export interface FieldDefinition<TField extends FieldType<any, any, any, any, any> = FieldType<any, any, any, any, any>> {
+    type: FieldClass<TField>;
+    config: ConstructorParameters<FieldClass<TField>>[0];
+}
+export type FieldInput<TField extends FieldType<any, any, any, any, any> = FieldType<any, any, any, any, any>> = FieldClass<TField> | FieldDefinition<TField> | TField;
+export type FieldInputMap = Record<string, FieldInput<any>>;
+export type FieldMap = Record<string, FieldType<any, any, any, any, any>>;
+export type FieldMapFactory = (field: any) => FieldInputMap;
+/**
+ * Context passed into low-level field methods.
+ *
+ * Record instances normally use the higher-level field instance API. This
+ * context remains for schema/query work and for concrete field internals.
+ */
+export interface FieldContext {
+    /** The model class metadata. */
+    model: ModelMetadata;
+    /** Database dialect used for schema/value conversion when available. */
+    dialect?: DatabaseDialect;
+    /** Knex table builder when schema is being applied to the database. */
+    table?: Knex.TableBuilder;
+    /** Options used when writing columns through `table`. */
+    columnWriteOptions?: DbColumnWriteOptions;
+    /** The active record instance when available. Query code may omit this. */
+    record?: unknown;
+    /** Logical field name on the model, for example `email`. */
+    fieldName: string;
+}
+/**
+ * Minimal model metadata required by fields.
+ *
+ * This avoids importing `ActiveRecord` into the field base class and keeps the
+ * dependency direction simple.
+ */
+export interface ModelMetadata {
+    /** Database table name. */
+    table: string;
+    /** Logical primary-key field name. */
+    primaryKey: string;
+    /** Static field definitions on the model class. */
+    fields: FieldMapFactory;
+}
+/**
+ * Options passed when collecting database write data from fields.
+ */
+export interface DbWriteOptions {
+    /** True for insert, false for update. */
+    isInsert: boolean;
+    /** Whether clean fields should be excluded from the generated row. */
+    onlyDirty: boolean;
+    /** Database value conversion context for driver-specific field storage. */
+    valueOptions?: DatabaseValueOptions;
+}
+/**
+ * Basic state used by most one-column value fields.
+ */
+export interface BasicFieldState<TValue = unknown> {
+    /** Current app-memory value. */
+    value: TValue;
+    /** Value originally loaded from the database or initial default. */
+    originalValue: TValue;
+    /** Whether the current value differs from the original value. */
+    dirty: boolean;
+    /** Validation errors for this field on this record. */
+    errors: FieldError[];
+}
+/**
+ * Database column description produced by a field's `getDbSchema()`.
+ *
+ * The `type` string comes from the active dialect and is applied directly by
+ * `Database` via Knex `specificType`.
+ */
+export interface DbColumnSpec {
+    /** Database column name. */
+    name: string;
+    /** Database column type, e.g. `varchar(255)`, `char(26)`, `json`, or `longtext`. */
+    type: string;
+    /** Whether null is allowed. */
+    nullable?: boolean;
+    /** Whether this column is the primary key. */
+    primary?: boolean;
+    /** Whether this column has a unique constraint. */
+    unique?: boolean;
+    /** Database default value. */
+    default?: unknown;
+    /** Database-native column comment where supported, such as MySQL. */
+    comment?: string;
+}
+/**
+ * Options for writing a column onto a Knex table builder.
+ */
+export interface DbColumnWriteOptions {
+    alter?: boolean;
+    alterNullable?: boolean;
+    alterType?: boolean;
+    applyDefault?: boolean;
+    applyComment?: boolean;
+}
+/**
+ * Writes a column spec onto a Knex table builder.
+ */
+export declare function writeDbColumn(table: Knex.TableBuilder, column: DbColumnSpec, options?: DbColumnWriteOptions): void;
+/**
+ * Neutral database index description.
+ */
+export interface DbIndexSpec {
+    /** Columns included in the index. */
+    columns: DbIndexColumnSpec[];
+    /** Optional index name. */
+    name?: string;
+    /** Whether the index is unique. */
+    unique?: boolean;
+    /** Database index kind. Defaults to a normal scalar index. */
+    type?: 'normal' | 'vector';
+}
+export type DbIndexColumnSpec = string | {
+    name: string;
+    order?: 'asc' | 'desc';
+};
+export declare function fieldSchemaIndexes(column: string, config: FieldConfig): DbIndexSpec[] | undefined;
+/**
+ * Neutral foreign-key description.
+ */
+export interface DbForeignKeySpec {
+    /** Local database column. */
+    column: string;
+    /** Referenced database table. */
+    referencesTable: string;
+    /** Referenced database column. */
+    referencesColumn: string;
+    /** Optional ON DELETE action. */
+    onDelete?: 'CASCADE' | 'RESTRICT' | 'SET NULL' | 'NO ACTION';
+    /** Optional ON UPDATE action. */
+    onUpdate?: 'CASCADE' | 'RESTRICT' | 'SET NULL' | 'NO ACTION';
+}
+/**
+ * Database schema contribution produced by a single field.
+ */
+export interface DbSchemaPart {
+    /** Columns required by this field. */
+    columns?: DbColumnSpec[];
+    /** Indexes required by this field. */
+    indexes?: DbIndexSpec[];
+    /** Foreign keys required by this field. */
+    foreignKeys?: DbForeignKeySpec[];
+}
+/**
+ * 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 declare abstract class FieldType<TValue = unknown, TDbValue = TValue, TDisplayValue = TValue, TInput = TValue, TState extends {
+    errors: FieldError[];
+} = BasicFieldState<TValue>> {
+    readonly config: FieldConfig;
+    private $fieldName?;
+    private $model?;
+    private $record?;
+    private $state?;
+    private $activeContext?;
+    constructor(config?: FieldConfig);
+    /**
+     * Logical field name on the parent record.
+     */
+    get name(): string;
+    /**
+     * Logical field name on the parent record/model.
+     */
+    get fieldName(): string;
+    /**
+     * Parent model metadata.
+     */
+    get model(): ModelMetadata;
+    /**
+     * Parent ActiveRecord instance.
+     */
+    get record(): unknown;
+    required(value?: boolean): this;
+    /**
+     * Primary database column for this bound field.
+     */
+    get column(): string;
+    /**
+     * Current app-memory value for this bound field.
+     */
+    get value(): TValue;
+    set value(input: TInput);
+    /**
+     * Whether this bound field has changed since hydration/default creation.
+     */
+    get dirty(): boolean;
+    /**
+     * Current validation errors for this bound field.
+     */
+    get errors(): FieldError[];
+    /**
+     * Clears validation errors for this bound field.
+     */
+    clearErrors(): void;
+    /**
+     * Hydrates this bound field from a database row.
+     */
+    hydrate(row: DbRow): void;
+    /**
+     * Validates this bound field.
+     */
+    validateField(): Promise<FieldError[]>;
+    /**
+     * Returns database write data for this bound field.
+     */
+    getBoundDataForDb(options: DbWriteOptions): Promise<DbWriteData>;
+    /**
+     * Returns a frontend/form/API-safe value for this bound field.
+     */
+    getBoundDisplayValue(): TDisplayValue | undefined;
+    /**
+     * Converts a query value for this bound field.
+     */
+    getBoundQueryValue(input: TInput): unknown;
+    /**
+     * Marks this bound field as clean.
+     */
+    markBoundClean(): void;
+    /**
+     * Returns the column for this field blueprint on a model.
+     */
+    getColumnFor(model: ModelMetadata, fieldName: string): string;
+    /**
+     * Converts a query value for this field blueprint on a model.
+     */
+    getQueryValueFor(model: ModelMetadata, fieldName: string, input: TInput): unknown;
+    /**
+     * Returns schema metadata for this field blueprint on a model.
+     */
+    getDbSchemaFor(model: ModelMetadata, fieldName: string): DbSchemaPart;
+    /**
+     * Returns the DomStudio component spec for rendering this field in a form.
+     */
+    getFormComponent(options?: FieldRenderOptions, ctx?: FieldContext): FrontendComponentSpec;
+    /**
+     * Returns the DomStudio component spec for rendering this field as a search filter.
+     */
+    getSearchFilterComponent(options?: FieldRenderOptions, ctx?: FieldContext): FrontendComponentSpec | null;
+    /**
+     * Returns a form component spec for an unbound model field.
+     */
+    getFormComponentFor(model: ModelMetadata, fieldName: string, options?: FieldRenderOptions): FrontendComponentSpec;
+    /**
+     * Returns a search component spec for an unbound model field.
+     */
+    getSearchFilterComponentFor(model: ModelMetadata, fieldName: string, options?: FieldRenderOptions): FrontendComponentSpec | null;
+    /**
+     * Returns the primary database column for this field.
+     *
+     * Compound fields may still return additional columns from `getDataForDb()`.
+     */
+    getColumn(ctx?: FieldContext): string;
+    /**
+     * Creates per-record runtime state for this field.
+     */
+    createState(ctx?: FieldContext): TState;
+    /**
+     * 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: TState, input: TInput, ctx?: FieldContext): void;
+    /**
+     * Handles app-level property reads, e.g. `user.email`.
+     */
+    getValue(state: TState, ctx?: FieldContext): TValue;
+    /**
+     * Hydrates field state from a raw database row.
+     */
+    setFromDb(state: TState, row: DbRow, ctx?: FieldContext): void;
+    /**
+     * Validates the field and stores the resulting errors on the field state.
+     */
+    validate(state: TState, ctx?: FieldContext): Promise<FieldError[]>;
+    /**
+     * Returns current validation errors for this field state.
+     */
+    getErrors(state: TState): FieldError[];
+    /**
+     * Returns true if this field state currently has validation errors.
+     */
+    hasErrors(state: TState): boolean;
+    /**
+     * Returns true if the field has changed since hydration/default creation.
+     */
+    isDirty(state: TState): boolean;
+    /**
+     * Marks the state as clean after a successful save or hydration.
+     */
+    markClean(state: TState): void;
+    /**
+     * Returns database write data for this field.
+     *
+     * The default implementation maps one field to one column.
+     */
+    getDataForDb(state: TState, options: DbWriteOptions): Promise<DbWriteData>;
+    getDataForDb(state: TState, ctx: FieldContext, options: DbWriteOptions): Promise<DbWriteData>;
+    /**
+     * Returns a frontend/form/API-safe value for this field.
+     */
+    getDisplayValue(state: TState, ctx?: FieldContext): TDisplayValue | undefined;
+    /**
+     * Alias used by JSON transport. Framework docs call this display data.
+     */
+    getJsonValue(state: TState, ctx?: FieldContext): TDisplayValue | undefined;
+    /**
+     * 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: TInput, ctx?: FieldContext): unknown;
+    /**
+     * 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?: FieldContext): DbSchemaPart;
+    /**
+     * Returns request/input validation rules for this field.
+     */
+    getValidationRules(ctx?: FieldContext): ValidationRule[];
+    /**
+     * Parses app/input assignment into the field's app-memory value.
+     */
+    protected parse(input: TInput): TValue;
+    /**
+     * Default form component for this field type.
+     */
+    protected defaultFormComponent(): string;
+    /**
+     * Default form props derived from FieldType config.
+     */
+    protected defaultFormComponentProps(_options: FieldRenderOptions): Record<string, unknown>;
+    /**
+     * Default search component for this field type.
+     */
+    protected defaultSearchFilterComponent(): string | null;
+    /**
+     * Default search props derived from FieldType config.
+     */
+    protected defaultSearchFilterComponentProps(_options: FieldRenderOptions): Record<string, unknown>;
+    protected fieldLabel(): string;
+    /**
+     * Converts a raw database value into app memory.
+     */
+    protected fromDbValue(input: TDbValue): TValue;
+    /**
+     * Converts an app-memory value into database storage form.
+     */
+    protected toDbValue(input: TValue, _options?: DatabaseValueOptions): TDbValue;
+    /**
+     * Converts a hydrated backend value into frontend/form display data.
+     */
+    protected toDisplayValue(input: TValue): TDisplayValue;
+    /**
+     * Collects validation errors for this field state.
+     *
+     * Concrete fields should call `super.collectErrors()` then append their own
+     * errors.
+     */
+    protected collectErrors(state: TState): Promise<FieldError[]>;
+    /**
+     * Tests whether a value should count as empty for required validation.
+     */
+    protected isEmpty(value: unknown): boolean;
+    /**
+     * Returns the database schema default implied by the runtime field default.
+     */
+    protected getDbDefaultValue(): unknown;
+    /**
+     * Context for this bound field.
+     */
+    protected get context(): FieldContext;
+    /**
+     * Dialect for schema generation, falling back to the configured connection.
+     */
+    protected schemaDialect(): DatabaseDialect;
+    /**
+     * Returns schema metadata and optionally writes columns onto `ctx.table`.
+     */
+    protected completeDbSchema(part: DbSchemaPart, ctx?: FieldContext): DbSchemaPart;
+    /**
+     * State for this bound field.
+     */
+    protected get state(): TState;
+    /**
+     * Attaches this field instance to a model without creating record state.
+     */
+    bindToModel(model: ModelMetadata, fieldName: string): this;
+    /**
+     * Returns an unbound copy of this field definition.
+     */
+    clone(): this;
+    /**
+     * Returns a cloned field definition with config overrides applied.
+     */
+    withConfig(config: Partial<FieldConfig>): this;
+    /**
+     * Attaches this field instance to a concrete ActiveRecord instance.
+     */
+    bindToRecord(record: unknown, fieldName: string): this;
+    bindToRecord(model: ModelMetadata, record: unknown, fieldName: string): this;
+    protected resolveDbWriteArgs(ctxOrOptions: FieldContext | DbWriteOptions, options?: DbWriteOptions): {
+        ctx?: FieldContext;
+        options: DbWriteOptions;
+    };
+    /**
+     * We are trying to deprecate this function in favour of using object functions like this.get
+     * @param ctx @deprecated this.schemaDialect()
+     * @returns
+     */
+    protected withContext<TResult>(ctx: FieldContext | undefined, callback: () => TResult): TResult;
+    private modelFromRecord;
+    private requireModel;
+    private requireFieldName;
+    /**
+     * Resolves a per-record default, copying cloneable literal values.
+     *
+     * Use a default factory for custom objects that cannot be copied safely.
+     */
+    private getDefaultValue;
+}
+export type FieldValue<TField> = TField extends FieldType<infer TValue, any, any, any, any> ? TValue : never;
+export type FieldDbValue<TField> = TField extends FieldType<any, infer TDbValue, any, any, any> ? TDbValue : never;
+export type FieldDisplayValue<TField> = TField extends FieldType<any, any, infer TDisplayValue, any, any> ? TDisplayValue : never;
+export type FieldInputValue<TField> = TField extends FieldType<any, any, any, infer TInput, any> ? TInput : never;