@vertz/db 0.2.0 → 0.2.1

package/dist/sql/index.d.ts

@@ -5,33 +5,69 @@
 * to PostgreSQL column names (snake_case) and vice versa.
 */
 /**
+* Override map for custom casing conversions.
+* Keys are camelCase, values are snake_case.
+* Example: { 'oAuth': 'oauth', 'userID': 'user_id' }
+*/
+type CasingOverrides = Record<string, string>;
+/**
 * Convert a camelCase string to snake_case.
 *
 * Handles acronyms correctly:
 * - "parseJSON" -> "parse_json"
 * - "getHTTPSUrl" -> "get_https_url"
 * - "htmlParser" -> "html_parser"
+*
+* @param str - The camelCase string to convert
+* @param overrides - Optional map of camelCase -> snake_case overrides that take precedence
 */
-declare function camelToSnake(str: string): string;
+declare function camelToSnake(str: string, overrides?: CasingOverrides): string;
 /**
 * Convert a snake_case string to camelCase.
 *
 * - "first_name" -> "firstName"
 * - "created_at_timestamp" -> "createdAtTimestamp"
-*/
-declare function snakeToCamel(str: string): string;
-/**
-* DELETE statement builder.
 *
-* Generates parameterized DELETE queries with support for:
-* - WHERE clause via the where builder
-* - RETURNING clause with column aliasing
-* - camelCase -> snake_case column conversion
-*/
+* @param str - The snake_case string to convert
+* @param overrides - Optional map of camelCase -> snake_case overrides (reverse lookup)
+*/
+declare function snakeToCamel(str: string, overrides?: CasingOverrides): string;
+interface Dialect {
+	/** Dialect name. */
+	readonly name: "postgres" | "sqlite";
+	/**
+	* Parameter placeholder: $1, $2 (postgres) or ? (sqlite).
+	* @param index - 1-based parameter index
+	*/
+	param(index: number): string;
+	/** SQL function for current timestamp. */
+	now(): string;
+	/**
+	* Map a vertz column sqlType to the dialect's SQL type.
+	* @param sqlType - The generic sqlType from column metadata
+	* @param meta - Additional metadata (enum values, length, precision)
+	*/
+	mapColumnType(sqlType: string, meta?: ColumnTypeMeta): string;
+	/** Whether the dialect supports RETURNING clause. */
+	readonly supportsReturning: boolean;
+	/** Whether the dialect supports array operators (@>, <@, &&). */
+	readonly supportsArrayOps: boolean;
+	/** Whether the dialect supports JSONB path operators (->>, ->). */
+	readonly supportsJsonbPath: boolean;
+}
+interface ColumnTypeMeta {
+	readonly enumName?: string;
+	readonly enumValues?: readonly string[];
+	readonly length?: number;
+	readonly precision?: number;
+	readonly scale?: number;
+}
 interface DeleteOptions {
 	readonly table: string;
 	readonly where?: Record<string, unknown>;
 	readonly returning?: "*" | readonly string[];
+	/** SQL dialect to use. Defaults to postgres. */
+	readonly dialect?: Dialect;
 }
 interface DeleteResult {
 	readonly sql: string;
@@ -40,17 +76,7 @@ interface DeleteResult {
 /**
 * Build a DELETE statement from the given options.
 */
-declare function buildDelete(options: DeleteOptions): DeleteResult;
-/**
-* INSERT statement builder.
-*
-* Generates parameterized INSERT queries with support for:
-* - Single row and batch (multi-row VALUES) inserts
-* - RETURNING clause with column aliasing
-* - ON CONFLICT (upsert) — DO NOTHING or DO UPDATE SET
-* - camelCase -> snake_case column conversion
-* - "now" sentinel handling for timestamp defaults
-*/
+declare function buildDelete(options: DeleteOptions, dialect?: Dialect): DeleteResult;
 interface OnConflictOptions {
 	readonly columns: readonly string[];
 	readonly action: "nothing" | "update";
@@ -65,6 +91,8 @@ interface InsertOptions {
 	readonly onConflict?: OnConflictOptions;
 	/** Column names (camelCase) that should use NOW() instead of a parameterized value when the value is "now". */
 	readonly nowColumns?: readonly string[];
+	/** SQL dialect to use. Defaults to postgres. */
+	readonly dialect?: Dialect;
 }
 interface InsertResult {
 	readonly sql: string;
@@ -73,18 +101,7 @@ interface InsertResult {
 /**
 * Build an INSERT statement from the given options.
 */
-declare function buildInsert(options: InsertOptions): InsertResult;
-/**
-* SELECT statement builder.
-*
-* Generates parameterized SELECT queries with support for:
-* - Column selection with camelCase -> snake_case conversion and aliasing
-* - WHERE clause via the where builder
-* - ORDER BY with direction
-* - LIMIT / OFFSET pagination (parameterized)
-* - Cursor-based pagination (cursor + take)
-* - COUNT(*) OVER() for listAndCount
-*/
+declare function buildInsert(options: InsertOptions, dialect?: Dialect): InsertResult;
 interface SelectOptions {
 	readonly table: string;
 	readonly columns?: readonly string[];
@@ -97,6 +114,10 @@ interface SelectOptions {
 	readonly cursor?: Record<string, unknown>;
 	/** Number of rows to take (used with cursor). Aliases `limit` when cursor is present. */
 	readonly take?: number;
+	/** Custom casing overrides for camelCase -> snake_case conversion. */
+	readonly casingOverrides?: CasingOverrides;
+	/** SQL dialect to use. Defaults to postgres. */
+	readonly dialect?: Dialect;
 }
 interface SelectResult {
 	readonly sql: string;
@@ -105,7 +126,7 @@ interface SelectResult {
 /**
 * Build a SELECT statement from the given options.
 */
-declare function buildSelect(options: SelectOptions): SelectResult;
+declare function buildSelect(options: SelectOptions, dialect?: Dialect): SelectResult;
 /**
 * SQL tagged template literal and escape hatch.
 *
@@ -151,16 +172,6 @@ declare const sql: {
 	(strings: TemplateStringsArray, ...values: unknown[]): SqlFragment;
 	raw(value: string): SqlFragment;
 };
-/**
-* UPDATE statement builder.
-*
-* Generates parameterized UPDATE queries with support for:
-* - SET clause from a data object
-* - WHERE clause via the where builder
-* - RETURNING clause with column aliasing
-* - camelCase -> snake_case column conversion
-* - "now" sentinel handling for timestamp defaults
-*/
 interface UpdateOptions {
 	readonly table: string;
 	readonly data: Record<string, unknown>;
@@ -168,6 +179,8 @@ interface UpdateOptions {
 	readonly returning?: "*" | readonly string[];
 	/** Column names (camelCase) that should use NOW() instead of a parameterized value when the value is "now". */
 	readonly nowColumns?: readonly string[];
+	/** SQL dialect to use. Defaults to postgres. */
+	readonly dialect?: Dialect;
 }
 interface UpdateResult {
 	readonly sql: string;
@@ -176,22 +189,7 @@ interface UpdateResult {
 /**
 * Build an UPDATE statement from the given options.
 */
-declare function buildUpdate(options: UpdateOptions): UpdateResult;
-/**
-* WHERE clause builder with parameterized queries.
-*
-* Supports all filter operators from the schema layer:
-* - Comparison: eq, ne, gt, gte, lt, lte
-* - String: contains, startsWith, endsWith
-* - Set: in, notIn
-* - Null: isNull (true/false)
-* - Logical: AND, OR, NOT
-* - PostgreSQL array: arrayContains (@>), arrayContainedBy (<@), arrayOverlaps (&&)
-* - JSONB path: metadata->key syntax
-*
-* All values are parameterized ($1, $2, ...) to prevent SQL injection.
-* Column names are converted from camelCase to snake_case.
-*/
+declare function buildUpdate(options: UpdateOptions, dialect?: Dialect): UpdateResult;
 interface WhereResult {
 	readonly sql: string;
 	readonly params: readonly unknown[];
@@ -207,7 +205,9 @@ interface WhereFilter {
 *
 * @param filter - The filter object with column conditions
 * @param paramOffset - Starting parameter offset (0-based, params start at $offset+1)
+* @param overrides - Optional casing overrides for camelCase -> snake_case conversion
+* @param dialect - SQL dialect for parameter placeholders and feature checks
 * @returns WhereResult with the SQL string (without WHERE keyword) and parameter values
 */
-declare function buildWhere(filter: WhereFilter | undefined, paramOffset?: number): WhereResult;
+declare function buildWhere(filter: WhereFilter | undefined, paramOffset?: number, overrides?: CasingOverrides, dialect?: Dialect): WhereResult;
 export { sql, snakeToCamel, camelToSnake, buildWhere, buildUpdate, buildSelect, buildInsert, buildDelete, WhereResult, UpdateResult, UpdateOptions, SqlFragment, SelectResult, SelectOptions, OnConflictOptions, InsertResult, InsertOptions, DeleteResult, DeleteOptions };

package/dist/sql/index.js

@@ -4,11 +4,11 @@ import {
   buildSelect,
   buildUpdate,
   buildWhere
-} from "../shared/chunk-3f2grpak.js";
+} from "../shared/chunk-0e1vy9qd.js";
 import {
   camelToSnake,
   snakeToCamel
-} from "../shared/chunk-hrfdj0rr.js";
+} from "../shared/chunk-v2qm94qp.js";
 // src/sql/tagged.ts
 function isSqlFragment(value) {
   return typeof value === "object" && value !== null && "_tag" in value && value._tag === "SqlFragment";

package/dist/sqlite/index.d.ts

@@ -0,0 +1,221 @@
+/**
+* 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 JsonbValidator<T> {
+	parse(value: unknown): T;
+}
+interface ColumnMetadata {
+	readonly sqlType: string;
+	readonly primary: boolean;
+	readonly unique: boolean;
+	readonly nullable: boolean;
+	readonly hasDefault: boolean;
+	readonly _annotations: Record<string, true>;
+	readonly isReadOnly: boolean;
+	readonly isAutoUpdate: 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>;
+	readonly generate?: "cuid" | "uuid" | "nanoid";
+}
+/** 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(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;
+	}>;
+	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";
+	}>;
+	is<TFlag extends string>(flag: TFlag): ColumnBuilder<TType, Omit<TMeta, "_annotations"> & {
+		readonly _annotations: TMeta["_annotations"] & { readonly [K in TFlag] : 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;
+	}>;
+	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;
+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 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 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 columns annotated 'hidden'. Includes everything else.
+*/
+type Infer<T extends ColumnRecord> = { [K in ColumnKeysWithoutAnyAnnotation<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]> };
+/**
+* $response -- API response shape. Excludes columns annotated 'hidden'.
+*/
+type Response<T extends ColumnRecord> = { [K in ColumnKeysWithoutAnyAnnotation<T, "hidden">] : InferColumnType<T[K]> };
+/**
+* $create_input -- API create input shape.
+* Excludes readOnly and primary key columns.
+* Columns with defaults are optional.
+*/
+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 columns annotated 'hidden'. */
+	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>;
+	/** 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>;
+}
+/**
+* Database Adapter Types for @vertz/db
+*
+* Generic adapter interface that abstracts database operations.
+* Implemented by SQLite, D1, and other database adapters.
+*/
+interface ListOptions {
+	where?: Record<string, unknown>;
+	orderBy?: Record<string, "asc" | "desc">;
+	limit?: number;
+	/** Cursor-based pagination: fetch records after this ID. */
+	after?: string;
+}
+interface EntityDbAdapter {
+	get(id: string): Promise<Record<string, unknown> | null>;
+	list(options?: ListOptions): Promise<{
+		data: Record<string, unknown>[];
+		total: number;
+	}>;
+	create(data: Record<string, unknown>): Promise<Record<string, unknown>>;
+	update(id: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
+	delete(id: string): Promise<Record<string, unknown> | null>;
+}
+interface SqliteAdapterOptions<T extends ColumnRecord> {
+	/** The table schema definition */
+	schema: TableDef<T>;
+	/** Path to the SQLite database file */
+	dbPath?: string;
+	/** Directory to store the database file (alternative to dbPath) */
+	dataDir?: string;
+	/** Auto-apply migrations on startup */
+	migrations?: {
+		autoApply?: boolean;
+	};
+}
+/**
+* Create a SQLite driver using bun:sqlite or better-sqlite3.
+*/
+declare function createSqliteDriver(dbPath: string): DbDriver;
+/**
+* Create a SQLite EntityDbAdapter from a schema.
+*/
+declare function createSqliteAdapter<T extends ColumnRecord>(options: SqliteAdapterOptions<T>): Promise<EntityDbAdapter>;
+export { createSqliteDriver, createSqliteAdapter, SqliteAdapterOptions };