@db3.ai/app 0.1.0-beta.1

package/src/db/examples/workspaceNotes.ts

@@ -0,0 +1,57 @@
+import { KnowledgeNote } from './KnowledgeNote';
+
+/**
+ * Saves allowed request fields under a workspace already authorized by the host.
+ *
+ * @param workspaceId - Trusted workspace identity, never taken from the payload.
+ * @param input - Untrusted form data; only title and body are fillable.
+ * @returns The persisted note, or rejects with RecordValidationError.
+ */
+export async function createWorkspaceNote(workspaceId: string, input: unknown): Promise<KnowledgeNote> {
+	const note = new KnowledgeNote();
+	note.setFromRequest(input);
+	note.assign({ workspace: workspaceId });
+	await note.save();
+	return note;
+}
+
+/**
+ * Reads a bounded list using logical model fields, not database column names.
+ *
+ * @param workspaceId - Workspace the caller is already allowed to read.
+ * @returns Up to twenty notes, newest first with a stable primary-key tie-break.
+ */
+export async function listWorkspaceNotes(workspaceId: string): Promise<KnowledgeNote[]> {
+	return KnowledgeNote.where('workspace', workspaceId)
+		.orderBy('createdAt', 'desc')
+		.orderBy('id', 'desc')
+		.limit(20)
+		.all();
+}
+
+/**
+ * Updates a note only when it belongs to the caller's authorized workspace.
+ *
+ * @param workspaceId - Trusted workspace identity.
+ * @param noteId - Note identity to look up within that workspace.
+ * @param input - Untrusted editable fields; omitted values remain unchanged.
+ * @returns The saved record; a missing or cross-workspace note is not found.
+ */
+export async function updateWorkspaceNote(workspaceId: string, noteId: string, input: unknown): Promise<KnowledgeNote> {
+	const note = await KnowledgeNote.where({ workspace: workspaceId, id: noteId }).firstOrFail();
+	note.setFromRequest(input);
+	await note.save();
+	return note;
+}
+
+/**
+ * Permanently deletes a note within an already authorized workspace.
+ *
+ * @param workspaceId - Trusted workspace identity.
+ * @param noteId - Note identity scoped to that workspace.
+ * @returns The number of deleted rows; throws when the scoped record is absent.
+ */
+export async function deleteWorkspaceNote(workspaceId: string, noteId: string): Promise<number> {
+	const note = await KnowledgeNote.where({ workspace: workspaceId, id: noteId }).firstOrFail();
+	return note.delete();
+}

package/src/db/fields/BooleanField.ts

