@db3.ai/app 0.1.0-beta.1

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

@@ -0,0 +1,25 @@
+import { BasicFieldState, FieldContext, FieldError } from '../FieldType.js';
+import type { ValidationRule } from '../../validation/index.js';
+import { StringField, type StringFieldConfig } from './StringField.js';
+/**
+ * Configuration for string fields restricted to a known set of values.
+ */
+export interface ChoiceStringFieldConfig extends StringFieldConfig {
+    /** Allowed internal values. */
+    choices: readonly string[];
+    /** Whether matching should be case-sensitive. Defaults to true. */
+    caseSensitive?: boolean;
+}
+/**
+ * String field that normalises to one of a declared set of choices.
+ */
+export declare class ChoiceStringField extends StringField {
+    readonly config: ChoiceStringFieldConfig;
+    constructor(config: ChoiceStringFieldConfig);
+    protected parse(input: unknown): string | null;
+    protected fromDbValue(input: unknown): string | null;
+    getValidationRules(ctx?: FieldContext): ValidationRule[];
+    protected collectErrors(state: BasicFieldState<string | null>): Promise<FieldError[]>;
+    private matchChoice;
+    private defaultChoice;
+}

package/dist/db/fields/ChoiceStringField.js

@@ -0,0 +1,58 @@
+import { StringField, } from './StringField.js';
+/**
+ * String field that normalises to one of a declared set of choices.
+ */
+export class ChoiceStringField extends StringField {
+    constructor(config) {
+        super(config);
+    }
+    parse(input) {
+        const value = super.parse(input);
+        if (!value) {
+            return this.defaultChoice();
+        }
+        const match = this.matchChoice(value);
+        return match ?? this.defaultChoice();
+    }
+    fromDbValue(input) {
+        return this.parse(input);
+    }
+    getValidationRules(ctx) {
+        return [
+            ...super.getValidationRules(ctx),
+            {
+                rule: 'in',
+                values: this.config.choices,
+            },
+        ];
+    }
+    async collectErrors(state) {
+        const errors = await super.collectErrors(state);
+        const value = state.value;
+        if (value && !this.matchChoice(value)) {
+            errors.push({
+                field: this.fieldName,
+                message: `${this.fieldName} must be one of: ${this.config.choices.join(', ')}`,
+                code: 'choice',
+                value,
+                details: {
+                    choices: this.config.choices,
+                },
+            });
+        }
+        return errors;
+    }
+    matchChoice(value) {
+        if (this.config.caseSensitive !== false) {
+            return this.config.choices.includes(value) ? value : null;
+        }
+        const normalized = value.toLowerCase();
+        return this.config.choices.find(choice => choice.toLowerCase() === normalized) ?? null;
+    }
+    defaultChoice() {
+        if (typeof this.config.default !== 'string') {
+            return null;
+        }
+        return this.matchChoice(this.config.default);
+    }
+}

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

@@ -0,0 +1,20 @@
+import { BasicFieldState, DbSchemaPart, FieldConfig, FieldContext, FieldError, FieldRenderOptions, FieldType } from '../FieldType.js';
+import type { ValidationRule } from '../../validation/index.js';
+export interface DecimalFieldConfig extends FieldConfig {
+    min?: number;
+    max?: number;
+    precision?: number;
+    scale?: number;
+}
+export declare class DecimalField extends FieldType<number | null, number | string | null, number | null, unknown, BasicFieldState<number | null>> {
+    readonly config: DecimalFieldConfig;
+    constructor(config?: DecimalFieldConfig);
+    protected parse(input: unknown): number | null;
+    protected fromDbValue(input: unknown): number | null;
+    protected defaultFormComponent(): string;
+    protected defaultSearchFilterComponent(): string | null;
+    protected defaultFormComponentProps(options: FieldRenderOptions): Record<string, unknown>;
+    getValidationRules(ctx?: FieldContext): ValidationRule[];
+    protected collectErrors(state: BasicFieldState<number | null>): Promise<FieldError[]>;
+    getDbSchema(ctx?: FieldContext): DbSchemaPart;
+}

package/dist/db/fields/DecimalField.js

