@vertz/db 0.2.0 → 0.2.1

package/dist/internals.d.ts

@@ -7,8 +7,9 @@ interface ColumnMetadata {
 	readonly unique: boolean;
 	readonly nullable: boolean;
 	readonly hasDefault: boolean;
-	readonly sensitive: boolean;
-	readonly hidden: boolean;
+	readonly _annotations: Record<string, true>;
+	readonly isReadOnly: boolean;
+	readonly isAutoUpdate: boolean;
 	readonly isTenant: boolean;
 	readonly references: {
 		readonly table: string;
@@ -23,6 +24,7 @@ interface ColumnMetadata {
 	readonly enumName?: string;
 	readonly enumValues?: readonly string[];
 	readonly validator?: JsonbValidator<unknown>;
+	readonly generate?: "cuid" | "uuid" | "nanoid";
 }
 /** Phantom symbol to carry the TypeScript type without a runtime value. */
 declare const PhantomType: unique symbol;
@@ -33,9 +35,12 @@ interface ColumnBuilder<
 	/** 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"> & {
+	primary(options?: {
+		generate?: "cuid" | "uuid" | "nanoid";
+	}): ColumnBuilder<TType, Omit<TMeta, "primary" | "hasDefault" | "generate"> & {
 		readonly primary: true;
 		readonly hasDefault: true;
+		readonly generate?: "cuid" | "uuid" | "nanoid";
 	}>;
 	unique(): ColumnBuilder<TType, Omit<TMeta, "unique"> & {
 		readonly unique: true;
@@ -47,11 +52,15 @@ interface ColumnBuilder<
 		readonly hasDefault: true;
 		readonly defaultValue: TType | "now";
 	}>;
-	sensitive(): ColumnBuilder<TType, Omit<TMeta, "sensitive"> & {
-		readonly sensitive: true;
+	is<TFlag extends string>(flag: TFlag): ColumnBuilder<TType, Omit<TMeta, "_annotations"> & {
+		readonly _annotations: TMeta["_annotations"] & { readonly [K in TFlag] : true };
 	}>;
-	hidden(): ColumnBuilder<TType, Omit<TMeta, "hidden"> & {
-		readonly hidden: true;
+	readOnly(): ColumnBuilder<TType, Omit<TMeta, "isReadOnly"> & {
+		readonly isReadOnly: true;
+	}>;
+	autoUpdate(): ColumnBuilder<TType, Omit<TMeta, "isAutoUpdate" | "isReadOnly"> & {
+		readonly isAutoUpdate: true;
+		readonly isReadOnly: true;
 	}>;
 	check(sql: string): ColumnBuilder<TType, Omit<TMeta, "check"> & {
 		readonly check: string;
@@ -66,26 +75,33 @@ interface ColumnBuilder<
 type InferColumnType<C> = C extends ColumnBuilder<infer T, ColumnMetadata> ? T : never;
 interface IndexDef {
 	readonly columns: readonly string[];
+	readonly name?: string;
+	readonly unique?: boolean;
 }
 /** 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`. */
+/** Keys of columns where a given metadata property 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). */
+/** Keys of columns where a given metadata property 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];
+/** Keys of columns that do NOT have ANY of the specified annotations in `_annotations`. */
+type ColumnKeysWithoutAnyAnnotation<
+	T extends ColumnRecord,
+	Annotations extends string
+> = { [K in keyof T] : T[K] extends ColumnBuilder<unknown, infer M> ? M["_annotations"] extends Record<Annotations, true> ? never : K : never }[keyof T];
 /**
 * $infer -- default SELECT type.
-* Excludes hidden columns. Includes everything else (including sensitive).
+* Excludes columns annotated 'hidden'. Includes everything else.
 */
-type Infer<T extends ColumnRecord> = { [K in ColumnKeysWhereNot<T, "hidden">] : InferColumnType<T[K]> };
+type Infer<T extends ColumnRecord> = { [K in ColumnKeysWithoutAnyAnnotation<T, "hidden">] : InferColumnType<T[K]> };
 /**
 * $infer_all -- all columns including hidden.
 */
@@ -101,21 +117,26 @@ type Insert<T extends ColumnRecord> = { [K in ColumnKeysWhereNot<T, "hasDefault"
 */
 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)
+* $response -- API response shape. Excludes columns annotated 'hidden'.
 */
-type NotSensitive<T extends ColumnRecord> = { [K in ColumnKeysWhereNot<T, "sensitive"> & ColumnKeysWhereNot<T, "hidden"> & keyof T] : InferColumnType<T[K]> };
+type Response<T extends ColumnRecord> = { [K in ColumnKeysWithoutAnyAnnotation<T, "hidden">] : InferColumnType<T[K]> };
 /**
-* $not_hidden -- excludes columns marked .hidden().
-* Same as $infer (excludes hidden, keeps sensitive).
+* $create_input -- API create input shape.
+* Excludes readOnly and primary key columns.
+* Columns with defaults are optional.
 */
-type NotHidden<T extends ColumnRecord> = { [K in ColumnKeysWhereNot<T, "hidden">] : InferColumnType<T[K]> };
+type ApiCreateInput<T extends ColumnRecord> = { [K in ColumnKeysWhereNot<T, "isReadOnly"> & ColumnKeysWhereNot<T, "primary"> & ColumnKeysWhereNot<T, "hasDefault"> & string] : InferColumnType<T[K]> } & { [K in ColumnKeysWhereNot<T, "isReadOnly"> & ColumnKeysWhereNot<T, "primary"> & ColumnKeysWhere<T, "hasDefault"> & string]? : InferColumnType<T[K]> };
+/**
+* $update_input -- API update input shape.
+* Excludes readOnly and primary key columns. All fields optional (partial update).
+*/
+type ApiUpdateInput<T extends ColumnRecord> = { [K in ColumnKeysWhereNot<T, "isReadOnly"> & ColumnKeysWhereNot<T, "primary"> & string]? : 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. */
+	/** Default SELECT type -- excludes columns annotated 'hidden'. */
 	readonly $infer: Infer<TColumns>;
 	/** All columns including hidden. */
 	readonly $infer_all: InferAll<TColumns>;
@@ -123,13 +144,60 @@ interface TableDef<TColumns extends ColumnRecord = ColumnRecord> {
 	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>;
+	/** API response shape — excludes columns annotated 'hidden'. */
+	readonly $response: Response<TColumns>;
+	/** API create input — excludes readOnly + PK; defaulted columns optional. */
+	readonly $create_input: ApiCreateInput<TColumns>;
+	/** API update input — excludes readOnly + PK; all fields optional. */
+	readonly $update_input: ApiUpdateInput<TColumns>;
 	/** Mark this table as shared / cross-tenant. */
 	shared(): TableDef<TColumns>;
 }
+interface ColumnSnapshot {
+	type: string;
+	nullable: boolean;
+	primary: boolean;
+	unique: boolean;
+	default?: string;
+	annotations?: string[];
+}
+interface IndexSnapshot {
+	columns: string[];
+	name?: string;
+	unique?: boolean;
+}
+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[]>;
+}
+/**
+* Abstraction over snapshot persistence.
+* Decouples the migration system from Node.js filesystem APIs.
+*/
+interface SnapshotStorage {
+	load(key: string): Promise<SchemaSnapshot | null>;
+	save(key: string, snapshot: SchemaSnapshot): Promise<void>;
+}
+/**
+* Node.js filesystem implementation of SnapshotStorage.
+* Uses node:fs/promises for file I/O and node:path for directory creation.
+*/
+declare class NodeSnapshotStorage implements SnapshotStorage {
+	load(path: string): Promise<SchemaSnapshot | null>;
+	save(path: string, snapshot: SchemaSnapshot): Promise<void>;
+}
 /**
 * Query executor — wraps raw SQL execution with error mapping.
 *
@@ -175,23 +243,20 @@ interface GroupByArgs {
 */
 declare function getColumnNames(table: TableDef<ColumnRecord>): string[];
 /**
-* Get column names excluding hidden columns (default SELECT behavior).
+* Get column names excluding 'hidden'-annotated columns (default SELECT behavior).
 */
 declare function getDefaultColumns(table: TableDef<ColumnRecord>): string[];
 /**
-* Get column names excluding sensitive AND hidden columns.
-*/
-declare function getNotSensitiveColumns(table: TableDef<ColumnRecord>): string[];
-/**
-* Get column names excluding hidden columns.
+* Get column names excluding columns with ANY of the specified annotations.
+* Always excludes 'hidden'-annotated columns in addition to the specified annotations.
 */
-declare function getNotHiddenColumns(table: TableDef<ColumnRecord>): string[];
+declare function getColumnsWithoutAnnotations(table: TableDef<ColumnRecord>, annotations: string[]): string[];
 /**
 * Resolve a select option to a list of column names.
 *
 * - undefined -> default columns (exclude hidden)
 * - { not: 'sensitive' } -> exclude sensitive + hidden
-* - { not: 'hidden' } -> exclude hidden
+* - { not: ['sensitive', 'patchable'] } -> exclude columns with any listed annotation + hidden
 * - { id: true, name: true } -> explicit pick
 */
 declare function resolveSelectColumns(table: TableDef<ColumnRecord>, select?: Record<string, unknown>): string[];
@@ -220,4 +285,4 @@ declare function mapRow<T>(row: Record<string, unknown>): T;
 * Convert an array of rows from snake_case to camelCase.
 */
 declare function mapRows<T>(rows: readonly Record<string, unknown>[]): T[];
-export { resolveSelectColumns, mapRows, mapRow, getTimestampColumns, getPrimaryKeyColumns, getNotSensitiveColumns, getNotHiddenColumns, getDefaultColumns, getColumnNames, executeQuery, QueryFn, GroupByArgs, ExecutorResult, CountArgs, AggregateArgs };
+export { resolveSelectColumns, mapRows, mapRow, getTimestampColumns, getPrimaryKeyColumns, getDefaultColumns, getColumnsWithoutAnnotations, getColumnNames, executeQuery, QueryFn, NodeSnapshotStorage, GroupByArgs, ExecutorResult, CountArgs, AggregateArgs };

package/dist/internals.js

@@ -1,25 +1,26 @@
 import {
   executeQuery,
   getColumnNames,
+  getColumnsWithoutAnnotations,
   getDefaultColumns,
-  getNotHiddenColumns,
-  getNotSensitiveColumns,
   getPrimaryKeyColumns,
   getTimestampColumns,
   mapRow,
   mapRows,
   resolveSelectColumns
-} from "./shared/chunk-xp022dyp.js";
-import"./shared/chunk-hrfdj0rr.js";
+} from "./shared/chunk-agyds4jw.js";
+import {
+  NodeSnapshotStorage
+} from "./shared/chunk-kb4tnn2k.js";
 export {
   resolveSelectColumns,
   mapRows,
   mapRow,
   getTimestampColumns,
   getPrimaryKeyColumns,
-  getNotSensitiveColumns,
-  getNotHiddenColumns,
   getDefaultColumns,
+  getColumnsWithoutAnnotations,
   getColumnNames,
-  executeQuery
+  executeQuery,
+  NodeSnapshotStorage
 };

package/dist/plugin/index.d.ts

@@ -33,7 +33,7 @@ interface QueryShape {
 * Same shape (table + operation + where keys + select keys + include keys)
 * always yields the same fingerprint, regardless of parameter values.
 */
-declare function fingerprint(query: QueryShape): string;
+declare function fingerprint(query: QueryShape): Promise<string>;
 /**
 * Context passed to plugin hooks.
 */

package/dist/plugin/index.js

@@ -1,3 +1,7 @@
+import {
+  sha256Hex
+} from "../shared/chunk-ssga2xea.js";
+
 // src/plugin/event-bus.ts
 function createEventBus() {
   const handlers = new Set;
@@ -16,8 +20,7 @@ function createEventBus() {
   };
 }
 // src/plugin/fingerprint.ts
-import { createHash } from "node:crypto";
-function fingerprint(query) {
+async function fingerprint(query) {
   const parts = [
     query.table,
     query.operation,
@@ -26,7 +29,8 @@ function fingerprint(query) {
     `i:${sortedKeys(query.include)}`
   ];
   const input = parts.join("|");
-  return createHash("sha256").update(input).digest("hex").slice(0, 16);
+  const hex = await sha256Hex(input);
+  return hex.slice(0, 16);
 }
 function sortedKeys(obj) {
   if (!obj)

package/dist/postgres/index.d.ts

@@ -0,0 +1,77 @@
+/**
+* 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>>;
+/**
+* Database driver interface.
+*
+* Provides a unified interface for different database backends
+* (PostgreSQL, SQLite/D1, etc.) with query and execute methods.
+*/
+interface DbDriver {
+	/**
+	* Execute a read query and return results.
+	*/
+	query<T = unknown>(sql: string, params?: unknown[]): Promise<T[]>;
+	/**
+	* Execute a write query and return affected row count.
+	*/
+	execute(sql: string, params?: unknown[]): Promise<{
+		rowsAffected: number;
+	}>;
+	/**
+	* Close the database connection.
+	*/
+	close(): Promise<void>;
+}
+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 PostgresDriver extends DbDriver {
+	/** The QueryFn adapter for use with createDb. */
+	readonly queryFn: QueryFn;
+	/** Check connection health with SELECT 1. */
+	isHealthy(): Promise<boolean>;
+}
+/**
+* Create a PostgreSQL driver from a connection URL and optional pool config.
+*
+* Note: Query routing (to replicas) is handled at the database.ts layer (createDb).
+* This driver provides a simple connection to a single PostgreSQL instance.
+*
+* @param url - PostgreSQL connection URL (e.g., postgres://user:pass@host:5432/db)
+* @param pool - Optional pool configuration
+* @returns A PostgresDriver with queryFn, close(), and isHealthy()
+*/
+declare function createPostgresDriver(url: string, pool?: PoolConfig): PostgresDriver;
+export { createPostgresDriver, PostgresDriver };

package/dist/postgres/index.js

@@ -0,0 +1,7 @@
+import {
+  createPostgresDriver
+} from "../shared/chunk-rqe0prft.js";
+import"../shared/chunk-j4kwq1gh.js";
+export {
+  createPostgresDriver
+};