@db3.ai/app 0.1.0-beta.1

package/src/db/fields/PasswordField.ts

@@ -0,0 +1,294 @@
+import {
+	DbRow,
+	DbSchemaPart,
+	DbWriteData,
+	DbWriteOptions,
+	FieldConfig,
+	FieldContext,
+	FieldError,
+	FieldType,
+	fieldSchemaIndexes,
+} from '../FieldType';
+import type { ValidationRule } from '../../validation';
+import {
+	defaultPasswordHash,
+	type PasswordHash,
+} from '../../auth/passwordHash';
+
+/**
+ * Per-record runtime state for a password field.
+ *
+ * The normal app-facing value is always `null`, but the state may hold an
+ * existing hash or a pending plaintext password waiting to be hashed on save.
+ */
+export interface PasswordFieldState {
+	/** Hash currently stored in memory, usually loaded from the database. */
+	hash: string | null;
+
+	/** Plaintext assigned by the app but not yet converted to a hash. */
+	pendingPlainText: string | null;
+
+	/** Hash generated during `getDataForDb()`, committed in `markClean()`. */
+	preparedHash: string | null;
+
+	/** Whether the password should be included in the next update. */
+	dirty: boolean;
+
+	/** Validation errors for this field state. */
+	errors: FieldError[];
+}
+
+/**
+ * Configuration for password fields.
+ */
+export interface PasswordFieldConfig extends FieldConfig {
+	/** Minimum plaintext password length. Defaults to 12. */
+	minLength?: number;
+
+	/** Database varchar length for the hash. Defaults to 255. */
+	length?: number;
+}
+
+/**
+ * Password field.
+ *
+ * App-facing behaviour:
+ * - `user.password = 'plain text'` stores pending plaintext in field state.
+ * - `user.password` returns `null`.
+ * - `user.toJSON()` omits the password.
+ * - `user.save()` hashes pending plaintext and writes the hash to the database.
+ *
+ * The field clears plaintext after successful database conversion.
+ */
+export class PasswordField extends FieldType<
+	null,
+	string | null,
+	undefined,
+	unknown,
+	PasswordFieldState
+> {
+	declare public readonly config: PasswordFieldConfig;
+
+	constructor(config: PasswordFieldConfig) {
+		super({
+			...config,
+			hidden: true,
+		});
+	}
+
+	/**
+	 * Creates password-specific per-record state.
+	 */
+	override createState(): PasswordFieldState {
+		return {
+			hash: null,
+			pendingPlainText: null,
+			preparedHash: null,
+			dirty: false,
+			errors: [],
+		};
+	}
+
+	/**
+	 * Stores pending plaintext for hashing later during `getDataForDb()`.
+	 */
+	override setValue(
+		state: PasswordFieldState,
+		input: unknown,
+		ctx?: FieldContext,
+	): void {
+		return this.withContext(ctx, () => {
+			if (input === null || input === undefined || input === '') {
+				state.pendingPlainText = null;
+				state.dirty = true;
+				return;
+			}
+
+			state.pendingPlainText = String(input);
+			state.preparedHash = null;
+			state.dirty = true;
+		});
+	}
+
+	/**
+	 * Never exposes a password or hash through normal property access.
+	 */
+	override getValue(): null {
+		return null;
+	}
+
+	protected override defaultFormComponent(): string {
+		return 'DomPasswordInput';
+	}
+
+	protected override defaultSearchFilterComponent(): string | null {
+		return null;
+	}
+
+	override getValidationRules(ctx?: FieldContext): ValidationRule[] {
+		return [
+			...super.getValidationRules(ctx),
+			'string',
+			{
+				rule: 'minLength',
+				value: this.config.minLength ?? 12,
+			},
+		];
+	}
+
+	/**
+	 * Hydrates the existing password hash from a raw database row.
+	 */
+	override setFromDb(
+		state: PasswordFieldState,
+		row: DbRow,
+		ctx?: FieldContext,
+	): void {
+		return this.withContext(ctx, () => {
+			state.hash = row[this.column] === null || row[this.column] === undefined
+				? null
+				: String(row[this.column]);
+
+			state.pendingPlainText = null;
+			state.preparedHash = null;
+			state.dirty = false;
+			state.errors = [];
+		});
+	}
+
+	/**
+	 * Validates required/minimum length rules.
+	 */
+	override async validate(
+		state: PasswordFieldState,
+		ctx?: FieldContext,
+	): Promise<FieldError[]> {
+		return this.withContext(ctx, async () => {
+			state.errors = [];
+
+			if (this.config.required && !state.hash && !state.pendingPlainText) {
+				state.errors.push({
+					field: this.fieldName,
+					message: `${this.fieldName} is required`,
+					code: 'required',
+				});
+			}
+
+			const minLength = this.config.minLength ?? 12;
+
+			if (state.pendingPlainText && state.pendingPlainText.length < minLength) {
+				state.errors.push({
+					field: this.fieldName,
+					message: `${this.fieldName} must be at least ${minLength} characters`,
+					code: 'minLength',
+					details: { minLength },
+				});
+			}
+
+			return state.errors;
+		});
+	}
+
+	/**
+	 * Produces the database hash column.
+	 */
+	override getDataForDb(
+		state: PasswordFieldState,
+		options: DbWriteOptions,
+	): Promise<DbWriteData>;
+	override getDataForDb(
+		state: PasswordFieldState,
+		ctx: FieldContext,
+		options: DbWriteOptions,
+	): Promise<DbWriteData>;
+	override async getDataForDb(
+		state: PasswordFieldState,
+		ctxOrOptions: FieldContext | DbWriteOptions,
+		options?: DbWriteOptions,
+	): Promise<DbWriteData> {
+		const args = this.resolveDbWriteArgs(ctxOrOptions, options);
+
+		return this.withContext(args.ctx, async () => {
+			if (args.options.onlyDirty && !state.dirty) {
+				return {};
+			}
+
+			if (state.pendingPlainText) {
+				state.preparedHash = await defaultPasswordHash.hash(state.pendingPlainText);
+
+				return {
+					[this.column]: state.preparedHash,
+				};
+			}
+
+			if (state.hash) {
+				return {
+					[this.column]: state.hash,
+				};
+			}
+
+			return {};
+		});
+	}
+
+	/**
+	 * Commits the prepared hash and clears plaintext after successful save.
+	 */
+	override markClean(state: PasswordFieldState): void {
+		if (state.preparedHash) {
+			state.hash = state.preparedHash;
+		}
+
+		state.pendingPlainText = null;
+		state.preparedHash = null;
+		state.dirty = false;
+		state.errors = [];
+	}
+
+	/**
+	 * Verifies a plaintext password against this field's hydrated hash.
+	 */
+	verifyPassword(
+		plainText: string,
+		passwordHash: PasswordHash = defaultPasswordHash,
+	): Promise<boolean> {
+		return this.state.hash
+			? passwordHash.verify(plainText, this.state.hash)
+			: Promise.resolve(false);
+	}
+
+	/**
+	 * Passwords are omitted from JSON output.
+	 */
+	override getDisplayValue(): undefined {
+		return undefined;
+	}
+
+	/**
+	 * Prevents accidental password querying.
+	 */
+	override getQueryValue(): never {
+		throw new Error('Password fields cannot be queried directly');
+	}
+
+	/**
+	 * Describes the password hash 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.varchar(this.config.length ?? 255),
+						nullable: !this.config.required,
+						default: this.getDbDefaultValue(),
+					},
+				],
+				indexes: fieldSchemaIndexes(this.column, this.config),
+			}, ctx);
+		});
+	}
+}

package/src/db/fields/StringField.ts

@@ -0,0 +1,154 @@
+import {
+	BasicFieldState,
+	DbSchemaPart,
+	FieldConfig,
+	FieldContext,
+	FieldError,
+	FieldRenderOptions,
+	FieldType,
+	fieldSchemaIndexes,
+} from '../FieldType';
+import type { ValidationRule } from '../../validation';
+
+/**
+ * Configuration for varchar-backed string fields.
+ */
+export interface StringFieldConfig extends FieldConfig {
+	/** Maximum app-memory string length. */
+	maxLength?: number;
+
+	/** Whether to trim incoming strings. Defaults to true. */
+	trim?: boolean;
+
+	/** Database varchar length. Defaults to `maxLength` or 255. */
+	length?: number;
+}
+
+/**
+ * Generic varchar-backed string field.
+ *
+ * Responsibilities:
+ * - coerce input to a string
+ * - optionally trim whitespace
+ * - convert empty strings to null
+ * - validate required/max length
+ * - describe varchar database column metadata
+ */
+export class StringField extends FieldType<
+	string | null,
+	string | null,
+	string | null,
+	unknown,
+	BasicFieldState<string | null>
+> {
+	constructor(public override readonly config: StringFieldConfig = {}) {
+		super(config);
+	}
+
+	/**
+	 * Parses input into a nullable string.
+	 */
+	protected override parse(input: unknown): string | null {
+		if (input === null || input === undefined) {
+			return null;
+		}
+
+		let value = String(input);
+
+		if (this.config.trim !== false) {
+			value = value.trim();
+		}
+
+		return value === '' ? null : value;
+	}
+
+	protected override defaultFormComponent(): string {
+		return 'DomTextInput';
+	}
+
+	protected override defaultFormComponentProps(options: FieldRenderOptions): Record<string, unknown> {
+		const props = super.defaultFormComponentProps(options);
+		const maxLength = this.effectiveMaxLength();
+
+		if (maxLength !== undefined) {
+			props.maxLength = maxLength;
+		}
+
+		return props;
+	}
+
+	override getValidationRules(ctx?: FieldContext): ValidationRule[] {
+		const rules = super.getValidationRules(ctx);
+
+		rules.push('string');
+
+		const maxLength = this.effectiveMaxLength();
+
+		if (maxLength !== undefined) {
+			rules.push({
+				rule: 'maxLength',
+				value: maxLength,
+			});
+		}
+
+		return rules;
+	}
+
+	/**
+	 * Adds string-specific validation on top of required validation.
+	 */
+	protected override async collectErrors(
+		state: BasicFieldState<string | null>,
+	): Promise<FieldError[]> {
+		const errors = await super.collectErrors(state);
+		const value = state.value;
+		const maxLength = this.effectiveMaxLength();
+
+		if (
+			value !== null &&
+			maxLength !== undefined &&
+			value.length > maxLength
+		) {
+			errors.push({
+				field: this.fieldName,
+				message: `${this.fieldName} must be ${maxLength} characters or fewer`,
+				code: 'maxLength',
+				value,
+				details: {
+					maxLength,
+				},
+			});
+		}
+
+		return errors;
+	}
+
+	/**
+	 * Returns database schema metadata for this string field.
+	 */
+	override getDbSchema(ctx?: FieldContext): DbSchemaPart {
+		return this.withContext(ctx, () => {
+			const types = this.schemaDialect().columnTypes;
+
+			return this.completeDbSchema({
+				columns: [
+					{
+						name: this.column,
+						type: types.varchar(this.config.length ?? this.config.maxLength ?? 255),
+						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);
+		});
+	}
+
+	protected effectiveMaxLength(): number | undefined {
+		if (this.config.maxLength !== undefined) return this.config.maxLength;
+
+		return this.config.length ?? 255;
+	}
+}

package/src/db/fields/StringListField.ts

@@ -0,0 +1,179 @@
+import {
+	BasicFieldState,
+	FieldContext,
+	FieldError,
+} from '../FieldType';
+import type { ValidationRule } from '../../validation';
+import {
+	JsonField,
+	type JsonFieldConfig,
+} from './JsonField';
+
+/**
+ * Configuration for JSON-backed lists of short strings.
+ */
+export interface StringListFieldConfig extends JsonFieldConfig {
+	/** Maximum number of saved items. Leave unset to allow storage-sized lists. */
+	maxItems?: number;
+
+	/** Whether values beyond maxItems are truncated. Defaults to true. */
+	truncate?: boolean;
+}
+
+/**
+ * Stores a normalised string array in app memory and JSON in the database.
+ */
+export class StringListField extends JsonField<string[]> {
+	declare public readonly config: StringListFieldConfig;
+
+	/**
+	 * Creates a JSON-backed string list field with an empty-array default.
+	 */
+	constructor(config: StringListFieldConfig = {}) {
+		super({
+			default: () => [],
+			...config,
+		});
+	}
+
+	/**
+	 * Normalises supported input into a deduplicated list of trimmed strings.
+	 */
+	protected override parse(input: unknown): string[] {
+		const values = this.rawValues(input);
+		const seen = new Set<string>();
+		const items: string[] = [];
+		const maxItems = this.config.maxItems;
+
+		if (
+			maxItems !== undefined
+			&& this.config.truncate !== false
+			&& maxItems <= 0
+		) {
+			return [];
+		}
+
+		for (const value of values) {
+			const item = String(value).trim().replace(/\s+/g, ' ');
+			const key = item.toLowerCase();
+
+			if (!item || seen.has(key)) continue;
+
+			seen.add(key);
+			items.push(item);
+
+			if (
+				maxItems !== undefined
+				&& this.config.truncate !== false
+				&& items.length >= maxItems
+			) {
+				break;
+			}
+		}
+
+		return items;
+	}
+
+	/**
+	 * Hydrates persisted JSON or already-decoded storage into app values.
+	 */
+	protected override fromDbValue(input: unknown): string[] {
+		return this.parse(super.fromDbValue(input as string | string[] | null));
+	}
+
+	/**
+	 * Serialises the normalised list for database storage.
+	 */
+	protected override toDbValue(input: string[]): string {
+		return super.toDbValue(this.parse(input)) ?? '[]';
+	}
+
+	/**
+	 * Provides the default form control for editing JSON string lists.
+	 */
+	protected override defaultFormComponent(): string {
+		return 'DomJsonListInput';
+	}
+
+	/**
+	 * Disables default search filtering for list fields.
+	 */
+	protected override defaultSearchFilterComponent(): string | null {
+		return null;
+	}
+
+	/**
+	 * Publishes request validation rules for list-shaped input.
+	 */
+	override getValidationRules(ctx?: FieldContext): ValidationRule[] {
+		const rules = super.getValidationRules(ctx);
+
+		rules.push('array');
+
+		if (this.config.maxItems !== undefined) {
+			rules.push({
+				rule: 'max',
+				value: this.config.maxItems,
+			});
+		}
+
+		return rules;
+	}
+
+	/**
+	 * Reports an item-count validation error when maxItems is configured.
+	 */
+	protected override async collectErrors(
+		state: BasicFieldState<string[]>,
+	): Promise<FieldError[]> {
+		const errors = await super.collectErrors(state);
+		const maxItems = this.config.maxItems;
+
+		if (
+			maxItems !== undefined
+			&& state.value
+			&& state.value.length > maxItems
+		) {
+			errors.push({
+				field: this.fieldName,
+				message: `${this.fieldName} must contain ${maxItems} items or fewer`,
+				code: 'maxItems',
+				value: state.value,
+				details: {
+					maxItems,
+				},
+			});
+		}
+
+		return errors;
+	}
+
+	/**
+	 * Extracts candidate string values from arrays, JSON, and delimited text.
+	 */
+	private rawValues(input: unknown): unknown[] {
+		if (input === null || input === undefined || input === '') {
+			return [];
+		}
+
+		if (Array.isArray(input)) {
+			return input.filter(item => typeof item === 'string');
+		}
+
+		if (typeof input === 'string') {
+			const value = input.trim();
+
+			if (!value) return [];
+
+			if (value.startsWith('[')) {
+				const parsed = JSON.parse(value);
+
+				return Array.isArray(parsed) ? parsed : [];
+			}
+
+			return value.split(/[\n,]/);
+		}
+
+		return [];
+	}
+}

package/src/db/fields/TextField.ts

@@ -0,0 +1,71 @@
+import {
+	DbSchemaPart,
+	FieldConfig,
+	FieldContext,
+	FieldRenderOptions,
+	fieldSchemaIndexes,
+} from '../FieldType';
+import { StringField } from './StringField';
+
+/**
+ * Configuration for text-backed string fields.
+ */
+export interface TextFieldConfig extends FieldConfig {
+	/** Maximum app-memory string length. Text fields have no default max length. */
+	maxLength?: number;
+
+	/** Whether to trim incoming strings. Defaults to true. */
+	trim?: boolean;
+}
+
+/**
+ * String value stored in a text-like database column.
+ */
+export class TextField extends StringField {
+	declare public readonly config: TextFieldConfig;
+
+	constructor(config: TextFieldConfig = {}) {
+		super(config);
+	}
+
+	protected override defaultFormComponent(): string {
+		return 'DomTextareaInput';
+	}
+
+	protected override defaultFormComponentProps(options: FieldRenderOptions): Record<string, unknown> {
+		const props = super.defaultFormComponentProps(options);
+
+		if (this.defaultFormComponent() === 'DomTextareaInput') {
+			props.rows = 4;
+		}
+
+		return props;
+	}
+
+	/**
+	 * Describes the text-like database column used by this field.
+	 */
+	override getDbSchema(ctx?: FieldContext): DbSchemaPart {
+		return this.withContext(ctx, () => {
+			const types = this.schemaDialect().columnTypes;
+
+			return this.completeDbSchema({
+				columns: [
+					{
+						name: this.column,
+						// on modern systems there is no real need to use text or mediumtext - these are historical mostly for extremely memory constrained systems
+						type: types.longText(),
+						nullable: !this.config.required && !this.config.primary,
+						primary: this.config.primary,
+						unique: this.config.unique,
+					},
+				],
+				indexes: fieldSchemaIndexes(this.column, this.config),
+			}, ctx);
+		});
+	}
+
+	protected override effectiveMaxLength(): number | undefined {
+		return this.config.maxLength;
+	}
+}