@@ -0,0 +1,105 @@
+import { FieldType, fieldSchemaIndexes, } from '../FieldType.js';
+export class DecimalField extends FieldType {
+    constructor(config = {}) {
+        super(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 value;
+    }
+    fromDbValue(input) {
+        return this.parse(input);
+    }
+    defaultFormComponent() {
+        return 'DomNumberInput';
+    }
+    defaultSearchFilterComponent() {
+        return 'DomNumberInput';
+    }
+    defaultFormComponentProps(options) {
+        const props = super.defaultFormComponentProps(options);
+        props.step = 'any';
+        if (this.config.min !== undefined) {
+            props.min = this.config.min;
+        }
+        if (this.config.max !== undefined) {
+            props.max = this.config.max;
+        }
+        return props;
+    }
+    getValidationRules(ctx) {
+        const rules = super.getValidationRules(ctx);
+        rules.push('number');
+        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 precision = this.config.precision ?? 12;
+            const scale = this.config.scale ?? 4;
+            const types = this.schemaDialect().columnTypes;
+            return this.completeDbSchema({
+                columns: [
+                    {
+                        name: this.column,
+                        type: types.decimal(precision, scale),
+                        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);
+        });
+    }
+}

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

@@ -0,0 +1,31 @@
+import { BasicFieldState, FieldContext, FieldError } from '../FieldType.js';
+import type { ValidationRule } from '../../validation/index.js';
+import { StringField, StringFieldConfig } from './StringField.js';
+/**
+ * Configuration for email fields.
+ */
+export interface EmailFieldConfig extends StringFieldConfig {
+    /** Whether to lowercase incoming email addresses. Defaults to true. */
+    lowercase?: boolean;
+}
+/**
+ * Email field implemented as a specialized string field.
+ *
+ * It normalizes values by trimming and lowercasing, then validates basic email
+ * structure. It intentionally does not send verification emails or check
+ * uniqueness in application code; that belongs to services/database constraints.
+ */
+export declare class EmailField extends StringField {
+    readonly config: EmailFieldConfig;
+    constructor(config?: EmailFieldConfig);
+    /**
+     * Parses and normalises email input.
+     */
+    protected parse(input: unknown): string | null;
+    protected defaultFormComponent(): string;
+    getValidationRules(ctx?: FieldContext): ValidationRule[];
+    /**
+     * Adds basic email-format validation.
+     */
+    protected collectErrors(state: BasicFieldState<string | null>): Promise<FieldError[]>;
+}

package/dist/db/fields/EmailField.js

@@ -0,0 +1,52 @@
+import { StringField } from './StringField.js';
+/**
+ * Email field implemented as a specialized string field.
+ *
+ * It normalizes values by trimming and lowercasing, then validates basic email
+ * structure. It intentionally does not send verification emails or check
+ * uniqueness in application code; that belongs to services/database constraints.
+ */
+export class EmailField extends StringField {
+    constructor(config = {}) {
+        super({
+            length: 255,
+            maxLength: 255,
+            ...config,
+        });
+    }
+    /**
+     * Parses and normalises email input.
+     */
+    parse(input) {
+        const value = super.parse(input);
+        if (value === null) {
+            return null;
+        }
+        return this.config.lowercase === false ? value : value.toLowerCase();
+    }
+    defaultFormComponent() {
+        return 'DomEmailInput';
+    }
+    getValidationRules(ctx) {
+        return [
+            ...super.getValidationRules(ctx),
+            'email',
+        ];
+    }
+    /**
+     * Adds basic email-format validation.
+     */
+    async collectErrors(state) {
+        const errors = await super.collectErrors(state);
+        const value = state.value;
+        if (value && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) {
+            errors.push({
+                field: this.fieldName,
+                message: `${this.fieldName} must be a valid email address`,
+                code: 'email',
+                value,
+            });
+        }
+        return errors;
+    }
+}

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

@@ -0,0 +1,82 @@
+import { Buffer } from 'node:buffer';
+import { type BasicFieldState, type DbSchemaPart, type FieldConfig, type FieldContext, FieldType } from '../FieldType.js';
+/**
+ * Configuration for an authenticated encrypted JSON field.
+ *
+ * Encrypted fields are always hidden, cannot define database defaults or
+ * indexes, and use long text storage because randomized ciphertext is not
+ * queryable JSON.
+ */
+export interface EncryptedJsonFieldConfig extends Omit<FieldConfig, 'hidden' | 'default' | 'unique' | 'index' | 'indexName' | 'indexes'> {
+}
+/**
+ * Error raised when an encrypted JSON field cannot access or use the
+ * application security service.
+ */
+export declare class EncryptedJsonFieldError extends Error {
+    /**
+     * Creates an encrypted-field error with a user-safe message.
+     *
+     * @param message - Error message that must not contain plaintext or ciphertext.
+     * @param options - Optional underlying security-service error.
+     */
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Field that keeps decoded JSON in application memory and delegates encrypted
+ * storage to the active app's central security service.
+ *
+ * Ciphertext is bound to the model table and field column through additional
+ * authenticated data, preventing encrypted values from being moved between
+ * unrelated fields without detection.
+ */
+export declare class EncryptedJsonField<TValue> extends FieldType<TValue | null, string | Buffer | null, undefined, unknown, BasicFieldState<TValue | null>> {
+    #private;
+    readonly config: EncryptedJsonFieldConfig;
+    /**
+     * Creates an encrypted JSON field that is always omitted from display data.
+     *
+     * @param config - Normal field configuration for the encrypted column.
+     */
+    constructor(config?: EncryptedJsonFieldConfig);
+    /**
+     * Prevents encrypted values from being exposed through forms or JSON output.
+     *
+     * @returns Undefined for every encrypted value.
+     */
+    getDisplayValue(): undefined;
+    /**
+     * Prevents equality queries against randomized ciphertext.
+     *
+     * @returns This method never returns.
+     */
+    getQueryValue(): never;
+    /**
+     * Describes the long text column used for versioned encrypted payloads.
+     *
+     * @param ctx - Model and database dialect context.
+     * @returns Schema metadata for the encrypted column.
+     */
+    getDbSchema(ctx?: FieldContext): DbSchemaPart;
+    /**
+     * Parses decoded input or a JSON document into application memory.
+     *
+     * @param input - Decoded JSON value, JSON string, or empty value.
+     * @returns Parsed value or null.
+     */
+    protected parse(input: unknown): TValue | null;
+    /**
+     * Decrypts and parses one database value through the application security service.
+     *
+     * @param input - Versioned ciphertext loaded from the database.
+     * @returns Decoded JSON value or null.
+     */
+    protected fromDbValue(input: string | Buffer | null): TValue | null;
+    /**
+     * Serializes and encrypts one application value through the security service.
+     *
+     * @param input - Decoded JSON value held by the model.
+     * @returns Versioned authenticated ciphertext or null.
+     */
+    protected toDbValue(input: TValue | null): string | null;
+}

package/dist/db/fields/EncryptedJsonField.js

@@ -0,0 +1,169 @@
+import { Buffer } from 'node:buffer';
+import { app } from '../../server/appContext.js';
+import { SecurityError } from '../../security/index.js';
+import { FieldType } from '../FieldType.js';
+/**
+ * Error raised when an encrypted JSON field cannot access or use the
+ * application security service.
+ */
+export class EncryptedJsonFieldError extends Error {
+    /**
+     * Creates an encrypted-field error with a user-safe message.
+     *
+     * @param message - Error message that must not contain plaintext or ciphertext.
+     * @param options - Optional underlying security-service error.
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'EncryptedJsonFieldError';
+    }
+}
+/**
+ * Field that keeps decoded JSON in application memory and delegates encrypted
+ * storage to the active app's central security service.
+ *
+ * Ciphertext is bound to the model table and field column through additional
+ * authenticated data, preventing encrypted values from being moved between
+ * unrelated fields without detection.
+ */
+export class EncryptedJsonField extends FieldType {
+    /**
+     * Creates an encrypted JSON field that is always omitted from display data.
+     *
+     * @param config - Normal field configuration for the encrypted column.
+     */
+    constructor(config = {}) {
+        super({
+            ...config,
+            hidden: true,
+        });
+    }
+    /**
+     * Prevents encrypted values from being exposed through forms or JSON output.
+     *
+     * @returns Undefined for every encrypted value.
+     */
+    getDisplayValue() {
+        return undefined;
+    }
+    /**
+     * Prevents equality queries against randomized ciphertext.
+     *
+     * @returns This method never returns.
+     */
+    getQueryValue() {
+        throw new EncryptedJsonFieldError('Encrypted JSON fields cannot be queried directly.');
+    }
+    /**
+     * Describes the long text column used for versioned encrypted payloads.
+     *
+     * @param ctx - Model and database dialect context.
+     * @returns Schema metadata for the encrypted column.
+     */
+    getDbSchema(ctx) {
+        return this.withContext(ctx, () => {
+            return this.completeDbSchema({
+                columns: [
+                    {
+                        name: this.column,
+                        type: this.schemaDialect().columnTypes.longText(),
+                        nullable: !this.config.required && !this.config.primary,
+                        primary: this.config.primary,
+                    },
+                ],
+                indexes: [],
+            }, ctx);
+        });
+    }
+    /**
+     * Parses decoded input or a JSON document into application memory.
+     *
+     * @param input - Decoded JSON value, JSON string, or empty value.
+     * @returns Parsed value or null.
+     */
+    parse(input) {
+        if (input === null || input === undefined || input === '')
+            return null;
+        return typeof input === 'string'
+            ? JSON.parse(input)
+            : input;
+    }
+    /**
+     * Decrypts and parses one database value through the application security service.
+     *
+     * @param input - Versioned ciphertext loaded from the database.
+     * @returns Decoded JSON value or null.
+     */
+    fromDbValue(input) {
+        if (input === null || input === undefined || input === '')
+            return null;
+        const payload = Buffer.isBuffer(input) ? input.toString('utf8') : input;
+        try {
+            return this.#security().decryptJson(payload, {
+                additionalAuthenticatedData: this.#additionalAuthenticatedData(),
+            });
+        }
+        catch (error) {
+            if (error instanceof EncryptedJsonFieldError)
+                throw error;
+            throw this.#error('could not be decrypted', error);
+        }
+    }
+    /**
+     * Serializes and encrypts one application value through the security service.
+     *
+     * @param input - Decoded JSON value held by the model.
+     * @returns Versioned authenticated ciphertext or null.
+     */
+    toDbValue(input) {
+        if (input === null || input === undefined)
+            return null;
+        try {
+            return this.#security().encryptJson(input, {
+                additionalAuthenticatedData: this.#additionalAuthenticatedData(),
+            });
+        }
+        catch (error) {
+            if (error instanceof EncryptedJsonFieldError)
+                throw error;
+            throw this.#error('could not be encrypted', error);
+        }
+    }
+    /**
+     * Resolves the central security service from the active application.
+     *
+     * @returns Active application security service.
+     */
+    #security() {
+        try {
+            return app().security;
+        }
+        catch (error) {
+            throw this.#error('requires an active application security service', error);
+        }
+    }
+    /**
+     * Builds context bound into the authentication tag for this field.
+     *
+     * @returns Stable table-and-column authentication data.
+     */
+    #additionalAuthenticatedData() {
+        return `${this.model.table}:${this.column}`;
+    }
+    /**
+     * Creates a field-scoped error without including protected values.
+     *
+     * @param reason - Safe explanation of the field failure.
+     * @param cause - Optional security-service error retained for diagnostics.
+     * @returns Encrypted JSON field error.
+     */
+    #error(reason, cause) {
+        const safeCause = cause instanceof SecurityError || cause instanceof Error
+            ? cause
+            : undefined;
+        const causeMessage = safeCause?.message
+            ? `: ${safeCause.message}`
+            : '';
+        return new EncryptedJsonFieldError(`Encrypted JSON field "${this.fieldName}" ${reason}${causeMessage}`, safeCause ? { cause: safeCause } : undefined);
+    }
+}

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