@@ -0,0 +1,128 @@
+import {
+	BasicFieldState,
+	DbSchemaPart,
+	FieldConfig,
+	FieldContext,
+	FieldType,
+	fieldSchemaIndexes,
+} from '../FieldType';
+import type { ValidationRule } from '../../validation';
+import type { DatabaseDialect } from '../dialects';
+
+/**
+ * Configuration for boolean fields.
+ */
+export interface BooleanFieldConfig extends FieldConfig { }
+
+/**
+ * Boolean field with light coercion for common form values.
+ */
+export class BooleanField extends FieldType<
+	boolean | null,
+	boolean | number | string | null,
+	boolean | null,
+	unknown,
+	BasicFieldState<boolean | null>
+> {
+	constructor(public override readonly config: BooleanFieldConfig = {}) {
+		super(config);
+	}
+
+	/**
+	 * Parses booleans from booleans, numbers, and common strings.
+	 */
+	protected override parse(input: unknown): boolean | null {
+		if (input === null || input === undefined || input === '') {
+			return null;
+		}
+
+		if (typeof input === 'boolean') {
+			return input;
+		}
+
+		if (typeof input === 'number') {
+			return input !== 0;
+		}
+
+		const value = String(input).toLowerCase().trim();
+
+		if (['true', '1', 'yes', 'on'].includes(value)) {
+			return true;
+		}
+
+		if (['false', '0', 'no', 'off'].includes(value)) {
+			return false;
+		}
+
+		return null;
+	}
+
+	/**
+	 * Normalises database driver boolean values such as MySQL's 1/0 integers.
+	 */
+	protected override fromDbValue(input: unknown): boolean | null {
+		return this.parse(input);
+	}
+
+	protected override defaultFormComponent(): string {
+		return 'DomToggle';
+	}
+
+	protected override defaultSearchFilterComponent(): string | null {
+		return 'DomToggle';
+	}
+
+	override getValidationRules(ctx?: FieldContext): ValidationRule[] {
+		return [
+			...super.getValidationRules(ctx),
+			'boolean',
+		];
+	}
+
+	/**
+	 * Describes the boolean database column.
+	 */
+	override getDbSchema(ctx?: FieldContext): DbSchemaPart {
+		return this.withContext(ctx, () => {
+			const dialect = this.schemaDialect();
+			const types = dialect.columnTypes;
+
+			return this.completeDbSchema({
+				columns: [
+					{
+						name: this.column,
+						type: types.boolean(),
+						nullable: !this.config.required && !this.config.primary,
+						primary: this.config.primary,
+						unique: this.config.unique,
+						default: booleanDatabaseDefault(
+							this.getDbDefaultValue(),
+							dialect,
+						),
+					},
+				],
+				indexes: fieldSchemaIndexes(this.column, this.config),
+			}, ctx);
+		});
+	}
+}
+
+/**
+ * Converts logical boolean defaults into values accepted by each SQL dialect.
+ *
+ * MySQL and MariaDB expose booleans as numeric columns and reject a quoted
+ * `true` or `false` emitted by Knex for `specificType()` columns. Postgres owns
+ * a native boolean type and retains the logical value.
+ *
+ * @param value - Static field default produced by the base field lifecycle.
+ * @param dialect - Database dialect that will create or migrate the column.
+ * @returns Dialect-safe schema default.
+ */
+function booleanDatabaseDefault(
+	value: unknown,
+	dialect: DatabaseDialect,
+): unknown {
+	if (typeof value !== 'boolean') return value;
+
+	return dialect.name === 'postgres' ? value : Number(value);
+}

package/src/db/fields/CharUuidField.ts

