@vertz/db 0.2.0

package/dist/internals.d.ts

@@ -0,0 +1,223 @@
+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;
+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>;
+}
+/**
+* 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>>;
+/**
+* Execute a SQL query, mapping PG errors to typed DbError.
+*/
+declare function executeQuery<T>(queryFn: QueryFn, sql: string, params: readonly unknown[]): Promise<ExecutorResult<T>>;
+interface CountArgs {
+	readonly where?: Record<string, unknown>;
+}
+interface AggregateArgs {
+	readonly where?: Record<string, unknown>;
+	readonly _avg?: Record<string, true>;
+	readonly _sum?: Record<string, true>;
+	readonly _min?: Record<string, true>;
+	readonly _max?: Record<string, true>;
+	readonly _count?: true | Record<string, true>;
+}
+interface GroupByArgs {
+	readonly by: readonly string[];
+	readonly where?: Record<string, unknown>;
+	readonly _count?: true | Record<string, true>;
+	readonly _avg?: Record<string, true>;
+	readonly _sum?: Record<string, true>;
+	readonly _min?: Record<string, true>;
+	readonly _max?: Record<string, true>;
+	readonly orderBy?: Record<string, "asc" | "desc">;
+	readonly limit?: number;
+	readonly offset?: number;
+}
+/**
+* Get all column names from a table definition.
+*/
+declare function getColumnNames(table: TableDef<ColumnRecord>): string[];
+/**
+* Get column names excluding hidden 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.
+*/
+declare function getNotHiddenColumns(table: TableDef<ColumnRecord>): 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
+* - { id: true, name: true } -> explicit pick
+*/
+declare function resolveSelectColumns(table: TableDef<ColumnRecord>, select?: Record<string, unknown>): string[];
+/**
+* Get timestamp column names that support the 'now' sentinel.
+*/
+declare function getTimestampColumns(table: TableDef<ColumnRecord>): string[];
+/**
+* Get the primary key column name(s) for a table.
+*/
+declare function getPrimaryKeyColumns(table: TableDef<ColumnRecord>): string[];
+/**
+* Row mapper — converts snake_case PostgreSQL row keys to camelCase.
+*
+* Used by query builder methods to normalize result rows from PG.
+* Handles nested objects and arrays (for JSONB columns, these are
+* preserved as-is since JSONB key casing is user-defined).
+*/
+/**
+* Convert all top-level keys of a row from snake_case to camelCase.
+* JSONB columns (objects/arrays) are not deeply transformed — only
+* top-level column keys are mapped.
+*/
+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 };

package/dist/internals.js

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

package/dist/plugin/index.d.ts

@@ -0,0 +1,66 @@
+/**
+* Mutation event emitted by the event bus.
+*/
+interface MutationEvent {
+	type: "create" | "update" | "delete";
+	table: string;
+	data: unknown;
+}
+type EventHandler = (event: MutationEvent) => void;
+interface EventBus {
+	emit(event: MutationEvent): void;
+	on(handler: EventHandler): void;
+	off(handler: EventHandler): void;
+}
+/**
+* Create a synchronous event bus for mutation events.
+*/
+declare function createEventBus(): EventBus;
+/**
+* The shape of a query for fingerprinting.
+* Only the structural keys matter — not the parameter values.
+*/
+interface QueryShape {
+	table: string;
+	operation: string;
+	where?: Record<string, unknown>;
+	select?: Record<string, unknown>;
+	include?: Record<string, unknown>;
+}
+/**
+* Produce a deterministic fingerprint for a query shape.
+*
+* 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;
+/**
+* Context passed to plugin hooks.
+*/
+interface QueryContext {
+	table: string;
+	operation: string;
+	args: Record<string, unknown>;
+	fingerprint: string;
+}
+/**
+* Plugin interface for the database.
+*
+* @experimental
+*/
+interface DbPlugin {
+	name: string;
+	beforeQuery?(context: QueryContext): QueryContext | undefined;
+	afterQuery?(context: QueryContext, result: unknown): unknown;
+}
+interface PluginRunner {
+	runBeforeQuery(context: QueryContext): QueryContext | undefined;
+	runAfterQuery(context: QueryContext, result: unknown): unknown;
+}
+/**
+* Create a plugin runner that executes hooks across a set of plugins.
+*
+* @experimental
+*/
+declare function createPluginRunner(plugins: DbPlugin[]): PluginRunner;
+export { fingerprint, createPluginRunner, createEventBus, QueryShape, QueryContext, PluginRunner, MutationEvent, EventHandler, EventBus, DbPlugin };

package/dist/plugin/index.js

@@ -0,0 +1,66 @@
+// src/plugin/event-bus.ts
+function createEventBus() {
+  const handlers = new Set;
+  return {
+    emit(event) {
+      for (const handler of handlers) {
+        handler(event);
+      }
+    },
+    on(handler) {
+      handlers.add(handler);
+    },
+    off(handler) {
+      handlers.delete(handler);
+    }
+  };
+}
+// src/plugin/fingerprint.ts
+import { createHash } from "node:crypto";
+function fingerprint(query) {
+  const parts = [
+    query.table,
+    query.operation,
+    `w:${sortedKeys(query.where)}`,
+    `s:${sortedKeys(query.select)}`,
+    `i:${sortedKeys(query.include)}`
+  ];
+  const input = parts.join("|");
+  return createHash("sha256").update(input).digest("hex").slice(0, 16);
+}
+function sortedKeys(obj) {
+  if (!obj)
+    return "";
+  return Object.keys(obj).sort().join(",");
+}
+// src/plugin/plugin-runner.ts
+function createPluginRunner(plugins) {
+  return {
+    runBeforeQuery(context) {
+      for (const plugin of plugins) {
+        if (plugin.beforeQuery) {
+          const result = plugin.beforeQuery(context);
+          if (result !== undefined) {
+            return result;
+          }
+        }
+      }
+      return;
+    },
+    runAfterQuery(context, result) {
+      let current = result;
+      for (const plugin of plugins) {
+        if (plugin.afterQuery) {
+          const pluginResult = plugin.afterQuery(context, current);
+          current = pluginResult !== undefined ? pluginResult : current;
+        }
+      }
+      return current;
+    }
+  };
+}
+export {
+  fingerprint,
+  createPluginRunner,
+  createEventBus
+};