@vertz/db 0.2.0 → 0.2.1

package/dist/d1/index.d.ts

@@ -0,0 +1,241 @@
+/**
+* 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 D1DatabaseBinding {
+	prepare(sql: string): D1PreparedStatement;
+}
+interface D1PreparedStatement {
+	bind(...values: unknown[]): D1PreparedStatement;
+	all(): Promise<{
+		results: unknown[];
+	}>;
+	run(): Promise<{
+		meta: {
+			changes: number;
+		};
+	}>;
+}
+interface D1AdapterOptions<T extends ColumnRecord> {
+	/** The table schema definition */
+	schema: TableDef<T>;
+	/** D1 database binding from Cloudflare env */
+	d1: D1DatabaseBinding;
+	/**
+	* Whether migrations should be applied at runtime.
+	* NOTE: For D1, migrations should typically be run via `wrangler d1 migrations apply`
+	* during deployment, not at runtime. Set to false for production use.
+	*/
+	migrations?: {
+		autoApply?: boolean;
+	};
+}
+/**
+* Create a DbDriver from a D1 database binding.
+*/
+declare function createD1Driver(d1: D1DatabaseBinding): DbDriver;
+/**
+* Create a D1 EntityDbAdapter from a schema and D1 binding.
+*
+* NOTE: For production D1 deployments, migrations should be run via
+* `wrangler d1 migrations apply` during deployment, NOT at runtime.
+* Set `migrations.autoApply = false` or omit the migrations option for production.
+*/
+declare function createD1Adapter<T extends ColumnRecord>(options: D1AdapterOptions<T>): EntityDbAdapter;
+export { createD1Driver, createD1Adapter, D1PreparedStatement, D1DatabaseBinding, D1AdapterOptions };

package/dist/d1/index.js

@@ -0,0 +1,8 @@
+import {
+  createD1Adapter,
+  createD1Driver
+} from "../shared/chunk-ktbebkz5.js";
+export {
+  createD1Driver,
+  createD1Adapter
+};

package/dist/diagnostic/index.js

@@ -2,7 +2,7 @@ import {
   diagnoseError,
   explainError,
   formatDiagnostic
-} from "../shared/chunk-wj026daz.js";
+} from "../shared/chunk-k04v1jjx.js";
 export {
   formatDiagnostic,
   explainError,