appflare 0.2.41 → 0.2.43

package/schema.ts

@@ -1,641 +1,641 @@
-export type ColumnType = "int" | "string" | "boolean" | "date" | "enum" | "json";
-
-export type JsonShape =
-	| { kind: "array"; element: JsonShape }
-	| { kind: "object"; shape: Record<string, JsonShape> }
-	| { kind: "string" }
-	| { kind: "number" }
-	| { kind: "boolean" }
-	| { kind: "date" }
-	| { kind: "unknown" };
-
-export type EnumDefinition = {
-	kind: "enum";
-	name: string;
-	sqlName?: string;
-	values: readonly string[];
-};
-
-export type ColumnBuilderOptions = {
-	sqlName?: string;
-	length?: number;
-	enumValues?: readonly string[];
-	enumRef?: string;
-	isArray?: boolean;
-	jsonShape?: JsonShape;
-};
-
-export type PrimaryKeyOptions = {
-	autoIncrement?: boolean;
-};
-
-export type ForeignKeyAction =
-	| "cascade"
-	| "set null"
-	| "set default"
-	| "restrict"
-	| "no action";
-
-export type RelationOneOptions = {
-	referenceField?: string;
-	field?: string;
-	fkType?: ColumnType;
-	sqlName?: string;
-	notNull?: boolean;
-	nullable?: boolean;
-	onDelete?: ForeignKeyAction;
-	onUpdate?: ForeignKeyAction;
-};
-
-export type RelationManyOptions = {
-	referenceField?: string;
-	field?: string;
-	fkType?: ColumnType;
-	sqlName?: string;
-	notNull?: boolean;
-	nullable?: boolean;
-	onDelete?: ForeignKeyAction;
-	onUpdate?: ForeignKeyAction;
-};
-
-export type RelationManyToManyOptions = {
-	referenceField?: string;
-	targetReferenceField?: string;
-	junctionTable?: string;
-	sourceField?: string;
-	targetField?: string;
-	sourceSqlName?: string;
-	targetSqlName?: string;
-	onDelete?: ForeignKeyAction;
-	onUpdate?: ForeignKeyAction;
-};
-
-export type ColumnReference = {
-	table: string;
-	column: string;
-	onDelete?: ForeignKeyAction;
-	onUpdate?: ForeignKeyAction;
-};
-
-export type ColumnDefinition = {
-	kind: "column";
-	type: ColumnType;
-	sqlName?: string;
-	length?: number;
-	notNull?: boolean;
-	nullable?: boolean;
-	primaryKey?: boolean;
-	autoIncrement?: boolean;
-	/** When true the column stores a UUID generated at runtime (string type). */
-	uuidPrimaryKey?: boolean;
-	unique?: true | { name?: string };
-	index?: true | { name?: string };
-	sqlDefault?: unknown;
-	/** When true, the SQL column gets DEFAULT CURRENT_TIMESTAMP and runtime inserts use `new Date()`. */
-	nowDefault?: boolean;
-	runtimeDefaultFn?: () => unknown;
-	references?: ColumnReference;
-	/** For enum columns: the allowed values. */
-	enumValues?: readonly string[];
-	/** For enum columns: reference to a named enum definition. */
-	enumRef?: string;
-	/** When true, the column stores an array of enum values. */
-	isArray?: boolean;
-	/** For JSON columns: the shape of the stored data. */
-	jsonShape?: JsonShape;
-};
-
-export type OneRelationDefinition = {
-	kind: "relation";
-	relation: "one";
-	targetTable: string;
-	field?: string;
-	referenceField?: string;
-	fkType?: ColumnType;
-	sqlName?: string;
-	notNull?: boolean;
-	nullable?: boolean;
-	onDelete?: ForeignKeyAction;
-	onUpdate?: ForeignKeyAction;
-};
-
-export type ManyRelationDefinition = {
-	kind: "relation";
-	relation: "many";
-	targetTable: string;
-	field?: string;
-	referenceField?: string;
-	fkType?: ColumnType;
-	sqlName?: string;
-	notNull?: boolean;
-	nullable?: boolean;
-	onDelete?: ForeignKeyAction;
-	onUpdate?: ForeignKeyAction;
-};
-
-export type ManyToManyRelationDefinition = {
-	kind: "relation";
-	relation: "manyToMany";
-	targetTable: string;
-	referenceField?: string;
-	targetReferenceField?: string;
-	junctionTable?: string;
-	sourceField?: string;
-	targetField?: string;
-	sourceSqlName?: string;
-	targetSqlName?: string;
-	onDelete?: ForeignKeyAction;
-	onUpdate?: ForeignKeyAction;
-};
-
-export type RelationDefinition =
-	| OneRelationDefinition
-	| ManyRelationDefinition
-	| ManyToManyRelationDefinition;
-
-export type TableOptions = {
-	sqlName?: string;
-};
-
-export type TableShape = Record<string, ColumnBuilder | RelationDefinition>;
-
-export type TableDefinition = {
-	kind: "table";
-	sqlName?: string;
-	columns: Record<string, ColumnDefinition>;
-	relations: Record<string, RelationDefinition>;
-};
-
-export type SchemaDefinition = {
-	kind: "schema";
-	tables: Record<string, TableDefinition>;
-	enums: Record<string, EnumDefinition>;
-};
-
-export class EnumBuilder<T extends string> {
-	private def: EnumDefinition;
-
-	public constructor(name: string, values: readonly T[]) {
-		this.def = {
-			kind: "enum",
-			name,
-			values: values as readonly string[],
-		};
-	}
-
-	public sql(name: string): EnumBuilder<T> {
-		return new EnumBuilder<T>(name, this.def.values as readonly T[]);
-	}
-
-	public toDefinition(): EnumDefinition {
-		return { ...this.def };
-	}
-
-	public getValues(): readonly T[] {
-		return this.def.values as readonly T[];
-	}
-}
-
-export function defineEnum<T extends string>(
-	name: string,
-	values: readonly T[],
-): EnumBuilder<T> {
-	return new EnumBuilder(name, values);
-}
-
-export class JsonArrayBuilder {
-	private _element: JsonShape;
-
-	public constructor(element: JsonShape) {
-		this._element = element;
-	}
-
-	public get shape(): JsonShape {
-		return { kind: "array", element: this._element };
-	}
-
-	public toColumnBuilder(): ColumnBuilder {
-		return new ColumnBuilder("json", { jsonShape: this.shape });
-	}
-}
-
-export class JsonObjectBuilder<TShape extends Record<string, JsonShape>> {
-	private _shape: TShape;
-
-	public constructor(shape: TShape) {
-		this._shape = shape;
-	}
-
-	public get shape(): JsonShape {
-		return { kind: "object", shape: this._shape };
-	}
-
-	public toColumnBuilder(): ColumnBuilder {
-		return new ColumnBuilder("json", { jsonShape: this.shape });
-	}
-}
-
-export class ColumnBuilder {
-	private definition: ColumnDefinition;
-
-	public constructor(
-		typeOrDefinition: ColumnType | ColumnDefinition,
-		options: ColumnBuilderOptions = {},
-	) {
-		if (typeof typeOrDefinition === "string") {
-			this.definition = {
-				kind: "column",
-				type: typeOrDefinition,
-				sqlName: options.sqlName,
-				length: options.length,
-				enumValues: options.enumValues,
-				enumRef: options.enumRef,
-				jsonShape: options.jsonShape,
-			};
-			return;
-		}
-
-		this.definition = {
-			...typeOrDefinition,
-		};
-	}
-
-	private with(patch: Partial<ColumnDefinition>): ColumnBuilder {
-		return new ColumnBuilder({
-			...this.definition,
-			...patch,
-		});
-	}
-
-	public sql(name: string): ColumnBuilder {
-		return this.with({ sqlName: name });
-	}
-
-	public notNull(): ColumnBuilder {
-		return this.with({ notNull: true, nullable: false });
-	}
-
-	public nullable(): ColumnBuilder {
-		return this.with({ nullable: true, notNull: false });
-	}
-
-	public primaryKey(options: PrimaryKeyOptions = {}): ColumnBuilder {
-		return this.with({
-			primaryKey: true,
-			autoIncrement: options.autoIncrement ?? this.definition.autoIncrement,
-		});
-	}
-
-	public unique(name?: string): ColumnBuilder {
-		return this.with({ unique: name ? { name } : true });
-	}
-
-	public index(name?: string): ColumnBuilder {
-		return this.with({ index: name ? { name } : true });
-	}
-
-	public default(value: unknown): ColumnBuilder {
-		return this.with({ sqlDefault: value });
-	}
-
-	public defaultFn(fn: () => unknown): ColumnBuilder {
-		return this.with({ runtimeDefaultFn: fn });
-	}
-
-	/**
-	 * Shorthand for date columns that should default to the current timestamp.
-	 * Sets SQL `DEFAULT CURRENT_TIMESTAMP` (via `nowDefault`) and
-	 * a runtime default of `new Date()`.
-	 */
-	public defaultNow(): ColumnBuilder {
-		return this.with({
-			nowDefault: true,
-			runtimeDefaultFn: () => new Date(),
-		});
-	}
-
-	public references(
-		table: string,
-		column = "id",
-		actions: Pick<ColumnReference, "onDelete" | "onUpdate"> = {},
-	): ColumnBuilder {
-		return this.with({
-			references: {
-				table,
-				column,
-				onDelete: actions.onDelete,
-				onUpdate: actions.onUpdate,
-			},
-		});
-	}
-
-	/** Marks the column as an array (e.g., for enum arrays). */
-	public array(): ColumnBuilder {
-		return this.with({ isArray: true });
-	}
-
-	public toDefinition(): ColumnDefinition {
-		return { ...this.definition };
-	}
-}
-
-export function table(
-	shape: TableShape,
-	options: TableOptions = {},
-): TableDefinition {
-	const columns: Record<string, ColumnDefinition> = {};
-	const relations: Record<string, RelationDefinition> = {};
-
-	for (const [fieldName, value] of Object.entries(shape)) {
-		if (value instanceof ColumnBuilder) {
-			columns[fieldName] = value.toDefinition();
-			continue;
-		}
-
-		if (value.kind === "relation") {
-			relations[fieldName] = value;
-			continue;
-		}
-
-		throw new Error(
-			`Invalid table field '${fieldName}'. Use column builders or relation helpers.`,
-		);
-	}
-
-	return {
-		kind: "table",
-		sqlName: options.sqlName,
-		columns,
-		relations,
-	};
-}
-
-export type SchemaOptions = {
-	enums?: Record<string, EnumDefinition>;
-};
-
-export function schema(
-	tables: Record<string, TableDefinition>,
-	options: SchemaOptions = {},
-): SchemaDefinition {
-	return {
-		kind: "schema",
-		tables,
-		enums: options.enums ?? {},
-	};
-}
-
-export function isSchemaDefinition(value: unknown): value is SchemaDefinition {
-	if (typeof value !== "object" || value === null) {
-		return false;
-	}
-	const candidate = value as {
-		kind?: string;
-		tables?: unknown;
-		enums?: unknown;
-	};
-	return (
-		candidate.kind === "schema" &&
-		typeof candidate.tables === "object" &&
-		(typeof candidate.enums === "object" || candidate.enums === undefined)
-	);
-}
-
-// ---------------------------------------------------------------------------
-// Relation builder helpers
-// ---------------------------------------------------------------------------
-
-function buildOneRelation(
-	targetTable: string,
-	fieldOrOptions?: string | RelationOneOptions,
-	options: RelationOneOptions = {},
-): OneRelationDefinition {
-	const field = typeof fieldOrOptions === "string" ? fieldOrOptions : undefined;
-	const mergedOptions =
-		typeof fieldOrOptions === "string" ? options : (fieldOrOptions ?? options);
-
-	return {
-		kind: "relation",
-		relation: "one",
-		targetTable,
-		field: mergedOptions.field ?? field,
-		referenceField: mergedOptions.referenceField,
-		fkType: mergedOptions.fkType,
-		sqlName: mergedOptions.sqlName,
-		notNull: mergedOptions.notNull,
-		nullable: mergedOptions.nullable,
-		onDelete: mergedOptions.onDelete,
-		onUpdate: mergedOptions.onUpdate,
-	};
-}
-
-function buildManyRelation(
-	targetTable: string,
-	fieldOrOptions?: string | RelationManyOptions,
-	options: RelationManyOptions = {},
-): ManyRelationDefinition {
-	const field = typeof fieldOrOptions === "string" ? fieldOrOptions : undefined;
-	const mergedOptions =
-		typeof fieldOrOptions === "string" ? options : (fieldOrOptions ?? options);
-
-	return {
-		kind: "relation",
-		relation: "many",
-		targetTable,
-		field: mergedOptions.field ?? field,
-		referenceField: mergedOptions.referenceField,
-		fkType: mergedOptions.fkType,
-		sqlName: mergedOptions.sqlName,
-		notNull: mergedOptions.notNull,
-		nullable: mergedOptions.nullable,
-		onDelete: mergedOptions.onDelete,
-		onUpdate: mergedOptions.onUpdate,
-	};
-}
-
-function buildManyToManyRelation(
-	targetTable: string,
-	options: RelationManyToManyOptions = {},
-): ManyToManyRelationDefinition {
-	return {
-		kind: "relation",
-		relation: "manyToMany",
-		targetTable,
-		referenceField: options.referenceField,
-		targetReferenceField: options.targetReferenceField,
-		junctionTable: options.junctionTable,
-		sourceField: options.sourceField,
-		targetField: options.targetField,
-		sourceSqlName: options.sourceSqlName,
-		targetSqlName: options.targetSqlName,
-		onDelete: options.onDelete,
-		onUpdate: options.onUpdate,
-	};
-}
-
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
-function columnBuilderToJsonShape(builder: ColumnBuilder): JsonShape {
-	const def = builder.toDefinition();
-	if (def.jsonShape) return def.jsonShape;
-	if (def.type === "int") return { kind: "number" };
-	if (def.type === "string") return { kind: "string" };
-	if (def.type === "boolean") return { kind: "boolean" };
-	if (def.type === "date") return { kind: "date" };
-	if (def.type === "enum" && def.enumValues) {
-		return {
-			kind: "string",
-		};
-	}
-	return { kind: "unknown" };
-}
-
-export const v = {
-	/** Define a reusable enum that can be referenced by multiple columns. */
-	defineEnum: <T extends string>(
-		name: string,
-		values: readonly T[],
-	): EnumBuilder<T> => defineEnum(name, values),
-
-	int: (options: ColumnBuilderOptions = {}) =>
-		new ColumnBuilder("int", options),
-	number: (options: ColumnBuilderOptions = {}) =>
-		new ColumnBuilder("int", options),
-	string: (options: ColumnBuilderOptions = {}) =>
-		new ColumnBuilder("string", options),
-	boolean: (options: ColumnBuilderOptions = {}) =>
-		new ColumnBuilder("boolean", options),
-	date: (options: ColumnBuilderOptions = {}) =>
-		new ColumnBuilder("date", options),
-
-	/**
-	 * UUID primary key column.
-	 * Stored as a string, marked as primary key and auto-populated with
-	 * `crypto.randomUUID()` at runtime (no SQL sequence).
-	 */
-	uuid: (options: ColumnBuilderOptions = {}) =>
-		new ColumnBuilder({
-			kind: "column",
-			type: "string",
-			sqlName: options.sqlName,
-			length: options.length ?? 36,
-			primaryKey: true,
-			notNull: true,
-			nullable: false,
-			uuidPrimaryKey: true,
-			runtimeDefaultFn: () => crypto.randomUUID(),
-		}),
-
-	/**
-	 * Enum column builder.
-	 * Pass an EnumBuilder (from v.defineEnum) or inline values.
-	 */
-	enum: <T extends string>(
-		valuesOrEnum: readonly T[] | EnumBuilder<T>,
-		options: ColumnBuilderOptions = {},
-	): ColumnBuilder => {
-		if (valuesOrEnum instanceof EnumBuilder) {
-			const def = valuesOrEnum.toDefinition();
-			return new ColumnBuilder("enum", {
-				...options,
-				enumValues: def.values,
-				enumRef: def.name,
-			});
-		}
-		return new ColumnBuilder("enum", {
-			...options,
-			enumValues: valuesOrEnum,
-		});
-	},
-
-	/**
-	 * Enum array column builder.
-	 * Stores multiple enum values in a single column.
-	 */
-	enumArray: <T extends string>(
-		valuesOrEnum: readonly T[] | EnumBuilder<T>,
-		options: ColumnBuilderOptions = {},
-	): ColumnBuilder => {
-		if (valuesOrEnum instanceof EnumBuilder) {
-			const def = valuesOrEnum.toDefinition();
-			return new ColumnBuilder("enum", {
-				...options,
-				enumValues: def.values,
-				enumRef: def.name,
-				isArray: true,
-			});
-		}
-		return new ColumnBuilder("enum", {
-			...options,
-			enumValues: valuesOrEnum,
-			isArray: true,
-		});
-	},
-
-	/**
-	 * JSON array column builder.
-	 * Stored as JSON text, auto-serialized on insert/query.
-	 * Use v.string(), v.number(), v.object(), or v.array() as the element type.
-	 * Example: v.array(v.string()), v.array(v.object({ name: v.string() }))
-	 */
-	array: (element: JsonArrayBuilder | ColumnBuilder): ColumnBuilder => {
-		if (element instanceof JsonArrayBuilder) {
-			return element.toColumnBuilder();
-		}
-		if (element instanceof ColumnBuilder) {
-			const def = element.toDefinition();
-			if (def.jsonShape) {
-				return new ColumnBuilder("json", { jsonShape: def.jsonShape });
-			}
-			const shape: JsonShape = {
-				kind: "array",
-				element: columnBuilderToJsonShape(element),
-			};
-			return new ColumnBuilder("json", { jsonShape: shape });
-		}
-		return new ColumnBuilder("json", { jsonShape: { kind: "unknown" } });
-	},
-
-	/**
-	 * JSON object column builder.
-	 * Stored as JSON text, auto-serialized on insert/query.
-	 * Pass a shape record: v.object({ name: v.string(), count: v.number() })
-	 */
-	object: <TShape extends Record<string, JsonShape | ColumnBuilder>>(
-		shape: TShape,
-	): ColumnBuilder => {
-		const resolved: Record<string, JsonShape> = {};
-		for (const [key, value] of Object.entries(shape)) {
-			if (value instanceof ColumnBuilder) {
-				resolved[key] = columnBuilderToJsonShape(value);
-			} else {
-				resolved[key] = value;
-			}
-		}
-		return new ColumnBuilder("json", {
-			jsonShape: { kind: "object", shape: resolved },
-		});
-	},
-
-	one: (
-		targetTable: string,
-		fieldOrOptions?: string | RelationOneOptions,
-		options: RelationOneOptions = {},
-	): OneRelationDefinition =>
-		buildOneRelation(targetTable, fieldOrOptions, options),
-
-	many: (
-		targetTable: string,
-		fieldOrOptions?: string | RelationManyOptions,
-		options: RelationManyOptions = {},
-	): ManyRelationDefinition =>
-		buildManyRelation(targetTable, fieldOrOptions, options),
-
-	manyToMany: (
-		targetTable: string,
-		options: RelationManyToManyOptions = {},
-	): ManyToManyRelationDefinition =>
-		buildManyToManyRelation(targetTable, options),
-};
+export type ColumnType = "int" | "string" | "boolean" | "date" | "enum" | "json";
+
+export type JsonShape =
+	| { kind: "array"; element: JsonShape }
+	| { kind: "object"; shape: Record<string, JsonShape> }
+	| { kind: "string" }
+	| { kind: "number" }
+	| { kind: "boolean" }
+	| { kind: "date" }
+	| { kind: "unknown" };
+
+export type EnumDefinition = {
+	kind: "enum";
+	name: string;
+	sqlName?: string;
+	values: readonly string[];
+};
+
+export type ColumnBuilderOptions = {
+	sqlName?: string;
+	length?: number;
+	enumValues?: readonly string[];
+	enumRef?: string;
+	isArray?: boolean;
+	jsonShape?: JsonShape;
+};
+
+export type PrimaryKeyOptions = {
+	autoIncrement?: boolean;
+};
+
+export type ForeignKeyAction =
+	| "cascade"
+	| "set null"
+	| "set default"
+	| "restrict"
+	| "no action";
+
+export type RelationOneOptions = {
+	referenceField?: string;
+	field?: string;
+	fkType?: ColumnType;
+	sqlName?: string;
+	notNull?: boolean;
+	nullable?: boolean;
+	onDelete?: ForeignKeyAction;
+	onUpdate?: ForeignKeyAction;
+};
+
+export type RelationManyOptions = {
+	referenceField?: string;
+	field?: string;
+	fkType?: ColumnType;
+	sqlName?: string;
+	notNull?: boolean;
+	nullable?: boolean;
+	onDelete?: ForeignKeyAction;
+	onUpdate?: ForeignKeyAction;
+};
+
+export type RelationManyToManyOptions = {
+	referenceField?: string;
+	targetReferenceField?: string;
+	junctionTable?: string;
+	sourceField?: string;
+	targetField?: string;
+	sourceSqlName?: string;
+	targetSqlName?: string;
+	onDelete?: ForeignKeyAction;
+	onUpdate?: ForeignKeyAction;
+};
+
+export type ColumnReference = {
+	table: string;
+	column: string;
+	onDelete?: ForeignKeyAction;
+	onUpdate?: ForeignKeyAction;
+};
+
+export type ColumnDefinition = {
+	kind: "column";
+	type: ColumnType;
+	sqlName?: string;
+	length?: number;
+	notNull?: boolean;
+	nullable?: boolean;
+	primaryKey?: boolean;
+	autoIncrement?: boolean;
+	/** When true the column stores a UUID generated at runtime (string type). */
+	uuidPrimaryKey?: boolean;
+	unique?: true | { name?: string };
+	index?: true | { name?: string };
+	sqlDefault?: unknown;
+	/** When true, the SQL column gets DEFAULT CURRENT_TIMESTAMP and runtime inserts use `new Date()`. */
+	nowDefault?: boolean;
+	runtimeDefaultFn?: () => unknown;
+	references?: ColumnReference;
+	/** For enum columns: the allowed values. */
+	enumValues?: readonly string[];
+	/** For enum columns: reference to a named enum definition. */
+	enumRef?: string;
+	/** When true, the column stores an array of enum values. */
+	isArray?: boolean;
+	/** For JSON columns: the shape of the stored data. */
+	jsonShape?: JsonShape;
+};
+
+export type OneRelationDefinition = {
+	kind: "relation";
+	relation: "one";
+	targetTable: string;
+	field?: string;
+	referenceField?: string;
+	fkType?: ColumnType;
+	sqlName?: string;
+	notNull?: boolean;
+	nullable?: boolean;
+	onDelete?: ForeignKeyAction;
+	onUpdate?: ForeignKeyAction;
+};
+
+export type ManyRelationDefinition = {
+	kind: "relation";
+	relation: "many";
+	targetTable: string;
+	field?: string;
+	referenceField?: string;
+	fkType?: ColumnType;
+	sqlName?: string;
+	notNull?: boolean;
+	nullable?: boolean;
+	onDelete?: ForeignKeyAction;
+	onUpdate?: ForeignKeyAction;
+};
+
+export type ManyToManyRelationDefinition = {
+	kind: "relation";
+	relation: "manyToMany";
+	targetTable: string;
+	referenceField?: string;
+	targetReferenceField?: string;
+	junctionTable?: string;
+	sourceField?: string;
+	targetField?: string;
+	sourceSqlName?: string;
+	targetSqlName?: string;
+	onDelete?: ForeignKeyAction;
+	onUpdate?: ForeignKeyAction;
+};
+
+export type RelationDefinition =
+	| OneRelationDefinition
+	| ManyRelationDefinition
+	| ManyToManyRelationDefinition;
+
+export type TableOptions = {
+	sqlName?: string;
+};
+
+export type TableShape = Record<string, ColumnBuilder | RelationDefinition>;
+
+export type TableDefinition = {
+	kind: "table";
+	sqlName?: string;
+	columns: Record<string, ColumnDefinition>;
+	relations: Record<string, RelationDefinition>;
+};
+
+export type SchemaDefinition = {
+	kind: "schema";
+	tables: Record<string, TableDefinition>;
+	enums: Record<string, EnumDefinition>;
+};
+
+export class EnumBuilder<T extends string> {
+	private def: EnumDefinition;
+
+	public constructor(name: string, values: readonly T[]) {
+		this.def = {
+			kind: "enum",
+			name,
+			values: values as readonly string[],
+		};
+	}
+
+	public sql(name: string): EnumBuilder<T> {
+		return new EnumBuilder<T>(name, this.def.values as readonly T[]);
+	}
+
+	public toDefinition(): EnumDefinition {
+		return { ...this.def };
+	}
+
+	public getValues(): readonly T[] {
+		return this.def.values as readonly T[];
+	}
+}
+
+export function defineEnum<T extends string>(
+	name: string,
+	values: readonly T[],
+): EnumBuilder<T> {
+	return new EnumBuilder(name, values);
+}
+
+export class JsonArrayBuilder {
+	private _element: JsonShape;
+
+	public constructor(element: JsonShape) {
+		this._element = element;
+	}
+
+	public get shape(): JsonShape {
+		return { kind: "array", element: this._element };
+	}
+
+	public toColumnBuilder(): ColumnBuilder {
+		return new ColumnBuilder("json", { jsonShape: this.shape });
+	}
+}
+
+export class JsonObjectBuilder<TShape extends Record<string, JsonShape>> {
+	private _shape: TShape;
+
+	public constructor(shape: TShape) {
+		this._shape = shape;
+	}
+
+	public get shape(): JsonShape {
+		return { kind: "object", shape: this._shape };
+	}
+
+	public toColumnBuilder(): ColumnBuilder {
+		return new ColumnBuilder("json", { jsonShape: this.shape });
+	}
+}
+
+export class ColumnBuilder {
+	private definition: ColumnDefinition;
+
+	public constructor(
+		typeOrDefinition: ColumnType | ColumnDefinition,
+		options: ColumnBuilderOptions = {},
+	) {
+		if (typeof typeOrDefinition === "string") {
+			this.definition = {
+				kind: "column",
+				type: typeOrDefinition,
+				sqlName: options.sqlName,
+				length: options.length,
+				enumValues: options.enumValues,
+				enumRef: options.enumRef,
+				jsonShape: options.jsonShape,
+			};
+			return;
+		}
+
+		this.definition = {
+			...typeOrDefinition,
+		};
+	}
+
+	private with(patch: Partial<ColumnDefinition>): ColumnBuilder {
+		return new ColumnBuilder({
+			...this.definition,
+			...patch,
+		});
+	}
+
+	public sql(name: string): ColumnBuilder {
+		return this.with({ sqlName: name });
+	}
+
+	public notNull(): ColumnBuilder {
+		return this.with({ notNull: true, nullable: false });
+	}
+
+	public nullable(): ColumnBuilder {
+		return this.with({ nullable: true, notNull: false });
+	}
+
+	public primaryKey(options: PrimaryKeyOptions = {}): ColumnBuilder {
+		return this.with({
+			primaryKey: true,
+			autoIncrement: options.autoIncrement ?? this.definition.autoIncrement,
+		});
+	}
+
+	public unique(name?: string): ColumnBuilder {
+		return this.with({ unique: name ? { name } : true });
+	}
+
+	public index(name?: string): ColumnBuilder {
+		return this.with({ index: name ? { name } : true });
+	}
+
+	public default(value: unknown): ColumnBuilder {
+		return this.with({ sqlDefault: value });
+	}
+
+	public defaultFn(fn: () => unknown): ColumnBuilder {
+		return this.with({ runtimeDefaultFn: fn });
+	}
+
+	/**
+	 * Shorthand for date columns that should default to the current timestamp.
+	 * Sets SQL `DEFAULT CURRENT_TIMESTAMP` (via `nowDefault`) and
+	 * a runtime default of `new Date()`.
+	 */
+	public defaultNow(): ColumnBuilder {
+		return this.with({
+			nowDefault: true,
+			runtimeDefaultFn: () => new Date(),
+		});
+	}
+
+	public references(
+		table: string,
+		column = "id",
+		actions: Pick<ColumnReference, "onDelete" | "onUpdate"> = {},
+	): ColumnBuilder {
+		return this.with({
+			references: {
+				table,
+				column,
+				onDelete: actions.onDelete,
+				onUpdate: actions.onUpdate,
+			},
+		});
+	}
+
+	/** Marks the column as an array (e.g., for enum arrays). */
+	public array(): ColumnBuilder {
+		return this.with({ isArray: true });
+	}
+
+	public toDefinition(): ColumnDefinition {
+		return { ...this.definition };
+	}
+}
+
+export function table(
+	shape: TableShape,
+	options: TableOptions = {},
+): TableDefinition {
+	const columns: Record<string, ColumnDefinition> = {};
+	const relations: Record<string, RelationDefinition> = {};
+
+	for (const [fieldName, value] of Object.entries(shape)) {
+		if (value instanceof ColumnBuilder) {
+			columns[fieldName] = value.toDefinition();
+			continue;
+		}
+
+		if (value.kind === "relation") {
+			relations[fieldName] = value;
+			continue;
+		}
+
+		throw new Error(
+			`Invalid table field '${fieldName}'. Use column builders or relation helpers.`,
+		);
+	}
+
+	return {
+		kind: "table",
+		sqlName: options.sqlName,
+		columns,
+		relations,
+	};
+}
+
+export type SchemaOptions = {
+	enums?: Record<string, EnumDefinition>;
+};
+
+export function schema(
+	tables: Record<string, TableDefinition>,
+	options: SchemaOptions = {},
+): SchemaDefinition {
+	return {
+		kind: "schema",
+		tables,
+		enums: options.enums ?? {},
+	};
+}
+
+export function isSchemaDefinition(value: unknown): value is SchemaDefinition {
+	if (typeof value !== "object" || value === null) {
+		return false;
+	}
+	const candidate = value as {
+		kind?: string;
+		tables?: unknown;
+		enums?: unknown;
+	};
+	return (
+		candidate.kind === "schema" &&
+		typeof candidate.tables === "object" &&
+		(typeof candidate.enums === "object" || candidate.enums === undefined)
+	);
+}
+
+// ---------------------------------------------------------------------------
+// Relation builder helpers
+// ---------------------------------------------------------------------------
+
+function buildOneRelation(
+	targetTable: string,
+	fieldOrOptions?: string | RelationOneOptions,
+	options: RelationOneOptions = {},
+): OneRelationDefinition {
+	const field = typeof fieldOrOptions === "string" ? fieldOrOptions : undefined;
+	const mergedOptions =
+		typeof fieldOrOptions === "string" ? options : (fieldOrOptions ?? options);
+
+	return {
+		kind: "relation",
+		relation: "one",
+		targetTable,
+		field: mergedOptions.field ?? field,
+		referenceField: mergedOptions.referenceField,
+		fkType: mergedOptions.fkType,
+		sqlName: mergedOptions.sqlName,
+		notNull: mergedOptions.notNull,
+		nullable: mergedOptions.nullable,
+		onDelete: mergedOptions.onDelete,
+		onUpdate: mergedOptions.onUpdate,
+	};
+}
+
+function buildManyRelation(
+	targetTable: string,
+	fieldOrOptions?: string | RelationManyOptions,
+	options: RelationManyOptions = {},
+): ManyRelationDefinition {
+	const field = typeof fieldOrOptions === "string" ? fieldOrOptions : undefined;
+	const mergedOptions =
+		typeof fieldOrOptions === "string" ? options : (fieldOrOptions ?? options);
+
+	return {
+		kind: "relation",
+		relation: "many",
+		targetTable,
+		field: mergedOptions.field ?? field,
+		referenceField: mergedOptions.referenceField,
+		fkType: mergedOptions.fkType,
+		sqlName: mergedOptions.sqlName,
+		notNull: mergedOptions.notNull,
+		nullable: mergedOptions.nullable,
+		onDelete: mergedOptions.onDelete,
+		onUpdate: mergedOptions.onUpdate,
+	};
+}
+
+function buildManyToManyRelation(
+	targetTable: string,
+	options: RelationManyToManyOptions = {},
+): ManyToManyRelationDefinition {
+	return {
+		kind: "relation",
+		relation: "manyToMany",
+		targetTable,
+		referenceField: options.referenceField,
+		targetReferenceField: options.targetReferenceField,
+		junctionTable: options.junctionTable,
+		sourceField: options.sourceField,
+		targetField: options.targetField,
+		sourceSqlName: options.sourceSqlName,
+		targetSqlName: options.targetSqlName,
+		onDelete: options.onDelete,
+		onUpdate: options.onUpdate,
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+function columnBuilderToJsonShape(builder: ColumnBuilder): JsonShape {
+	const def = builder.toDefinition();
+	if (def.jsonShape) return def.jsonShape;
+	if (def.type === "int") return { kind: "number" };
+	if (def.type === "string") return { kind: "string" };
+	if (def.type === "boolean") return { kind: "boolean" };
+	if (def.type === "date") return { kind: "date" };
+	if (def.type === "enum" && def.enumValues) {
+		return {
+			kind: "string",
+		};
+	}
+	return { kind: "unknown" };
+}
+
+export const v = {
+	/** Define a reusable enum that can be referenced by multiple columns. */
+	defineEnum: <T extends string>(
+		name: string,
+		values: readonly T[],
+	): EnumBuilder<T> => defineEnum(name, values),
+
+	int: (options: ColumnBuilderOptions = {}) =>
+		new ColumnBuilder("int", options),
+	number: (options: ColumnBuilderOptions = {}) =>
+		new ColumnBuilder("int", options),
+	string: (options: ColumnBuilderOptions = {}) =>
+		new ColumnBuilder("string", options),
+	boolean: (options: ColumnBuilderOptions = {}) =>
+		new ColumnBuilder("boolean", options),
+	date: (options: ColumnBuilderOptions = {}) =>
+		new ColumnBuilder("date", options),
+
+	/**
+	 * UUID primary key column.
+	 * Stored as a string, marked as primary key and auto-populated with
+	 * `crypto.randomUUID()` at runtime (no SQL sequence).
+	 */
+	uuid: (options: ColumnBuilderOptions = {}) =>
+		new ColumnBuilder({
+			kind: "column",
+			type: "string",
+			sqlName: options.sqlName,
+			length: options.length ?? 36,
+			primaryKey: true,
+			notNull: true,
+			nullable: false,
+			uuidPrimaryKey: true,
+			runtimeDefaultFn: () => crypto.randomUUID(),
+		}),
+
+	/**
+	 * Enum column builder.
+	 * Pass an EnumBuilder (from v.defineEnum) or inline values.
+	 */
+	enum: <T extends string>(
+		valuesOrEnum: readonly T[] | EnumBuilder<T>,
+		options: ColumnBuilderOptions = {},
+	): ColumnBuilder => {
+		if (valuesOrEnum instanceof EnumBuilder) {
+			const def = valuesOrEnum.toDefinition();
+			return new ColumnBuilder("enum", {
+				...options,
+				enumValues: def.values,
+				enumRef: def.name,
+			});
+		}
+		return new ColumnBuilder("enum", {
+			...options,
+			enumValues: valuesOrEnum,
+		});
+	},
+
+	/**
+	 * Enum array column builder.
+	 * Stores multiple enum values in a single column.
+	 */
+	enumArray: <T extends string>(
+		valuesOrEnum: readonly T[] | EnumBuilder<T>,
+		options: ColumnBuilderOptions = {},
+	): ColumnBuilder => {
+		if (valuesOrEnum instanceof EnumBuilder) {
+			const def = valuesOrEnum.toDefinition();
+			return new ColumnBuilder("enum", {
+				...options,
+				enumValues: def.values,
+				enumRef: def.name,
+				isArray: true,
+			});
+		}
+		return new ColumnBuilder("enum", {
+			...options,
+			enumValues: valuesOrEnum,
+			isArray: true,
+		});
+	},
+
+	/**
+	 * JSON array column builder.
+	 * Stored as JSON text, auto-serialized on insert/query.
+	 * Use v.string(), v.number(), v.object(), or v.array() as the element type.
+	 * Example: v.array(v.string()), v.array(v.object({ name: v.string() }))
+	 */
+	array: (element: JsonArrayBuilder | ColumnBuilder): ColumnBuilder => {
+		if (element instanceof JsonArrayBuilder) {
+			return element.toColumnBuilder();
+		}
+		if (element instanceof ColumnBuilder) {
+			const def = element.toDefinition();
+			if (def.jsonShape) {
+				return new ColumnBuilder("json", { jsonShape: { kind: "array", element: def.jsonShape } });
+			}
+			const shape: JsonShape = {
+				kind: "array",
+				element: columnBuilderToJsonShape(element),
+			};
+			return new ColumnBuilder("json", { jsonShape: shape });
+		}
+		return new ColumnBuilder("json", { jsonShape: { kind: "unknown" } });
+	},
+
+	/**
+	 * JSON object column builder.
+	 * Stored as JSON text, auto-serialized on insert/query.
+	 * Pass a shape record: v.object({ name: v.string(), count: v.number() })
+	 */
+	object: <TShape extends Record<string, JsonShape | ColumnBuilder>>(
+		shape: TShape,
+	): ColumnBuilder => {
+		const resolved: Record<string, JsonShape> = {};
+		for (const [key, value] of Object.entries(shape)) {
+			if (value instanceof ColumnBuilder) {
+				resolved[key] = columnBuilderToJsonShape(value);
+			} else {
+				resolved[key] = value;
+			}
+		}
+		return new ColumnBuilder("json", {
+			jsonShape: { kind: "object", shape: resolved },
+		});
+	},
+
+	one: (
+		targetTable: string,
+		fieldOrOptions?: string | RelationOneOptions,
+		options: RelationOneOptions = {},
+	): OneRelationDefinition =>
+		buildOneRelation(targetTable, fieldOrOptions, options),
+
+	many: (
+		targetTable: string,
+		fieldOrOptions?: string | RelationManyOptions,
+		options: RelationManyOptions = {},
+	): ManyRelationDefinition =>
+		buildManyRelation(targetTable, fieldOrOptions, options),
+
+	manyToMany: (
+		targetTable: string,
+		options: RelationManyToManyOptions = {},
+	): ManyToManyRelationDefinition =>
+		buildManyToManyRelation(targetTable, options),
+};