@vertz/db 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,1346 @@
+/**
+* @vertz/db diagnostic utilities.
+*
+* Maps common error patterns to human-readable explanations.
+* Useful for developers and LLMs understanding type errors and runtime exceptions.
+*
+* @module
+*/
+interface DiagnosticResult {
+	/** Short identifier for the error pattern. */
+	readonly code: string;
+	/** Human-readable explanation of the error. */
+	readonly explanation: string;
+	/** Suggested fix or next step. */
+	readonly suggestion: string;
+}
+/**
+* Analyzes an error message and returns a human-readable diagnostic.
+*
+* Works with both TypeScript type error messages (from the branded types)
+* and runtime DbError messages.
+*
+* @param message - The error message string to analyze
+* @returns A DiagnosticResult if the pattern is recognized, or null
+*/
+declare function diagnoseError(message: string): DiagnosticResult | null;
+/**
+* Formats a diagnostic result as a multi-line string for display.
+*
+* @param diag - The diagnostic result to format
+* @returns A formatted string with the error code, explanation, and suggestion
+*/
+declare function formatDiagnostic(diag: DiagnosticResult): string;
+/**
+* Convenience: diagnose and format in one step.
+*
+* @param message - The error message to analyze
+* @returns Formatted diagnostic string, or a fallback message
+*/
+declare function explainError(message: string): string;
+interface JsonbValidator<T> {
+	parse(value: unknown): T;
+}
+interface ColumnMetadata {
+	readonly sqlType: string;
+	readonly primary: boolean;
+	readonly unique: boolean;
+	readonly nullable: boolean;
+	readonly hasDefault: boolean;
+	readonly sensitive: boolean;
+	readonly hidden: boolean;
+	readonly isTenant: boolean;
+	readonly references: {
+		readonly table: string;
+		readonly column: string;
+	} | null;
+	readonly check: string | null;
+	readonly defaultValue?: unknown;
+	readonly format?: string;
+	readonly length?: number;
+	readonly precision?: number;
+	readonly scale?: number;
+	readonly enumName?: string;
+	readonly enumValues?: readonly string[];
+	readonly validator?: JsonbValidator<unknown>;
+}
+/** Phantom symbol to carry the TypeScript type without a runtime value. */
+declare const PhantomType: unique symbol;
+interface ColumnBuilder<
+	TType,
+	TMeta extends ColumnMetadata = ColumnMetadata
+> {
+	/** Phantom field -- only exists at the type level for inference. Do not access at runtime. */
+	readonly [PhantomType]: TType;
+	readonly _meta: TMeta;
+	primary(): ColumnBuilder<TType, Omit<TMeta, "primary" | "hasDefault"> & {
+		readonly primary: true;
+		readonly hasDefault: true;
+	}>;
+	unique(): ColumnBuilder<TType, Omit<TMeta, "unique"> & {
+		readonly unique: true;
+	}>;
+	nullable(): ColumnBuilder<TType | null, Omit<TMeta, "nullable"> & {
+		readonly nullable: true;
+	}>;
+	default(value: TType | "now"): ColumnBuilder<TType, Omit<TMeta, "hasDefault"> & {
+		readonly hasDefault: true;
+		readonly defaultValue: TType | "now";
+	}>;
+	sensitive(): ColumnBuilder<TType, Omit<TMeta, "sensitive"> & {
+		readonly sensitive: true;
+	}>;
+	hidden(): ColumnBuilder<TType, Omit<TMeta, "hidden"> & {
+		readonly hidden: true;
+	}>;
+	check(sql: string): ColumnBuilder<TType, Omit<TMeta, "check"> & {
+		readonly check: string;
+	}>;
+	references(table: string, column?: string): ColumnBuilder<TType, Omit<TMeta, "references"> & {
+		readonly references: {
+			readonly table: string;
+			readonly column: string;
+		};
+	}>;
+}
+type InferColumnType<C> = C extends ColumnBuilder<infer T, ColumnMetadata> ? T : never;
+type DefaultMeta<TSqlType extends string> = {
+	readonly sqlType: TSqlType;
+	readonly primary: false;
+	readonly unique: false;
+	readonly nullable: false;
+	readonly hasDefault: false;
+	readonly sensitive: false;
+	readonly hidden: false;
+	readonly isTenant: false;
+	readonly references: null;
+	readonly check: null;
+};
+/** Metadata for varchar columns — carries the length constraint. */
+type VarcharMeta<TLength extends number> = DefaultMeta<"varchar"> & {
+	readonly length: TLength;
+};
+/** Metadata for decimal/numeric columns — carries precision and scale. */
+type DecimalMeta<
+	TPrecision extends number,
+	TScale extends number
+> = DefaultMeta<"decimal"> & {
+	readonly precision: TPrecision;
+	readonly scale: TScale;
+};
+/** Metadata for enum columns — carries the enum name and its values. */
+type EnumMeta<
+	TName extends string,
+	TValues extends readonly string[]
+> = DefaultMeta<"enum"> & {
+	readonly enumName: TName;
+	readonly enumValues: TValues;
+};
+/** Metadata for columns with a format constraint (e.g., email). */
+type FormatMeta<
+	TSqlType extends string,
+	TFormat extends string
+> = DefaultMeta<TSqlType> & {
+	readonly format: TFormat;
+};
+type SerialMeta = {
+	readonly sqlType: "serial";
+	readonly primary: false;
+	readonly unique: false;
+	readonly nullable: false;
+	readonly hasDefault: true;
+	readonly sensitive: false;
+	readonly hidden: false;
+	readonly isTenant: false;
+	readonly references: null;
+	readonly check: null;
+};
+type TenantMeta = {
+	readonly sqlType: "uuid";
+	readonly primary: false;
+	readonly unique: false;
+	readonly nullable: false;
+	readonly hasDefault: false;
+	readonly sensitive: false;
+	readonly hidden: false;
+	readonly isTenant: true;
+	readonly references: {
+		readonly table: string;
+		readonly column: string;
+	};
+	readonly check: null;
+};
+interface ThroughDef<TJoin extends TableDef<ColumnRecord> = TableDef<ColumnRecord>> {
+	readonly table: () => TJoin;
+	readonly thisKey: string;
+	readonly thatKey: string;
+}
+interface RelationDef<
+	TTarget extends TableDef<ColumnRecord> = TableDef<ColumnRecord>,
+	TType extends "one" | "many" = "one" | "many"
+> {
+	readonly _type: TType;
+	readonly _target: () => TTarget;
+	readonly _foreignKey: string | null;
+	readonly _through: ThroughDef | null;
+}
+interface ManyRelationDef<TTarget extends TableDef<ColumnRecord> = TableDef<ColumnRecord>> extends RelationDef<TTarget, "many"> {
+	through<TJoin extends TableDef<ColumnRecord>>(joinTable: () => TJoin, thisKey: string, thatKey: string): RelationDef<TTarget, "many">;
+}
+interface IndexDef {
+	readonly columns: readonly string[];
+}
+/** A record of column builders -- the shape passed to d.table(). */
+type ColumnRecord = Record<string, ColumnBuilder<unknown, ColumnMetadata>>;
+/** Extract the TypeScript type from every column in a record. */
+type InferColumns<T extends ColumnRecord> = { [K in keyof T] : InferColumnType<T[K]> };
+/** Keys of columns where a given metadata flag is `true`. */
+type ColumnKeysWhere<
+	T extends ColumnRecord,
+	Flag extends keyof ColumnMetadata
+> = { [K in keyof T] : T[K] extends ColumnBuilder<unknown, infer M> ? M extends Record<Flag, true> ? K : never : never }[keyof T];
+/** Keys of columns where a given metadata flag is NOT `true` (i.e., false). */
+type ColumnKeysWhereNot<
+	T extends ColumnRecord,
+	Flag extends keyof ColumnMetadata
+> = { [K in keyof T] : T[K] extends ColumnBuilder<unknown, infer M> ? M extends Record<Flag, true> ? never : K : never }[keyof T];
+/**
+* $infer -- default SELECT type.
+* Excludes hidden columns. Includes everything else (including sensitive).
+*/
+type Infer<T extends ColumnRecord> = { [K in ColumnKeysWhereNot<T, "hidden">] : InferColumnType<T[K]> };
+/**
+* $infer_all -- all columns including hidden.
+*/
+type InferAll<T extends ColumnRecord> = InferColumns<T>;
+/**
+* $insert -- write type. ALL columns included (visibility is read-side only).
+* Columns with hasDefault: true become optional.
+*/
+type Insert<T extends ColumnRecord> = { [K in ColumnKeysWhereNot<T, "hasDefault">] : InferColumnType<T[K]> } & { [K in ColumnKeysWhere<T, "hasDefault">]? : InferColumnType<T[K]> };
+/**
+* $update -- write type. ALL non-primary-key columns, all optional.
+* Primary key excluded (you don't update a PK).
+*/
+type Update<T extends ColumnRecord> = { [K in ColumnKeysWhereNot<T, "primary">]? : InferColumnType<T[K]> };
+/**
+* $not_sensitive -- excludes columns marked .sensitive() OR .hidden().
+* (hidden implies sensitive for read purposes)
+*/
+type NotSensitive<T extends ColumnRecord> = { [K in ColumnKeysWhereNot<T, "sensitive"> & ColumnKeysWhereNot<T, "hidden"> & keyof T] : InferColumnType<T[K]> };
+/**
+* $not_hidden -- excludes columns marked .hidden().
+* Same as $infer (excludes hidden, keeps sensitive).
+*/
+type NotHidden<T extends ColumnRecord> = { [K in ColumnKeysWhereNot<T, "hidden">] : InferColumnType<T[K]> };
+interface TableDef<TColumns extends ColumnRecord = ColumnRecord> {
+	readonly _name: string;
+	readonly _columns: TColumns;
+	readonly _indexes: readonly IndexDef[];
+	readonly _shared: boolean;
+	/** Default SELECT type -- excludes hidden columns. */
+	readonly $infer: Infer<TColumns>;
+	/** All columns including hidden. */
+	readonly $infer_all: InferAll<TColumns>;
+	/** Insert type -- defaulted columns optional. ALL columns included. */
+	readonly $insert: Insert<TColumns>;
+	/** Update type -- all non-PK columns optional. ALL columns included. */
+	readonly $update: Update<TColumns>;
+	/** Excludes sensitive and hidden columns. */
+	readonly $not_sensitive: NotSensitive<TColumns>;
+	/** Excludes hidden columns. */
+	readonly $not_hidden: NotHidden<TColumns>;
+	/** Mark this table as shared / cross-tenant. */
+	shared(): TableDef<TColumns>;
+}
+interface TableOptions {
+	relations?: Record<string, RelationDef>;
+	indexes?: IndexDef[];
+}
+interface ColumnSnapshot {
+	type: string;
+	nullable: boolean;
+	primary: boolean;
+	unique: boolean;
+	default?: string;
+	sensitive?: boolean;
+	hidden?: boolean;
+}
+interface IndexSnapshot {
+	columns: string[];
+}
+interface ForeignKeySnapshot {
+	column: string;
+	targetTable: string;
+	targetColumn: string;
+}
+interface TableSnapshot {
+	columns: Record<string, ColumnSnapshot>;
+	indexes: IndexSnapshot[];
+	foreignKeys: ForeignKeySnapshot[];
+	_metadata: Record<string, unknown>;
+}
+interface SchemaSnapshot {
+	version: 1;
+	tables: Record<string, TableSnapshot>;
+	enums: Record<string, string[]>;
+}
+/**
+* The query function type expected by the migration runner.
+*/
+type MigrationQueryFn = (sql: string, params: readonly unknown[]) => Promise<{
+	rows: readonly Record<string, unknown>[];
+	rowCount: number;
+}>;
+/**
+* Represents a migration file on disk.
+*/
+interface MigrationFile {
+	name: string;
+	sql: string;
+	timestamp: number;
+}
+/**
+* Result of applying (or dry-running) a migration.
+*/
+interface ApplyResult {
+	/** The migration name. */
+	name: string;
+	/** The SQL that was (or would be) executed. */
+	sql: string;
+	/** The computed checksum of the migration SQL. */
+	checksum: string;
+	/** Whether this was a dry run. */
+	dryRun: boolean;
+	/** The statements that were (or would be) executed, in order. */
+	statements: string[];
+}
+interface MigrateDeployOptions {
+	queryFn: MigrationQueryFn;
+	migrationFiles: MigrationFile[];
+	/** When true, return the SQL that would be executed without applying. */
+	dryRun?: boolean;
+}
+interface MigrateDeployResult {
+	applied: string[];
+	alreadyApplied: string[];
+	/** When dry-run is enabled, contains the details of each migration that would be applied. */
+	dryRun: boolean;
+	/** Detailed results for each migration that was (or would be) applied. */
+	migrations?: ApplyResult[];
+}
+/**
+* Apply all pending migrations in order.
+*
+* In dry-run mode, returns the SQL that would be executed without modifying the database.
+*/
+declare function migrateDeploy(options: MigrateDeployOptions): Promise<MigrateDeployResult>;
+interface RenameSuggestion {
+	table: string;
+	oldColumn: string;
+	newColumn: string;
+	confidence: number;
+}
+interface MigrateDevOptions {
+	queryFn: MigrationQueryFn;
+	currentSnapshot: SchemaSnapshot;
+	previousSnapshot: SchemaSnapshot;
+	migrationName: string;
+	existingFiles: string[];
+	migrationsDir: string;
+	writeFile: (path: string, content: string) => Promise<void>;
+	dryRun: boolean;
+}
+interface MigrateDevResult {
+	migrationFile: string;
+	sql: string;
+	appliedAt?: Date;
+	dryRun: boolean;
+	renames?: RenameSuggestion[];
+	snapshot: SchemaSnapshot;
+}
+/**
+* Generate a migration from schema diff, optionally apply it.
+*
+* In dry-run mode, generates SQL and returns it WITHOUT applying or writing files.
+*/
+declare function migrateDev(options: MigrateDevOptions): Promise<MigrateDevResult>;
+interface PushOptions {
+	queryFn: MigrationQueryFn;
+	currentSnapshot: SchemaSnapshot;
+	previousSnapshot: SchemaSnapshot;
+}
+interface PushResult {
+	sql: string;
+	tablesAffected: string[];
+}
+/**
+* Push schema changes directly to the database without creating a migration file.
+*/
+declare function push(options: PushOptions): Promise<PushResult>;
+interface MigrateStatusOptions {
+	queryFn: MigrationQueryFn;
+	migrationFiles: MigrationFile[];
+}
+interface MigrationInfo {
+	name: string;
+	checksum: string;
+	appliedAt: Date;
+}
+interface MigrateStatusResult {
+	applied: MigrationInfo[];
+	pending: string[];
+}
+/**
+* Report the status of migrations: which are applied and which are pending.
+*/
+declare function migrateStatus(options: MigrateStatusOptions): Promise<MigrateStatusResult>;
+/**
+* Query executor — wraps raw SQL execution with error mapping.
+*
+* Takes a query function (from the database driver) and wraps it to:
+* 1. Execute parameterized SQL
+* 2. Map PG errors to typed DbError subclasses
+* 3. Return typed QueryResult
+*/
+interface ExecutorResult<T> {
+	readonly rows: readonly T[];
+	readonly rowCount: number;
+}
+type QueryFn = <T>(sql: string, params: readonly unknown[]) => Promise<ExecutorResult<T>>;
+/** Operators available for comparable types (number, string, Date, bigint). */
+interface ComparisonOperators<T> {
+	readonly eq?: T;
+	readonly ne?: T;
+	readonly gt?: T;
+	readonly gte?: T;
+	readonly lt?: T;
+	readonly lte?: T;
+	readonly in?: readonly T[];
+	readonly notIn?: readonly T[];
+}
+/** Additional operators for string columns. */
+interface StringOperators {
+	readonly contains?: string;
+	readonly startsWith?: string;
+	readonly endsWith?: string;
+}
+/** The `isNull` operator — only available for nullable columns. */
+interface NullOperator {
+	readonly isNull?: boolean;
+}
+/**
+* Resolves the filter operators for a single column based on its inferred type
+* and nullable metadata.
+*
+* - All types get comparison + in/notIn
+* - String types additionally get contains, startsWith, endsWith
+* - Nullable columns additionally get isNull
+*
+* Uses [T] extends [string] to prevent union distribution -- ensures that a
+* union like 'admin' | 'editor' keeps the full union in each operator slot.
+*/
+type ColumnFilterOperators<
+	TType,
+	TNullable extends boolean
+> = ([TType] extends [string] ? ComparisonOperators<TType> & StringOperators : ComparisonOperators<TType>) & (TNullable extends true ? NullOperator : unknown);
+/** Determine whether a column is nullable from its metadata. */
+type IsNullable<C> = C extends ColumnBuilder<unknown, infer M> ? M extends {
+	readonly nullable: true;
+} ? true : false : false;
+/**
+* FilterType<TColumns> — typed where clause.
+*
+* Each key maps to either:
+* - A direct value (shorthand for `{ eq: value }`)
+* - An object with typed filter operators
+*/
+type FilterType<TColumns extends ColumnRecord> = { [K in keyof TColumns]? : InferColumnType<TColumns[K]> | ColumnFilterOperators<InferColumnType<TColumns[K]>, IsNullable<TColumns[K]>> };
+type OrderByType<TColumns extends ColumnRecord> = { [K in keyof TColumns]? : "asc" | "desc" };
+/**
+* SelectOption<TColumns> — the `select` field in query options.
+*
+* Either:
+* - `{ not: 'sensitive' | 'hidden' }` — exclude columns by visibility category
+* - `{ [column]: true }` — explicitly pick columns
+*
+* The two forms are mutually exclusive, enforced via `never` mapped keys.
+*/
+type SelectOption<TColumns extends ColumnRecord> = ({
+	readonly not: "sensitive" | "hidden";
+} & { readonly [K in keyof TColumns]? : never }) | ({ readonly [K in keyof TColumns]? : true } & {
+	readonly not?: never;
+});
+/** Keys of columns where a given metadata flag is NOT `true`. */
+type ColumnKeysWhereNot2<
+	T extends ColumnRecord,
+	Flag extends keyof ColumnMetadata
+> = { [K in keyof T] : T[K] extends ColumnBuilder<unknown, infer M> ? M extends Record<Flag, true> ? never : K : never }[keyof T];
+/** Extract selected keys from a select map (keys set to `true`). */
+type SelectedKeys<
+	TColumns extends ColumnRecord,
+	TSelect
+> = { [K in keyof TSelect] : K extends keyof TColumns ? (TSelect[K] extends true ? K : never) : never }[keyof TSelect];
+/**
+* SelectNarrow<TColumns, TSelect> — applies a select clause to narrow the result type.
+*
+* - `{ not: 'sensitive' }` → excludes sensitive AND hidden columns
+* - `{ not: 'hidden' }` → excludes hidden columns
+* - `{ id: true, name: true }` → picks only id and name
+* - `undefined` → default: excludes hidden columns ($infer behavior)
+*/
+type SelectNarrow<
+	TColumns extends ColumnRecord,
+	TSelect
+> = TSelect extends {
+	not: "sensitive";
+} ? { [K in ColumnKeysWhereNot2<TColumns, "sensitive"> & ColumnKeysWhereNot2<TColumns, "hidden"> & keyof TColumns] : InferColumnType<TColumns[K]> } : TSelect extends {
+	not: "hidden";
+} ? { [K in ColumnKeysWhereNot2<TColumns, "hidden"> & keyof TColumns] : InferColumnType<TColumns[K]> } : TSelect extends Record<string, true | undefined> ? { [K in SelectedKeys<TColumns, TSelect> & keyof TColumns] : InferColumnType<TColumns[K]> } : { [K in ColumnKeysWhereNot2<TColumns, "hidden"> & keyof TColumns] : InferColumnType<TColumns[K]> };
+/** Relations record — maps relation names to RelationDef. */
+type RelationsRecord = Record<string, RelationDef>;
+/**
+* The shape of include options for a given relations record.
+* Each relation can be:
+* - `true` — include with default fields
+* - An object with optional `select` clause for narrowing
+*/
+type IncludeOption<TRelations extends RelationsRecord> = { [K in keyof TRelations]? : true | {
+	select?: Record<string, true>;
+} };
+/** Extract the target table from a RelationDef. */
+type RelationTarget<R> = R extends RelationDef<infer TTarget, "one" | "many"> ? TTarget : never;
+/** Extract the relation type ('one' | 'many') from a RelationDef. */
+type RelationType<R> = R extends RelationDef<TableDef<ColumnRecord>, infer TType> ? TType : never;
+/**
+* Resolve a single included relation.
+* - 'one' relations return a single object
+* - 'many' relations return an array
+* - When a `select` sub-clause is provided, the result is narrowed
+*/
+type ResolveOneInclude<
+	R extends RelationDef,
+	TIncludeValue,
+	_Depth extends readonly unknown[] = []
+> = TIncludeValue extends {
+	select: infer TSubSelect;
+} ? RelationTarget<R> extends TableDef<infer TCols> ? SelectNarrow<TCols, TSubSelect> : never : RelationTarget<R> extends TableDef<infer TCols> ? SelectNarrow<TCols, undefined> : never;
+/**
+* IncludeResolve<TRelations, TInclude, Depth> — resolves all included relations.
+*
+* Depth is tracked using a tuple counter. Default cap = 2.
+*/
+type IncludeResolve<
+	TRelations extends RelationsRecord,
+	TInclude,
+	_Depth extends readonly unknown[] = []
+> = _Depth["length"] extends 3 ? unknown : { [K in keyof TInclude as K extends keyof TRelations ? TInclude[K] extends false | undefined ? never : K : never] : K extends keyof TRelations ? RelationType<TRelations[K]> extends "many" ? ResolveOneInclude<TRelations[K], TInclude[K], _Depth>[] : ResolveOneInclude<TRelations[K], TInclude[K], _Depth> : never };
+/** Query options shape used by FindResult. */
+interface FindOptions<
+	TColumns extends ColumnRecord = ColumnRecord,
+	TRelations extends RelationsRecord = RelationsRecord
+> {
+	select?: SelectOption<TColumns>;
+	include?: IncludeOption<TRelations>;
+	where?: FilterType<TColumns>;
+	orderBy?: OrderByType<TColumns>;
+}
+/**
+* FindResult<TTable, TOptions> — the return type of a typed query.
+*
+* Combines:
+* - SelectNarrow for column selection
+* - IncludeResolve for relation includes
+*
+* TOptions is structurally typed (not constrained to FindOptions) so that
+* literal option objects flow through without widening.
+*/
+type FindResult<
+	TTable extends TableDef<ColumnRecord>,
+	TOptions = unknown,
+	TRelations extends RelationsRecord = RelationsRecord
+> = TTable extends TableDef<infer TColumns> ? SelectNarrow<TColumns, TOptions extends {
+	select: infer S;
+} ? S : undefined> & (TOptions extends {
+	include: infer I;
+} ? IncludeResolve<TRelations, I> : unknown) : never;
+/**
+* InsertInput<TTable> — standalone insert type utility.
+* Makes columns with defaults optional, all others required.
+*/
+type InsertInput<TTable extends TableDef<ColumnRecord>> = TTable["$insert"];
+/**
+* UpdateInput<TTable> — standalone update type utility.
+* All non-PK columns, all optional.
+*/
+type UpdateInput<TTable extends TableDef<ColumnRecord>> = TTable["$update"];
+/** A table entry in the database registry, pairing a table with its relations. */
+interface TableEntry<
+	TTable extends TableDef<ColumnRecord> = TableDef<ColumnRecord>,
+	TRelations extends RelationsRecord = RelationsRecord
+> {
+	readonly table: TTable;
+	readonly relations: TRelations;
+}
+/**
+* Database<TTables> — type that carries the full table registry.
+*
+* Used as the foundation for typed query methods (implemented in later tickets).
+* Provides type-safe access to table definitions and their relations.
+*/
+interface Database<TTables extends Record<string, TableEntry> = Record<string, TableEntry>> {
+	readonly _tables: TTables;
+}
+/**
+* SQL tagged template literal and escape hatch.
+*
+* Provides a safe, composable way to write raw SQL with automatic parameterization.
+*
+* Usage:
+*   const result = sql`SELECT * FROM users WHERE id = ${userId}`;
+*   // { sql: 'SELECT * FROM users WHERE id = $1', params: [userId] }
+*
+*   const col = sql.raw('created_at');
+*   const result = sql`SELECT ${col} FROM users`;
+*   // { sql: 'SELECT created_at FROM users', params: [] }
+*
+*   const where = sql`WHERE active = ${true}`;
+*   const query = sql`SELECT * FROM users ${where}`;
+*   // { sql: 'SELECT * FROM users WHERE active = $1', params: [true] }
+*/
+/**
+* A fragment of SQL with parameterized values.
+*
+* The `_tag` property is used to identify SqlFragment instances during
+* template composition, distinguishing them from regular interpolated values.
+*/
+interface SqlFragment {
+	readonly _tag: "SqlFragment";
+	readonly sql: string;
+	readonly params: readonly unknown[];
+}
+interface TenantGraph {
+	/** The tenant root table name (e.g., "organizations"). Null if no tenant columns exist. */
+	readonly root: string | null;
+	/** Tables with a direct d.tenant() column pointing to the root. */
+	readonly directlyScoped: readonly string[];
+	/** Tables reachable from directly scoped tables via .references() chains. */
+	readonly indirectlyScoped: readonly string[];
+	/** Tables marked with .shared(). */
+	readonly shared: readonly string[];
+}
+interface TableRegistryEntry {
+	readonly table: TableDef<ColumnRecord>;
+	readonly relations: Record<string, unknown>;
+}
+type TableRegistry = Record<string, TableRegistryEntry>;
+/**
+* Analyzes a table registry to compute the tenant scoping graph.
+*
+* 1. Finds the tenant root — the table that tenant columns point to.
+* 2. Classifies tables as directly scoped (has d.tenant()), indirectly scoped
+*    (references a scoped table via .references()), or shared (.shared()).
+* 3. Tables that are none of the above are unscoped — the caller should
+*    log a notice for those.
+*/
+declare function computeTenantGraph(registry: TableRegistry): TenantGraph;
+interface PoolConfig {
+	/** Maximum number of connections in the pool. */
+	readonly max?: number;
+	/**
+	* Idle timeout in milliseconds before a connection is closed.
+	* Defaults to 30000 (30 seconds) if not specified, preventing
+	* idle connections from staying open indefinitely.
+	*/
+	readonly idleTimeout?: number;
+	/** Connection timeout in milliseconds. */
+	readonly connectionTimeout?: number;
+	/**
+	* Health check timeout in milliseconds.
+	* Used by isHealthy() to prevent hanging on degraded databases.
+	* Defaults to 5000 (5 seconds) if not specified.
+	*/
+	readonly healthCheckTimeout?: number;
+	/**
+	* Read replica URLs for query routing.
+	* Read-only queries (SELECT) can be routed to replicas for load balancing.
+	* The primary URL is always used for writes (INSERT, UPDATE, DELETE).
+	*/
+	readonly replicas?: readonly string[];
+}
+interface CreateDbOptions<TTables extends Record<string, TableEntry>> {
+	/** PostgreSQL connection URL. */
+	readonly url: string;
+	/** Table registry mapping logical names to table definitions + relations. */
+	readonly tables: TTables;
+	/** Connection pool configuration. */
+	readonly pool?: PoolConfig;
+	/** Column name casing strategy. */
+	readonly casing?: "snake_case" | "camelCase";
+	/** Log function for notices (e.g., unscoped table warnings). */
+	readonly log?: (message: string) => void;
+	/**
+	* Raw query function injected by the driver layer.
+	* If not provided, query methods will throw.
+	* @internal — primarily for testing with PGlite.
+	*/
+	readonly _queryFn?: QueryFn;
+}
+interface QueryResult<T> {
+	readonly rows: readonly T[];
+	readonly rowCount: number;
+}
+/** Extract the TableDef from a TableEntry. */
+type EntryTable<TEntry extends TableEntry> = TEntry["table"];
+/** Extract the relations record from a TableEntry. */
+type EntryRelations<TEntry extends TableEntry> = TEntry["relations"];
+/** Extract columns from a TableEntry's table. */
+type EntryColumns<TEntry extends TableEntry> = EntryTable<TEntry>["_columns"];
+/** Options for get / getOrThrow — typed per-table. */
+type TypedGetOptions<TEntry extends TableEntry> = {
+	readonly where?: FilterType<EntryColumns<TEntry>>;
+	readonly select?: SelectOption<EntryColumns<TEntry>>;
+	readonly orderBy?: OrderByType<EntryColumns<TEntry>>;
+	readonly include?: IncludeOption<EntryRelations<TEntry>>;
+};
+/** Options for list / listAndCount — typed per-table. */
+type TypedListOptions<TEntry extends TableEntry> = {
+	readonly where?: FilterType<EntryColumns<TEntry>>;
+	readonly select?: SelectOption<EntryColumns<TEntry>>;
+	readonly orderBy?: OrderByType<EntryColumns<TEntry>>;
+	readonly limit?: number;
+	readonly offset?: number;
+	/** Cursor object: column-value pairs marking the position to paginate from. */
+	readonly cursor?: Record<string, unknown>;
+	/** Number of rows to take (used with cursor). Aliases `limit` when cursor is present. */
+	readonly take?: number;
+	readonly include?: IncludeOption<EntryRelations<TEntry>>;
+};
+/** Options for create — typed per-table. */
+type TypedCreateOptions<TEntry extends TableEntry> = {
+	readonly data: InsertInput<EntryTable<TEntry>>;
+	readonly select?: SelectOption<EntryColumns<TEntry>>;
+};
+/** Options for createManyAndReturn — typed per-table. */
+type TypedCreateManyAndReturnOptions<TEntry extends TableEntry> = {
+	readonly data: readonly InsertInput<EntryTable<TEntry>>[];
+	readonly select?: SelectOption<EntryColumns<TEntry>>;
+};
+/** Options for createMany — typed per-table. */
+type TypedCreateManyOptions<TEntry extends TableEntry> = {
+	readonly data: readonly InsertInput<EntryTable<TEntry>>[];
+};
+/** Options for update — typed per-table. */
+type TypedUpdateOptions<TEntry extends TableEntry> = {
+	readonly where: FilterType<EntryColumns<TEntry>>;
+	readonly data: UpdateInput<EntryTable<TEntry>>;
+	readonly select?: SelectOption<EntryColumns<TEntry>>;
+};
+/** Options for updateMany — typed per-table. */
+type TypedUpdateManyOptions<TEntry extends TableEntry> = {
+	readonly where: FilterType<EntryColumns<TEntry>>;
+	readonly data: UpdateInput<EntryTable<TEntry>>;
+};
+/** Options for upsert — typed per-table. */
+type TypedUpsertOptions<TEntry extends TableEntry> = {
+	readonly where: FilterType<EntryColumns<TEntry>>;
+	readonly create: InsertInput<EntryTable<TEntry>>;
+	readonly update: UpdateInput<EntryTable<TEntry>>;
+	readonly select?: SelectOption<EntryColumns<TEntry>>;
+};
+/** Options for delete — typed per-table. */
+type TypedDeleteOptions<TEntry extends TableEntry> = {
+	readonly where: FilterType<EntryColumns<TEntry>>;
+	readonly select?: SelectOption<EntryColumns<TEntry>>;
+};
+/** Options for deleteMany — typed per-table. */
+type TypedDeleteManyOptions<TEntry extends TableEntry> = {
+	readonly where: FilterType<EntryColumns<TEntry>>;
+};
+/** Options for count — typed per-table. */
+type TypedCountOptions<TEntry extends TableEntry> = {
+	readonly where?: FilterType<EntryColumns<TEntry>>;
+};
+interface DatabaseInstance<TTables extends Record<string, TableEntry>> {
+	/** The table registry for type-safe access. */
+	readonly _tables: TTables;
+	/** The computed tenant scoping graph. */
+	readonly $tenantGraph: TenantGraph;
+	/**
+	* Execute a raw SQL query via the sql tagged template.
+	*/
+	query<T = Record<string, unknown>>(fragment: SqlFragment): Promise<QueryResult<T>>;
+	/**
+	* Close all pool connections.
+	*/
+	close(): Promise<void>;
+	/**
+	* Check if the database connection is healthy.
+	*/
+	isHealthy(): Promise<boolean>;
+	/**
+	* Get a single row or null.
+	*/
+	get<
+		TName extends keyof TTables & string,
+		TOptions extends TypedGetOptions<TTables[TName]>
+	>(table: TName, options?: TOptions): Promise<FindResult<EntryTable<TTables[TName]>, TOptions, EntryRelations<TTables[TName]>> | null>;
+	/**
+	* Get a single row or throw NotFoundError.
+	*/
+	getOrThrow<
+		TName extends keyof TTables & string,
+		TOptions extends TypedGetOptions<TTables[TName]>
+	>(table: TName, options?: TOptions): Promise<FindResult<EntryTable<TTables[TName]>, TOptions, EntryRelations<TTables[TName]>>>;
+	/**
+	* List multiple rows.
+	*/
+	list<
+		TName extends keyof TTables & string,
+		TOptions extends TypedListOptions<TTables[TName]>
+	>(table: TName, options?: TOptions): Promise<FindResult<EntryTable<TTables[TName]>, TOptions, EntryRelations<TTables[TName]>>[]>;
+	/**
+	* List multiple rows with total count.
+	*/
+	listAndCount<
+		TName extends keyof TTables & string,
+		TOptions extends TypedListOptions<TTables[TName]>
+	>(table: TName, options?: TOptions): Promise<{
+		data: FindResult<EntryTable<TTables[TName]>, TOptions, EntryRelations<TTables[TName]>>[];
+		total: number;
+	}>;
+	/** @deprecated Use `get` instead */
+	findOne: DatabaseInstance<TTables>["get"];
+	/** @deprecated Use `getOrThrow` instead */
+	findOneOrThrow: DatabaseInstance<TTables>["getOrThrow"];
+	/** @deprecated Use `list` instead */
+	findMany: DatabaseInstance<TTables>["list"];
+	/** @deprecated Use `listAndCount` instead */
+	findManyAndCount: DatabaseInstance<TTables>["listAndCount"];
+	/**
+	* Insert a single row and return it.
+	*/
+	create<
+		TName extends keyof TTables & string,
+		TOptions extends TypedCreateOptions<TTables[TName]>
+	>(table: TName, options: TOptions): Promise<FindResult<EntryTable<TTables[TName]>, TOptions, EntryRelations<TTables[TName]>>>;
+	/**
+	* Insert multiple rows and return the count.
+	*/
+	createMany<TName extends keyof TTables & string>(table: TName, options: TypedCreateManyOptions<TTables[TName]>): Promise<{
+		count: number;
+	}>;
+	/**
+	* Insert multiple rows and return them.
+	*/
+	createManyAndReturn<
+		TName extends keyof TTables & string,
+		TOptions extends TypedCreateManyAndReturnOptions<TTables[TName]>
+	>(table: TName, options: TOptions): Promise<FindResult<EntryTable<TTables[TName]>, TOptions, EntryRelations<TTables[TName]>>[]>;
+	/**
+	* Update matching rows and return the first. Throws NotFoundError if none match.
+	*/
+	update<
+		TName extends keyof TTables & string,
+		TOptions extends TypedUpdateOptions<TTables[TName]>
+	>(table: TName, options: TOptions): Promise<FindResult<EntryTable<TTables[TName]>, TOptions, EntryRelations<TTables[TName]>>>;
+	/**
+	* Update matching rows and return the count.
+	*/
+	updateMany<TName extends keyof TTables & string>(table: TName, options: TypedUpdateManyOptions<TTables[TName]>): Promise<{
+		count: number;
+	}>;
+	/**
+	* Insert or update a row.
+	*/
+	upsert<
+		TName extends keyof TTables & string,
+		TOptions extends TypedUpsertOptions<TTables[TName]>
+	>(table: TName, options: TOptions): Promise<FindResult<EntryTable<TTables[TName]>, TOptions, EntryRelations<TTables[TName]>>>;
+	/**
+	* Delete a matching row and return it. Throws NotFoundError if none match.
+	*/
+	delete<
+		TName extends keyof TTables & string,
+		TOptions extends TypedDeleteOptions<TTables[TName]>
+	>(table: TName, options: TOptions): Promise<FindResult<EntryTable<TTables[TName]>, TOptions, EntryRelations<TTables[TName]>>>;
+	/**
+	* Delete matching rows and return the count.
+	*/
+	deleteMany<TName extends keyof TTables & string>(table: TName, options: TypedDeleteManyOptions<TTables[TName]>): Promise<{
+		count: number;
+	}>;
+	/**
+	* Count rows matching an optional filter.
+	*/
+	count<TName extends keyof TTables & string>(table: TName, options?: TypedCountOptions<TTables[TName]>): Promise<number>;
+	/**
+	* Run aggregation functions on a table.
+	*/
+	aggregate<TName extends keyof TTables & string>(table: TName, options: exports_aggregate.AggregateArgs): Promise<Record<string, unknown>>;
+	/**
+	* Group rows by columns and apply aggregation functions.
+	*/
+	groupBy<TName extends keyof TTables & string>(table: TName, options: exports_aggregate.GroupByArgs): Promise<Record<string, unknown>[]>;
+}
+/**
+* Creates a typed Database instance.
+*
+* Computes the tenant graph at creation time from d.tenant() metadata,
+* traversing references to find indirect tenant paths.
+* Logs notices for tables without tenant paths and not .shared().
+*
+* When `url` is provided and `_queryFn` is NOT provided, creates a real
+* postgres connection using the `postgres` package (porsager/postgres).
+* The `_queryFn` escape hatch still works for testing with PGlite.
+*
+* **Timestamp coercion:** The postgres driver automatically converts string
+* values matching ISO 8601 timestamp patterns to `Date` objects. This applies
+* to all columns, not just declared timestamp columns. If you store
+* timestamp-formatted strings in plain text columns, they will be coerced
+* to `Date` objects. See the postgres-driver source for details.
+*
+* **Connection pool defaults:** When no `pool.idleTimeout` is specified,
+* idle connections are closed after 30 seconds. Set `idleTimeout` explicitly
+* to override (value in milliseconds, e.g., `60000` for 60s).
+*/
+declare function createDb<TTables extends Record<string, TableEntry>>(options: CreateDbOptions<TTables>): DatabaseInstance<TTables>;
+interface EnumSchemaLike<T extends readonly string[]> {
+	readonly values: T;
+}
+declare const d: {
+	uuid(): ColumnBuilder<string, DefaultMeta<"uuid">>;
+	text(): ColumnBuilder<string, DefaultMeta<"text">>;
+	varchar<TLength extends number>(length: TLength): ColumnBuilder<string, VarcharMeta<TLength>>;
+	email(): ColumnBuilder<string, FormatMeta<"text", "email">>;
+	boolean(): ColumnBuilder<boolean, DefaultMeta<"boolean">>;
+	integer(): ColumnBuilder<number, DefaultMeta<"integer">>;
+	bigint(): ColumnBuilder<bigint, DefaultMeta<"bigint">>;
+	decimal<
+		TPrecision extends number,
+		TScale extends number
+	>(precision: TPrecision, scale: TScale): ColumnBuilder<string, DecimalMeta<TPrecision, TScale>>;
+	real(): ColumnBuilder<number, DefaultMeta<"real">>;
+	doublePrecision(): ColumnBuilder<number, DefaultMeta<"double precision">>;
+	serial(): ColumnBuilder<number, SerialMeta>;
+	timestamp(): ColumnBuilder<Date, DefaultMeta<"timestamp with time zone">>;
+	date(): ColumnBuilder<string, DefaultMeta<"date">>;
+	time(): ColumnBuilder<string, DefaultMeta<"time">>;
+	jsonb<T = unknown>(opts?: {
+		validator: JsonbValidator<T>;
+	}): ColumnBuilder<T, DefaultMeta<"jsonb">>;
+	textArray(): ColumnBuilder<string[], DefaultMeta<"text[]">>;
+	integerArray(): ColumnBuilder<number[], DefaultMeta<"integer[]">>;
+	enum<
+		TName extends string,
+		const TValues extends readonly string[]
+	>(name: TName, values: TValues): ColumnBuilder<TValues[number], EnumMeta<TName, TValues>>;
+	enum<
+		TName extends string,
+		const TValues extends readonly [string, ...string[]]
+	>(name: TName, schema: EnumSchemaLike<TValues>): ColumnBuilder<TValues[number], EnumMeta<TName, TValues>>;
+	tenant(targetTable: TableDef<ColumnRecord>): ColumnBuilder<string, TenantMeta>;
+	table<TColumns extends ColumnRecord>(name: string, columns: TColumns, options?: TableOptions): TableDef<TColumns>;
+	index(columns: string | string[]): IndexDef;
+	ref: {
+		one<TTarget extends TableDef<ColumnRecord>>(target: () => TTarget, foreignKey: string): RelationDef<TTarget, "one">;
+		many<TTarget extends TableDef<ColumnRecord>>(target: () => TTarget, foreignKey: string): RelationDef<TTarget, "many">;
+		many<TTarget extends TableDef<ColumnRecord>>(target: () => TTarget): ManyRelationDef<TTarget>;
+	};
+	entry<TTable extends TableDef<ColumnRecord>>(table: TTable): TableEntry<TTable, {}>;
+	entry<
+		TTable extends TableDef<ColumnRecord>,
+		TRelations extends Record<string, RelationDef>
+	>(table: TTable, relations: TRelations): TableEntry<TTable, TRelations>;
+};
+interface DbErrorJson {
+	readonly error: string;
+	readonly code: string;
+	readonly message: string;
+	readonly table?: string;
+	readonly column?: string;
+}
+declare abstract class DbError extends Error {
+	abstract readonly code: string;
+	/** Raw PostgreSQL SQLSTATE code, if applicable. */
+	readonly pgCode?: string | undefined;
+	readonly table?: string | undefined;
+	readonly query?: string | undefined;
+	constructor(message: string);
+	toJSON(): DbErrorJson;
+}
+interface UniqueConstraintErrorOptions {
+	readonly table: string;
+	readonly column: string;
+	readonly value?: string;
+	readonly query?: string;
+}
+declare class UniqueConstraintError extends DbError {
+	readonly code: "UNIQUE_VIOLATION";
+	readonly pgCode: "23505";
+	readonly table: string;
+	readonly query: string | undefined;
+	readonly column: string;
+	readonly value: string | undefined;
+	constructor(options: UniqueConstraintErrorOptions);
+	toJSON(): DbErrorJson;
+}
+interface ForeignKeyErrorOptions {
+	readonly table: string;
+	readonly constraint: string;
+	readonly detail?: string;
+	readonly query?: string;
+}
+declare class ForeignKeyError extends DbError {
+	readonly code: "FOREIGN_KEY_VIOLATION";
+	readonly pgCode: "23503";
+	readonly table: string;
+	readonly query: string | undefined;
+	readonly constraint: string;
+	readonly detail: string | undefined;
+	constructor(options: ForeignKeyErrorOptions);
+	toJSON(): DbErrorJson;
+}
+interface NotNullErrorOptions {
+	readonly table: string;
+	readonly column: string;
+	readonly query?: string;
+}
+declare class NotNullError extends DbError {
+	readonly code: "NOT_NULL_VIOLATION";
+	readonly pgCode: "23502";
+	readonly table: string;
+	readonly query: string | undefined;
+	readonly column: string;
+	constructor(options: NotNullErrorOptions);
+	toJSON(): DbErrorJson;
+}
+interface CheckConstraintErrorOptions {
+	readonly table: string;
+	readonly constraint: string;
+	readonly query?: string;
+}
+declare class CheckConstraintError extends DbError {
+	readonly code: "CHECK_VIOLATION";
+	readonly pgCode: "23514";
+	readonly table: string;
+	readonly query: string | undefined;
+	readonly constraint: string;
+	constructor(options: CheckConstraintErrorOptions);
+	toJSON(): DbErrorJson;
+}
+declare class NotFoundError extends DbError {
+	readonly code: "NOT_FOUND";
+	readonly table: string;
+	readonly query: string | undefined;
+	constructor(table: string, query?: string);
+	toJSON(): DbErrorJson;
+}
+declare class ConnectionError extends DbError {
+	readonly code: string;
+	constructor(message: string);
+}
+declare class ConnectionPoolExhaustedError extends ConnectionError {
+	readonly code: "POOL_EXHAUSTED";
+	constructor(poolSize: number);
+}
+/**
+* Maps semantic error names to their corresponding PostgreSQL SQLSTATE codes.
+*
+* Usage in switch statements:
+* ```ts
+* switch (error.code) {
+*   case 'UNIQUE_VIOLATION':   // ...
+*   case 'FOREIGN_KEY_VIOLATION': // ...
+* }
+* ```
+*
+* Reverse lookup (semantic name -> PG code):
+* ```ts
+* DbErrorCode.UNIQUE_VIOLATION // '23505'
+* ```
+*/
+declare const DbErrorCode: {
+	readonly UNIQUE_VIOLATION: "23505";
+	readonly FOREIGN_KEY_VIOLATION: "23503";
+	readonly NOT_NULL_VIOLATION: "23502";
+	readonly CHECK_VIOLATION: "23514";
+	readonly EXCLUSION_VIOLATION: "23P01";
+	readonly SERIALIZATION_FAILURE: "40001";
+	readonly DEADLOCK_DETECTED: "40P01";
+	readonly CONNECTION_EXCEPTION: "08000";
+	readonly CONNECTION_DOES_NOT_EXIST: "08003";
+	readonly CONNECTION_FAILURE: "08006";
+	readonly NOT_FOUND: "NOT_FOUND";
+	readonly CONNECTION_ERROR: "CONNECTION_ERROR";
+	readonly POOL_EXHAUSTED: "POOL_EXHAUSTED";
+};
+/** Union of all semantic error code keys (e.g., `'UNIQUE_VIOLATION' | 'FOREIGN_KEY_VIOLATION' | ...`). */
+type DbErrorCodeName = keyof typeof DbErrorCode;
+/** Union of all raw PG error code values (e.g., `'23505' | '23503' | ...`). */
+type DbErrorCodeValue = (typeof DbErrorCode)[keyof typeof DbErrorCode];
+/**
+* Reverse map: raw PG code -> semantic name.
+* Built at module load time from DbErrorCode.
+*/
+declare const PgCodeToName: Readonly<Record<string, DbErrorCodeName | undefined>>;
+/**
+* Look up the semantic name for a raw PG error code.
+* Returns the key (e.g., `'UNIQUE_VIOLATION'`) or `undefined` if unmapped.
+*/
+declare function resolveErrorCode(pgCode: string): DbErrorCodeName | undefined;
+interface HttpErrorResponse {
+	readonly status: number;
+	readonly body: DbErrorJson;
+}
+/**
+* Maps a DbError to an HTTP error response with the appropriate status code.
+*
+* - UniqueConstraintError  -> 409 Conflict
+* - NotFoundError          -> 404 Not Found
+* - ForeignKeyError        -> 422 Unprocessable Entity
+* - NotNullError           -> 422 Unprocessable Entity
+* - CheckConstraintError   -> 422 Unprocessable Entity
+* - ConnectionError        -> 503 Service Unavailable
+* - Unknown DbError        -> 500 Internal Server Error
+*/
+declare function dbErrorToHttpError(error: DbError): HttpErrorResponse;
+interface PgErrorInput {
+	readonly code: string;
+	readonly message: string;
+	readonly table?: string;
+	readonly column?: string;
+	readonly constraint?: string;
+	readonly detail?: string;
+}
+/**
+* Maps a raw PostgreSQL error object to a typed DbError subclass.
+*
+* Extracts structured metadata (column, constraint, value) from the
+* PG error's `detail` and `message` fields.
+*/
+declare function parsePgError(pgError: PgErrorInput, query?: string): DbError;
+/**
+* Extracts the string column keys from a TableDef's _columns record.
+* Used to constrain FK arguments at the type level.
+*/
+type ColumnKeys<T extends TableDef<ColumnRecord>> = T extends TableDef<infer C> ? Extract<keyof C, string> : never;
+/**
+* A ref builder scoped to a specific source table within a registry.
+*
+* - `one()` validates: target name is a registry key, FK is a column of the SOURCE table
+* - `many()` validates: target name is a registry key, FK is a column of the TARGET table
+*/
+interface TypedRef<
+	TTables extends Record<string, TableDef<ColumnRecord>>,
+	TSourceTable extends TableDef<ColumnRecord>
+> {
+	/** belongsTo — FK lives on the source table */
+	one<
+		TTargetName extends Extract<keyof TTables, string>,
+		TFK extends ColumnKeys<TSourceTable>
+	>(target: TTargetName, foreignKey: TFK): RelationDef<TTables[TTargetName], "one">;
+	/** hasMany — FK lives on the target table */
+	many<
+		TTargetName extends Extract<keyof TTables, string>,
+		TFK extends ColumnKeys<TTables[TTargetName]>
+	>(target: TTargetName, foreignKey: TFK): RelationDef<TTables[TTargetName], "many">;
+}
+/**
+* An object keyed by table name where each value is a TypedRef scoped
+* to that table as the source. This enables `ref.posts.one('users', 'authorId')`
+* where TypeScript knows 'authorId' must be a column of `posts`.
+*/
+type PerTableRefFactory<TTables extends Record<string, TableDef<ColumnRecord>>> = { [K in Extract<keyof TTables, string>] : TypedRef<TTables, TTables[K]> };
+/**
+* Maps each table key to a TableEntry, merging the table with its relations
+* from the callback (or empty relations if the table was omitted).
+*/
+type RegistryOutput<
+	TTables extends Record<string, TableDef<ColumnRecord>>,
+	TRelMap extends { [K in keyof TTables]? : Record<string, RelationDef> }
+> = { [K in keyof TTables] : TableEntry<TTables[K], K extends keyof TRelMap ? TRelMap[K] extends Record<string, RelationDef> ? TRelMap[K] : {} : {}> };
+/**
+* Creates a typed table registry with compile-time validated relations.
+*
+* Tables without relations in the callback are auto-wrapped with `{ table, relations: {} }`.
+* The `ref` parameter is keyed by table name — use `ref.posts.one('users', 'authorId')`
+* to get compile-time validation that 'users' is a registry key and 'authorId' is a column
+* of the `posts` table.
+*
+* @example
+* ```typescript
+* const tables = createRegistry(
+*   { users, posts, comments },
+*   (ref) => ({
+*     posts: {
+*       author: ref.posts.one('users', 'authorId'),
+*       comments: ref.posts.many('comments', 'postId'),
+*     },
+*     comments: {
+*       post: ref.comments.one('posts', 'postId'),
+*       author: ref.comments.one('users', 'authorId'),
+*     },
+*   }),
+* );
+* ```
+*/
+declare function createRegistry<
+	TTables extends Record<string, TableDef<ColumnRecord>>,
+	TRelMap extends { [K in keyof TTables]? : Record<string, RelationDef> }
+>(tables: TTables, relationsCallback: (ref: PerTableRefFactory<TTables>) => TRelMap): RegistryOutput<TTables, TRelMap>;
+/**
+* Shared enum registry — define enums once, reuse across tables.
+*
+* @example
+* ```ts
+* const enums = createEnumRegistry({
+*   status: ['active', 'inactive', 'pending'],
+*   role: ['admin', 'editor', 'viewer'],
+* } as const);
+*
+* const orders = d.table('orders', {
+*   status: d.enum('status', enums.status),
+* });
+* const users = d.table('users', {
+*   role: d.enum('role', enums.role),
+* });
+* ```
+*/
+/** A registered enum entry with name and values accessible for d.enum(). */
+interface RegisteredEnum<TValues extends readonly string[]> {
+	/** The enum name (same as the registry key). */
+	readonly name: string;
+	/** The enum values — compatible with d.enum()'s EnumSchemaLike interface. */
+	readonly values: TValues;
+}
+type EnumRegistry<T extends Record<string, readonly string[]>> = { readonly [K in keyof T] : RegisteredEnum<T[K]> };
+/**
+* Creates a shared enum registry from a map of enum names to their values.
+* The returned object can be passed directly to `d.enum(name, enums.myEnum)`.
+*/
+declare function createEnumRegistry<T extends Record<string, readonly string[]>>(definitions: T): EnumRegistry<T>;
+/**
+* Branded error types for readable compiler messages.
+*
+* When developers pass invalid column names, relation names, or filter types,
+* TypeScript produces raw generic expansion errors that are hard to read.
+* These branded types produce clear, actionable error messages instead.
+*
+* @module
+*/
+/**
+* Produced when a column name in select/where/orderBy does not exist on the table.
+*
+* Example:
+*   `ERROR: Column 'nonExistent' does not exist on table 'users'.`
+*/
+type InvalidColumn<
+	K extends string,
+	Table extends string
+> = `ERROR: Column '${K}' does not exist on table '${Table}'.`;
+/**
+* Produced when a filter value has the wrong type.
+*
+* Example:
+*   `ERROR: Filter on 'age' expects type 'number', got 'string'.`
+*/
+type InvalidFilterType<
+	Col extends string,
+	Expected extends string,
+	Got extends string
+> = `ERROR: Filter on '${Col}' expects type '${Expected}', got '${Got}'.`;
+/**
+* Produced when an include name does not match any declared relation.
+*
+* Example:
+*   `ERROR: Relation 'bogus' does not exist. Available relations: author, comments.`
+*/
+type InvalidRelation<
+	K extends string,
+	Available extends string
+> = `ERROR: Relation '${K}' does not exist. Available relations: ${Available}.`;
+/**
+* Produced when a select option mixes `not` with explicit field selection.
+*
+* Example:
+*   `ERROR: Cannot combine 'not' with explicit field selection in select.`
+*/
+type MixedSelectError = "ERROR: Cannot combine 'not' with explicit field selection in select.";
+/**
+* ValidateKeys<TKeys, TAllowed, TTable> — maps invalid keys to branded error messages.
+*
+* For each key K in TKeys:
+* - If K extends TAllowed, keep the original type
+* - Otherwise, produce an InvalidColumn error message
+*/
+type ValidateKeys<
+	TKeys extends Record<string, unknown>,
+	TAllowed extends string,
+	TTable extends string
+> = { [K in keyof TKeys] : K extends TAllowed ? TKeys[K] : InvalidColumn<K & string, TTable> };
+/**
+* StrictKeys<TRecord, TAllowed, TTable> — validates that all keys in TRecord
+* are in the TAllowed union, producing branded errors for invalid keys.
+*/
+type StrictKeys<
+	TRecord,
+	TAllowed extends string,
+	TTable extends string
+> = TRecord extends Record<string, unknown> ? { [K in keyof TRecord] : K extends TAllowed ? TRecord[K] : InvalidColumn<K & string, TTable> } : TRecord;
+/**
+* Type generation for DB client codegen.
+*
+* This module generates TypeScript types from domain definitions.
+*/
+interface DomainField {
+	type: "string" | "number" | "boolean" | "date" | "json" | "uuid" | "enum";
+	primary?: boolean;
+	required?: boolean;
+	references?: string;
+	enumName?: string;
+	enumValues?: string[];
+}
+interface DomainRelation {
+	type: "belongsTo" | "hasMany";
+	target: string;
+	foreignKey: string;
+}
+interface DomainDefinition {
+	name: string;
+	fields: Record<string, DomainField>;
+	relations?: Record<string, DomainRelation>;
+}
+/**
+* Generate TypeScript types from a domain definition.
+* This function should generate:
+* - Entity interface (e.g., interface User { ... })
+* - Create input type (required fields only)
+* - Update input type (all fields optional)
+* - Where/filter type
+* - OrderBy type
+* - CRUD method signatures
+*/
+declare function generateTypes(domain: DomainDefinition): string;
+/**
+* Generate the typed database client from domain definitions.
+* This function should generate:
+* - A db object with entity accessors
+* - Each entity has: list, get, create, update, delete methods
+* - Typed filter/where parameters
+* - Relation accessors
+*/
+declare function generateClient(domains: DomainDefinition[]): string;
+/**
+* Define a domain for DB client codegen.
+* This creates a domain definition that can be used to generate types and client.
+*/
+declare function defineDomain(name: string, config: {
+	fields: Record<string, Omit<DomainField, "type"> & {
+		type: DomainField["type"];
+	}>;
+	relations?: Record<string, Omit<DomainRelation, "type"> & {
+		type: DomainRelation["type"];
+	}>;
+}): DomainDefinition;
+export { resolveErrorCode, push, parsePgError, migrateStatus, migrateDev, migrateDeploy, generateTypes, generateClient, formatDiagnostic, explainError, diagnoseError, defineDomain, dbErrorToHttpError, d, createRegistry, createEnumRegistry, createDb, computeTenantGraph, VarcharMeta, ValidateKeys, UpdateInput, UniqueConstraintErrorOptions, UniqueConstraintError, TenantMeta, TenantGraph, TableEntry, TableDef, StrictKeys, SelectOption, SelectNarrow, RenameSuggestion, RelationDef, RegisteredEnum, QueryResult, PushResult, PushOptions, PoolConfig, PgErrorInput, PgCodeToName, OrderByType, NotNullErrorOptions, NotNullError, NotFoundError, MixedSelectError, MigrationInfo, MigrateStatusResult, MigrateStatusOptions, MigrateDevResult, MigrateDevOptions, MigrateDeployResult, MigrateDeployOptions, JsonbValidator, InvalidRelation, InvalidFilterType, InvalidColumn, InsertInput, InferColumnType, IndexDef, IncludeResolve, IncludeOption, HttpErrorResponse, FormatMeta, ForeignKeyErrorOptions, ForeignKeyError, FindResult, FindOptions, FilterType, EnumMeta, DomainRelation, DomainField, DomainDefinition, DiagnosticResult, DecimalMeta, DbErrorJson, DbErrorCodeValue, DbErrorCodeName, DbErrorCode, DbError, DatabaseInstance, Database, CreateDbOptions, ConnectionPoolExhaustedError, ConnectionError, ColumnMetadata, ColumnBuilder, CheckConstraintErrorOptions, CheckConstraintError };