@@ -0,0 +1,35 @@
+import { BasicFieldState, DbSchemaPart, FieldConfig, FieldContext, FieldError, FieldRenderOptions, FieldType } from '../FieldType.js';
+import type { ValidationRule } from '../../validation/index.js';
+/**
+ * Configuration for integer fields.
+ */
+export interface IntegerFieldConfig extends FieldConfig {
+    /** Minimum allowed integer value. */
+    min?: number;
+    /** Maximum allowed integer value. */
+    max?: number;
+    /** Whether to generate an unsigned integer column where supported. */
+    unsigned?: boolean;
+    /** Whether to generate a big integer column. */
+    big?: boolean;
+}
+/**
+ * Integer field for numeric model attributes.
+ */
+export declare class IntegerField extends FieldType<number | null, number | null, number | null, unknown, BasicFieldState<number | null>> {
+    readonly config: IntegerFieldConfig;
+    constructor(config?: IntegerFieldConfig);
+    protected parse(input: unknown): number | null;
+    protected defaultFormComponent(): string;
+    protected defaultSearchFilterComponent(): string | null;
+    protected defaultFormComponentProps(options: FieldRenderOptions): Record<string, unknown>;
+    min(value: number): IntegerField;
+    max(value: number): IntegerField;
+    getValidationRules(ctx?: FieldContext): ValidationRule[];
+    protected collectErrors(state: BasicFieldState<number | null>): Promise<FieldError[]>;
+    getDbSchema(ctx?: FieldContext): DbSchemaPart;
+}
+export declare class BigIncrementsField extends IntegerField {
+    constructor(config?: IntegerFieldConfig);
+    getDbSchema(ctx?: FieldContext): DbSchemaPart;
+}