@@ -0,0 +1,91 @@
+import {
+	BasicFieldState,
+	DbSchemaPart,
+	FieldContext,
+	FieldError,
+	fieldSchemaIndexes,
+} from '../FieldType';
+import type { ValidationRule } from '../../validation';
+import { StringField, StringFieldConfig } from './StringField';
+
+/**
+ * Configuration for textual UUID fields stored as `char(36)` by default.
+ */
+export interface CharUuidFieldConfig extends StringFieldConfig {
+	/** Character length. Defaults to 36. */
+	length?: number;
+}
+
+/**
+ * UUID-like string field stored as `char(36)`.
+ *
+ * This fits schemas that store UUIDs as text rather than using the native
+ * PostgreSQL `uuid` type.
+ */
+export class CharUuidField extends StringField {
+	declare public readonly config: CharUuidFieldConfig;
+
+	constructor(config: CharUuidFieldConfig = {}) {
+		super({
+			length: 36,
+			maxLength: 36,
+			trim: true,
+			...config,
+		});
+	}
+
+	override getValidationRules(ctx?: FieldContext): ValidationRule[] {
+		return [
+			...super.getValidationRules(ctx),
+			'uuid',
+		];
+	}
+
+	/**
+	 * Adds simple UUID-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 &&
+			!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value)
+		) {
+			errors.push({
+				field: this.fieldName,
+				message: `${this.fieldName} must be a valid UUID`,
+				code: 'uuid',
+				value,
+			});
+		}
+
+		return errors;
+	}
+
+	/**
+	 * Describes a `char(36)` database column.
+	 */
+	override getDbSchema(ctx?: FieldContext): DbSchemaPart {
+		return this.withContext(ctx, () => {
+			const length = this.config.length ?? 36;
+			const types = this.schemaDialect().columnTypes;
+
+			return this.completeDbSchema({
+				columns: [
+					{
+						name: this.column,
+						type: types.char(length),
+						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/ChoiceStringField.ts

@@ -0,0 +1,97 @@
+import {
+	BasicFieldState,
+	FieldContext,
+	FieldError,
+} from '../FieldType';
+import type { ValidationRule } from '../../validation';
+import {
+	StringField,
+	type StringFieldConfig,
+} from './StringField';
+
+/**
+ * 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 class ChoiceStringField extends StringField {
+	declare public readonly config: ChoiceStringFieldConfig;
+
+	constructor(config: ChoiceStringFieldConfig) {
+		super(config);
+	}
+
+	protected override parse(input: unknown): string | null {
+		const value = super.parse(input);
+
+		if (!value) {
+			return this.defaultChoice();
+		}
+
+		const match = this.matchChoice(value);
+
+		return match ?? this.defaultChoice();
+	}
+
+	protected override fromDbValue(input: unknown): string | null {
+		return this.parse(input);
+	}
+
+	override getValidationRules(ctx?: FieldContext): ValidationRule[] {
+		return [
+			...super.getValidationRules(ctx),
+			{
+				rule: 'in',
+				values: this.config.choices,
+			},
+		];
+	}
+
+	protected override async collectErrors(
+		state: BasicFieldState<string | null>,
+	): Promise<FieldError[]> {
+		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;
+	}
+
+	private matchChoice(value: string): string | null {
+		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;
+	}
+
+	private defaultChoice(): string | null {
+		if (typeof this.config.default !== 'string') {
+			return null;
+		}
+
+		return this.matchChoice(this.config.default);
+	}
+}

package/src/db/fields/DecimalField.ts

@@ -0,0 +1,157 @@
+import {
+	BasicFieldState,
+	DbSchemaPart,
+	FieldConfig,
+	FieldContext,
+	FieldError,
+	FieldRenderOptions,
+	FieldType,
+	fieldSchemaIndexes,
+} from '../FieldType';
+import type { ValidationRule } from '../../validation';
+
+export interface DecimalFieldConfig extends FieldConfig {
+	min?: number;
+	max?: number;
+	precision?: number;
+	scale?: number;
+}
+
+export class DecimalField extends FieldType<
+	number | null,
+	number | string | null,
+	number | null,
+	unknown,
+	BasicFieldState<number | null>
+> {
+	declare public readonly config: DecimalFieldConfig;
+
+	constructor(config: DecimalFieldConfig = {}) {
+		super(config);
+	}
+
+	protected override parse(input: unknown): number | null {
+		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;
+	}
+
+	protected override fromDbValue(input: unknown): number | null {
+		return this.parse(input);
+	}
+
+	protected override defaultFormComponent(): string {
+		return 'DomNumberInput';
+	}
+
+	protected override defaultSearchFilterComponent(): string | null {
+		return 'DomNumberInput';
+	}
+
+	protected override defaultFormComponentProps(options: FieldRenderOptions): Record<string, unknown> {
+		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;
+	}
+
+	override getValidationRules(ctx?: FieldContext): ValidationRule[] {
+		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;
+	}
+
+	protected override async collectErrors(
+		state: BasicFieldState<number | null>,
+	): Promise<FieldError[]> {
+		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;
+	}
+
+	override getDbSchema(ctx?: FieldContext): DbSchemaPart {
+		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/src/db/fields/EmailField.ts

@@ -0,0 +1,79 @@
+import {
+	BasicFieldState,
+	FieldContext,
+	FieldError,
+} from '../FieldType';
+import type { ValidationRule } from '../../validation';
+import { StringField, StringFieldConfig } from './StringField';
+
+/**
+ * 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 class EmailField extends StringField {
+	declare public readonly config: EmailFieldConfig;
+
+	constructor(config: EmailFieldConfig = {}) {
+		super({
+			length: 255,
+			maxLength: 255,
+			...config,
+		});
+	}
+
+	/**
+	 * Parses and normalises email input.
+	 */
+	protected override parse(input: unknown): string | null {
+		const value = super.parse(input);
+
+		if (value === null) {
+			return null;
+		}
+
+		return this.config.lowercase === false ? value : value.toLowerCase();
+	}
+
+	protected override defaultFormComponent(): string {
+		return 'DomEmailInput';
+	}
+
+	override getValidationRules(ctx?: FieldContext): ValidationRule[] {
+		return [
+			...super.getValidationRules(ctx),
+			'email',
+		];
+	}
+
+	/**
+	 * Adds basic email-format validation.
+	 */
+	protected override async collectErrors(
+		state: BasicFieldState<string | null>,
+	): Promise<FieldError[]> {
+		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;
+	}
+}