@db3.ai/app 0.1.0-beta.1

package/src/db/fields/TimestampField.ts

@@ -0,0 +1,164 @@
+import {
+	BasicFieldState,
+	DbSchemaPart,
+	DbWriteData,
+	DbWriteOptions,
+	FieldConfig,
+	FieldContext,
+	FieldType,
+	fieldSchemaIndexes,
+} from '../FieldType';
+
+/**
+ * Configuration for timestamp/date-time fields.
+ */
+export interface TimestampFieldConfig extends FieldConfig {
+	/** Timestamp precision, e.g. 0 for `timestamp(0)`. */
+	precision?: number;
+
+	/** Automatically set the timestamp on create/update. */
+	auto?: 'create' | 'update' | 'both';
+}
+
+/**
+ * Timestamp field using `Date | null` in app memory.
+ *
+ * The database driver may return dates as Date objects or strings depending on
+ * dialect/configuration; this field normalises both to `Date`.
+ */
+export class TimestampField extends FieldType<
+	Date | null,
+	Date | string | null,
+	string | null,
+	unknown,
+	BasicFieldState<Date | null>
+> {
+	declare public readonly config: TimestampFieldConfig;
+
+	constructor(config: TimestampFieldConfig = {}) {
+		super({
+			precision: 0,
+			...config,
+		});
+	}
+
+	/**
+	 * Parses app input into a Date object.
+	 */
+	protected override parse(input: unknown): Date | null {
+		if (input === null || input === undefined || input === '') {
+			return null;
+		}
+
+		if (input instanceof Date) {
+			return input;
+		}
+
+		const date = new Date(String(input));
+
+		if (Number.isNaN(date.getTime())) {
+			return null;
+		}
+
+		return date;
+	}
+
+	/**
+	 * Converts database value into app-memory Date.
+	 */
+	protected override fromDbValue(input: unknown): Date | null {
+		return this.parse(input);
+	}
+
+	/**
+	 * Converts app-memory Date to database value.
+	 */
+	protected override toDbValue(input: Date | null): Date | null {
+		if (input === null || input === undefined) {
+			return null;
+		}
+
+		return input;
+	}
+
+	protected override defaultFormComponent(): string {
+		return 'DomDatePicker';
+	}
+
+	protected override defaultSearchFilterComponent(): string | null {
+		return 'DomDateRange';
+	}
+
+	/**
+	 * Returns an ISO string for JSON output.
+	 */
+	override getDisplayValue(
+		state: BasicFieldState<Date | null>,
+		ctx?: FieldContext,
+	): string | null | undefined {
+		return this.withContext(ctx, () => {
+			if (this.config.hidden) {
+				return undefined;
+			}
+
+			return state.value ? state.value.toISOString() : null;
+		});
+	}
+
+	/**
+	 * Automatically sets create/update timestamps when configured.
+	 */
+	override getDataForDb(
+		state: BasicFieldState<Date | null>,
+		options: DbWriteOptions,
+	): Promise<DbWriteData>;
+	override getDataForDb(
+		state: BasicFieldState<Date | null>,
+		ctx: FieldContext,
+		options: DbWriteOptions,
+	): Promise<DbWriteData>;
+	override async getDataForDb(
+		state: BasicFieldState<Date | null>,
+		ctxOrOptions: FieldContext | DbWriteOptions,
+		options?: DbWriteOptions,
+	): Promise<DbWriteData> {
+		const args = this.resolveDbWriteArgs(ctxOrOptions, options);
+
+		return this.withContext(args.ctx, async () => {
+			if (
+				this.config.auto === 'both' ||
+				(this.config.auto === 'create' && args.options.isInsert) ||
+				(this.config.auto === 'update' && !args.options.isInsert)
+			) {
+				state.value = new Date();
+				state.dirty = true;
+			}
+
+			return super.getDataForDb(state, args.options);
+		});
+	}
+
+	/**
+	 * Describes the timestamp database column.
+	 */
+	override getDbSchema(ctx?: FieldContext): DbSchemaPart {
+		return this.withContext(ctx, () => {
+			const precision = this.config.precision ?? 0;
+			const types = this.schemaDialect().columnTypes;
+
+			return this.completeDbSchema({
+				columns: [
+					{
+						name: this.column,
+						type: types.timestamp(precision),
+						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/src/db/fields/UlidField.ts

@@ -0,0 +1,189 @@
+import { isUlid, ulid } from '@db3.ai/pure/ulid';
+import {
+	BasicFieldState,
+	DbSchemaPart,
+	DbWriteData,
+	DbWriteOptions,
+	FieldContext,
+	FieldError,
+	fieldSchemaIndexes,
+} from '../FieldType';
+import type { ValidationRule } from '../../validation';
+
+import { StringField, StringFieldConfig } from './StringField';
+
+/**
+ * Configuration for ULID fields.
+ */
+export interface UlidFieldConfig extends StringFieldConfig {
+	/**
+	 * Character length. ULIDs are canonically 26 characters.
+	 */
+	length?: 26;
+
+	/**
+	 * Whether the field should generate a ULID automatically.
+	 *
+	 * Kept as serialisable data so this config can be stored in JSON/database.
+	 */
+	generated?: boolean | 'ulid' | 'db';
+
+	/**
+	 * Whether values should be normalised to uppercase.
+	 *
+	 * ULIDs are case-insensitive, but canonical representation is uppercase.
+	 */
+	uppercase?: boolean;
+}
+
+/**
+ * ULID field stored as `char(26)` by default.
+ *
+ * ULIDs are useful primary keys because their string representation sorts
+ * approximately by creation time.
+ */
+export class UlidField extends StringField {
+	declare public readonly config: UlidFieldConfig;
+
+	constructor(config: UlidFieldConfig = {}) {
+		super({
+			primary: true,
+			generated: true,
+			required: true,
+			length: 26,
+			maxLength: 26,
+			trim: true,
+			uppercase: true,
+			...config,
+		});
+	}
+
+	/**
+	 * Creates per-record state.
+	 *
+	 * If generated is enabled, this creates the ULID immediately so `record.id`
+	 * is available before save.
+	 */
+	override createState(ctx?: FieldContext): BasicFieldState<string | null> {
+		const state = super.createState(ctx) as BasicFieldState<string | null>;
+
+		if (!state.value && this.shouldGenerateInApp()) {
+			state.value = ulid();
+			state.originalValue = state.value;
+			state.dirty = false;
+		}
+
+		return state;
+	}
+
+	/**
+	 * Parses app input into canonical ULID form.
+	 */
+	protected override parse(input: unknown): string | null {
+		const value = super.parse(input);
+
+		if (!value) {
+			return null;
+		}
+
+		return this.config.uppercase === false
+			? value
+		: value.toUpperCase();
+	}
+
+	/**
+	 * Returns request-level validation rules for ULID input.
+	 */
+	override getValidationRules(ctx?: FieldContext): ValidationRule[] {
+		return [
+			...super.getValidationRules(ctx),
+			'ulid',
+		];
+	}
+
+	/**
+	 * Converts this field to database write data.
+	 *
+	 * If `generated: 'db'` and the value is empty, the column is omitted so the
+	 * database can provide the value.
+	 */
+	override getDataForDb(
+		state: BasicFieldState<string | null>,
+		options: DbWriteOptions,
+	): Promise<DbWriteData>;
+	override getDataForDb(
+		state: BasicFieldState<string | null>,
+		ctx: FieldContext,
+		options: DbWriteOptions,
+	): Promise<DbWriteData>;
+	override async getDataForDb(
+		state: BasicFieldState<string | null>,
+		ctxOrOptions: FieldContext | DbWriteOptions,
+		options?: DbWriteOptions,
+	): Promise<DbWriteData> {
+		const args = this.resolveDbWriteArgs(ctxOrOptions, options);
+
+		return this.withContext(args.ctx, async () => {
+			if (this.config.generated === 'db' && !state.value) {
+				return {};
+			}
+
+			if (this.shouldGenerateInApp() && !state.value) {
+				state.value = ulid();
+			}
+
+			return super.getDataForDb(state, args.options);
+		});
+	}
+
+	/**
+	 * Adds ULID-format validation when a value is present.
+	 */
+	protected override async collectErrors(
+		state: BasicFieldState<string | null>,
+	): Promise<FieldError[]> {
+		const errors = await super.collectErrors(state);
+		const value = state.value;
+
+		if (value && !isUlid(value)) {
+			errors.push({
+				field: this.fieldName,
+				message: `${this.fieldName} must be a valid ULID`,
+				code: 'ulid',
+				value,
+			});
+		}
+
+		return errors;
+	}
+
+	/**
+	 * Describes a `char(26)` database column.
+	 */
+	override getDbSchema(ctx?: FieldContext): DbSchemaPart {
+		return this.withContext(ctx, () => {
+			const types = this.schemaDialect().columnTypes;
+
+			return this.completeDbSchema({
+				columns: [
+					{
+						name: this.column,
+						type: types.char(26),
+						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);
+		});
+	}
+
+	/**
+	 * Returns true when this field should generate ULIDs in application code.
+	 */
+	protected shouldGenerateInApp(): boolean {
+		return this.config.generated === true || this.config.generated === 'ulid';
+	}
+}

package/src/db/fields/UrlField.ts

@@ -0,0 +1,97 @@
+import {
+	BasicFieldState,
+	FieldContext,
+	FieldError,
+} from '../FieldType';
+import type { ValidationRule } from '../../validation';
+import {
+	TextField,
+	type TextFieldConfig,
+} from './TextField';
+
+/**
+ * Configuration for URL fields.
+ */
+export interface UrlFieldConfig extends TextFieldConfig {
+	/** Allowed URL protocols. Defaults to HTTP and HTTPS. */
+	allowedProtocols?: string[];
+
+	/** Whether the hostname must contain a dot. Defaults to true. */
+	requirePublicHostname?: boolean;
+
+	/** Protocol to prepend when users omit one. Defaults to `https://`. */
+	defaultProtocol?: 'http://' | 'https://';
+}
+
+/**
+ * URL field with request-friendly normalization.
+ *
+ * It accepts values with or without a protocol, trims whitespace, normalises via
+ * the platform URL parser, and returns `null` for values that cannot be saved as
+ * public URLs.
+ */
+export class UrlField extends TextField {
+	declare public readonly config: UrlFieldConfig;
+
+	constructor(config: UrlFieldConfig = {}) {
+		super({
+			maxLength: 2000,
+			...config,
+		});
+	}
+
+	protected override parse(input: unknown): string | null {
+		const value = super.parse(input);
+
+		if (!value) return null;
+
+		return this.normalizeUrl(value);
+	}
+
+	protected override defaultFormComponent(): string {
+		return 'DomUrlInput';
+	}
+
+	override getValidationRules(ctx?: FieldContext): ValidationRule[] {
+		return [
+			...super.getValidationRules(ctx),
+			'url',
+		];
+	}
+
+	protected override async collectErrors(
+		state: BasicFieldState<string | null>,
+	): Promise<FieldError[]> {
+		const errors = await super.collectErrors(state);
+		const value = state.value;
+
+		if (value && !this.normalizeUrl(value)) {
+			errors.push({
+				field: this.fieldName,
+				message: `${this.fieldName} must be a valid URL`,
+				code: 'url',
+				value,
+			});
+		}
+
+		return errors;
+	}
+
+	private normalizeUrl(value: string): string | null {
+		const candidate = /^[a-z][a-z\d+.-]*:\/\//i.test(value)
+			? value
+			: `${this.config.defaultProtocol ?? 'https://'}${value}`;
+
+		try {
+			const url = new URL(candidate);
+			const allowedProtocols = this.config.allowedProtocols ?? ['http:', 'https:'];
+
+			if (!allowedProtocols.includes(url.protocol)) return null;
+			if ((this.config.requirePublicHostname ?? true) && !url.hostname.includes('.')) return null;
+
+			return url.toString();
+		} catch {
+			return null;
+		}
+	}
+}

package/src/db/fields/VectorField.ts

@@ -0,0 +1,266 @@
+import type { ValidationRule } from '../../validation';
+import {
+	type BasicFieldState,
+	type DbSchemaPart,
+	type DbIndexSpec,
+	type FieldConfig,
+	type FieldContext,
+	type FieldError,
+	type FieldRenderOptions,
+	FieldType,
+} from '../FieldType';
+import type { DatabaseDialect, DatabaseValueOptions } from '../dialects';
+import { resolveDatabaseDialect } from '../dialects';
+
+type VectorDbValue = Uint8Array | string | number[] | null;
+
+/**
+ * Configuration for native database vectors such as embeddings.
+ */
+export interface VectorFieldConfig extends FieldConfig {
+	/** Expected number of vector dimensions. Leave unset to use the database default. */
+	dimensions?: number;
+
+	/** Whether to create a database-native vector index. Defaults to true for required vectors. */
+	index?: boolean;
+}
+
+/**
+ * Stores an embedding/vector as a native database VECTOR column.
+ */
+export class VectorField extends FieldType<
+	number[] | null,
+	unknown,
+	number[] | null,
+	unknown,
+	BasicFieldState<number[] | null>
+> {
+	declare public readonly config: VectorFieldConfig;
+
+	/**
+	 * Creates a native vector field and validates schema-level options.
+	 */
+	constructor(config: VectorFieldConfig = {}) {
+		const resolvedConfig: VectorFieldConfig = {
+			selectedByDefault: false,
+			index: config.index ?? Boolean(config.required),
+			...config,
+		};
+
+		super(resolvedConfig);
+		validateVectorConfig(resolvedConfig, resolveDatabaseDialect().vectorMaxDimensions);
+	}
+
+	/**
+	 * Parses JSON text, decoded arrays, or binary vector input into app memory.
+	 */
+	protected override parse(input: unknown): number[] | null {
+		if (input === null || input === undefined || input === '') {
+			return null;
+		}
+
+		return resolveDatabaseDialect().vectorFromDbValue(input);
+	}
+
+	/**
+	 * Hydrates binary vectors, vector text, or already-decoded arrays.
+	 */
+	protected override fromDbValue(input: VectorDbValue): number[] | null {
+		return this.parse(input);
+	}
+
+	/**
+	 * Converts app-memory vectors into the active dialect's native vector value.
+	 */
+	protected override toDbValue(
+		input: number[] | null,
+		options?: DatabaseValueOptions,
+	): unknown {
+		if (input === null || input === undefined) {
+			return null;
+		}
+
+		const dialect = options?.dialect ?? resolveDatabaseDialect();
+
+		return dialect.vectorToDbValue(input, options?.db);
+	}
+
+	/**
+	 * Uses a JSON editor for manual vector editing in generated forms.
+	 */
+	protected override defaultFormComponent(): string {
+		return 'DomJsonInput';
+	}
+
+	/**
+	 * Disables default scalar search filtering for vector fields.
+	 */
+	protected override defaultSearchFilterComponent(): string | null {
+		return null;
+	}
+
+	/**
+	 * Adds dimension metadata to generated vector form props.
+	 */
+	protected override defaultFormComponentProps(options: FieldRenderOptions): Record<string, unknown> {
+		const props = super.defaultFormComponentProps(options);
+
+		if (this.config.dimensions !== undefined) {
+			props.dimensions = this.config.dimensions;
+		}
+
+		return props;
+	}
+
+	/**
+	 * Publishes request validation rules for array-shaped vector input.
+	 */
+	override getValidationRules(ctx?: FieldContext): ValidationRule[] {
+		const rules = super.getValidationRules(ctx);
+
+		rules.push('array');
+
+		return rules;
+	}
+
+	/**
+	 * Describes the native VECTOR column used by this field.
+	 */
+	override getDbSchema(ctx?: FieldContext): DbSchemaPart {
+		return this.withContext(ctx, () => {
+			const dialect = this.schemaDialect();
+
+			validateVectorConfig(this.config, dialect.vectorMaxDimensions);
+
+			return this.completeDbSchema({
+				columns: [
+					{
+						name: this.column,
+						type: dialect.vectorColumnType(this.config.dimensions),
+						nullable: !this.config.required,
+					},
+				],
+				indexes: vectorSchemaIndexes(this.column, this.config, dialect),
+			}, ctx);
+		});
+	}
+
+	/**
+	 * Reports non-array, non-number, and dimension mismatch errors.
+	 */
+	protected override async collectErrors(
+		state: BasicFieldState<number[] | null>,
+	): Promise<FieldError[]> {
+		const errors = await super.collectErrors(state);
+		const value = state.value as unknown;
+
+		if (this.isEmpty(value)) {
+			return errors;
+		}
+
+		if (!Array.isArray(value)) {
+			errors.push({
+				field: this.fieldName,
+				message: `${this.fieldName} must be an array of numbers`,
+				code: 'array',
+				value,
+			});
+
+			return errors;
+		}
+
+		const invalidIndex = value.findIndex(item => (
+			typeof item !== 'number' || !Number.isFinite(item)
+		));
+
+		if (invalidIndex !== -1) {
+			errors.push({
+				field: this.fieldName,
+				message: `${this.fieldName} must contain only finite numbers`,
+				code: 'numberArray',
+				value,
+				details: {
+					invalidIndex,
+				},
+			});
+		}
+
+		if (
+			this.config.dimensions !== undefined
+			&& value.length !== this.config.dimensions
+		) {
+			errors.push({
+				field: this.fieldName,
+				message: `${this.fieldName} must contain ${this.config.dimensions} numbers`,
+				code: 'dimensions',
+				value,
+				details: {
+					dimensions: this.config.dimensions,
+					actual: value.length,
+				},
+			});
+		}
+
+		return errors;
+	}
+
+	/**
+	 * Treats an empty vector as empty for required validation.
+	 */
+	protected override isEmpty(value: unknown): boolean {
+		return super.isEmpty(value) || (Array.isArray(value) && value.length === 0);
+	}
+}
+
+/**
+ * Validates configuration that native VECTOR columns cannot support.
+ */
+function validateVectorConfig(
+	config: VectorFieldConfig,
+	maxDimensions: number,
+): void {
+	if (
+		config.dimensions !== undefined
+		&& (
+			!Number.isInteger(config.dimensions)
+			|| config.dimensions <= 0
+			|| config.dimensions > maxDimensions
+		)
+	) {
+		throw new Error(
+			`VectorField dimensions must be an integer between 1 and ${maxDimensions}.`,
+		);
+	}
+
+	if (config.primary || config.unique || (config.indexes?.length ?? 0) > 0) {
+		throw new Error('VECTOR columns cannot be primary, unique, or custom normal indexed keys.');
+	}
+
+	if (config.index && !config.required) {
+		throw new Error('VECTOR indexes require required: true because MariaDB vector indexes cannot include nullable columns.');
+	}
+}
+
+/**
+ * Builds the native vector index metadata for dialects that support it.
+ *
+ * @param column - Database column that stores the vector.
+ * @param config - Vector field configuration.
+ * @param dialect - Active database dialect.
+ * @returns Vector index schema metadata, or undefined when disabled/unsupported.
+ */
+function vectorSchemaIndexes(
+	column: string,
+	config: VectorFieldConfig,
+	dialect: DatabaseDialect,
+): DbIndexSpec[] | undefined {
+	if (!config.index || !dialect.supportsVectorIndexes) return undefined;
+
+	return [
+		{
+			type: 'vector',
+			columns: [column],
+			name: config.indexName,
+		},
+	];
+}