@vertz/db 0.2.0

package/dist/shared/chunk-xp022dyp.js

@@ -0,0 +1,296 @@
+import {
+  snakeToCamel
+} from "./chunk-hrfdj0rr.js";
+
+// src/errors/db-error.ts
+class DbError extends Error {
+  pgCode;
+  table;
+  query;
+  constructor(message) {
+    super(message);
+    this.name = new.target.name;
+  }
+  toJSON() {
+    const json = {
+      error: this.name,
+      code: this.code,
+      message: this.message
+    };
+    if (this.table !== undefined) {
+      json.table = this.table;
+    }
+    return json;
+  }
+}
+
+class UniqueConstraintError extends DbError {
+  code = "UNIQUE_VIOLATION";
+  pgCode = "23505";
+  table;
+  query;
+  column;
+  value;
+  constructor(options) {
+    super(`Unique constraint violated on ${options.table}.${options.column}${options.value !== undefined ? ` (value: ${options.value})` : ""}`);
+    this.table = options.table;
+    this.column = options.column;
+    this.value = options.value;
+    this.query = options.query;
+  }
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      table: this.table,
+      column: this.column
+    };
+  }
+}
+
+class ForeignKeyError extends DbError {
+  code = "FOREIGN_KEY_VIOLATION";
+  pgCode = "23503";
+  table;
+  query;
+  constraint;
+  detail;
+  constructor(options) {
+    super(`Foreign key constraint "${options.constraint}" violated on table ${options.table}`);
+    this.table = options.table;
+    this.constraint = options.constraint;
+    this.detail = options.detail;
+    this.query = options.query;
+  }
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      table: this.table
+    };
+  }
+}
+
+class NotNullError extends DbError {
+  code = "NOT_NULL_VIOLATION";
+  pgCode = "23502";
+  table;
+  query;
+  column;
+  constructor(options) {
+    super(`Not-null constraint violated on ${options.table}.${options.column}`);
+    this.table = options.table;
+    this.column = options.column;
+    this.query = options.query;
+  }
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      table: this.table,
+      column: this.column
+    };
+  }
+}
+
+class CheckConstraintError extends DbError {
+  code = "CHECK_VIOLATION";
+  pgCode = "23514";
+  table;
+  query;
+  constraint;
+  constructor(options) {
+    super(`Check constraint "${options.constraint}" violated on table ${options.table}`);
+    this.table = options.table;
+    this.constraint = options.constraint;
+    this.query = options.query;
+  }
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      table: this.table
+    };
+  }
+}
+
+class NotFoundError extends DbError {
+  code = "NOT_FOUND";
+  table;
+  query;
+  constructor(table, query) {
+    super(`Record not found in table ${table}`);
+    this.table = table;
+    this.query = query;
+  }
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      table: this.table
+    };
+  }
+}
+
+class ConnectionError extends DbError {
+  code = "CONNECTION_ERROR";
+  constructor(message) {
+    super(`Database connection error: ${message}`);
+  }
+}
+
+class ConnectionPoolExhaustedError extends ConnectionError {
+  code = "POOL_EXHAUSTED";
+  constructor(poolSize) {
+    super(`Connection pool exhausted (max: ${poolSize})`);
+    this.name = "ConnectionPoolExhaustedError";
+  }
+}
+
+// src/errors/pg-parser.ts
+function extractKeyDetail(detail) {
+  if (!detail)
+    return null;
+  const match = detail.match(/^Key \(([^)]+)\)=\(([^)]*)\)/);
+  if (!match)
+    return null;
+  return { column: match[1], value: match[2] };
+}
+function extractNotNullColumn(message) {
+  const match = message.match(/null value in column "([^"]+)"/);
+  return match ? match[1] : null;
+}
+function extractCheckConstraint(message) {
+  const match = message.match(/violates check constraint "([^"]+)"/);
+  return match ? match[1] : null;
+}
+function isConnectionErrorCode(code) {
+  return code.startsWith("08");
+}
+
+class UnknownDbError extends DbError {
+  code;
+  table;
+  query;
+  constructor(code, message, table, query) {
+    super(message);
+    this.code = code;
+    this.table = table;
+    this.query = query;
+  }
+}
+function parsePgError(pgError, query) {
+  const { code, message, table, column, constraint, detail } = pgError;
+  switch (code) {
+    case "23505": {
+      const keyDetail = extractKeyDetail(detail);
+      return new UniqueConstraintError({
+        table: table ?? "unknown",
+        column: column ?? keyDetail?.column ?? "unknown",
+        value: keyDetail?.value,
+        query
+      });
+    }
+    case "23503": {
+      return new ForeignKeyError({
+        table: table ?? "unknown",
+        constraint: constraint ?? "unknown",
+        detail,
+        query
+      });
+    }
+    case "23502": {
+      const extractedColumn = extractNotNullColumn(message);
+      return new NotNullError({
+        table: table ?? "unknown",
+        column: column ?? extractedColumn ?? "unknown",
+        query
+      });
+    }
+    case "23514": {
+      const extractedConstraint = extractCheckConstraint(message);
+      return new CheckConstraintError({
+        table: table ?? "unknown",
+        constraint: constraint ?? extractedConstraint ?? "unknown",
+        query
+      });
+    }
+    default: {
+      if (isConnectionErrorCode(code)) {
+        return new ConnectionError(message);
+      }
+      return new UnknownDbError(code, message, table, query);
+    }
+  }
+}
+
+// src/query/executor.ts
+function isPgError(error) {
+  return typeof error === "object" && error !== null && "code" in error && typeof error.code === "string" && "message" in error && typeof error.message === "string";
+}
+async function executeQuery(queryFn, sql, params) {
+  try {
+    return await queryFn(sql, params);
+  } catch (error) {
+    if (isPgError(error)) {
+      throw parsePgError(error, sql);
+    }
+    throw error;
+  }
+}
+
+// src/query/helpers.ts
+function getColumnNames(table) {
+  return Object.keys(table._columns);
+}
+function getDefaultColumns(table) {
+  return Object.keys(table._columns).filter((key) => {
+    const col = table._columns[key];
+    return col ? !col._meta.hidden : true;
+  });
+}
+function getNotSensitiveColumns(table) {
+  return Object.keys(table._columns).filter((key) => {
+    const col = table._columns[key];
+    return col ? !col._meta.sensitive && !col._meta.hidden : true;
+  });
+}
+function getNotHiddenColumns(table) {
+  return Object.keys(table._columns).filter((key) => {
+    const col = table._columns[key];
+    return col ? !col._meta.hidden : true;
+  });
+}
+function resolveSelectColumns(table, select) {
+  if (!select) {
+    return getDefaultColumns(table);
+  }
+  if ("not" in select && select.not !== undefined) {
+    if (select.not === "sensitive") {
+      return getNotSensitiveColumns(table);
+    }
+    return getNotHiddenColumns(table);
+  }
+  return Object.keys(select).filter((k) => select[k] === true);
+}
+function getTimestampColumns(table) {
+  return Object.keys(table._columns).filter((key) => {
+    const col = table._columns[key];
+    return col ? col._meta.sqlType === "timestamp with time zone" : false;
+  });
+}
+function getPrimaryKeyColumns(table) {
+  return Object.keys(table._columns).filter((key) => {
+    const col = table._columns[key];
+    return col ? col._meta.primary : false;
+  });
+}
+
+// src/query/row-mapper.ts
+function mapRow(row) {
+  const result = {};
+  for (const key of Object.keys(row)) {
+    result[snakeToCamel(key)] = row[key];
+  }
+  return result;
+}
+function mapRows(rows) {
+  return rows.map((row) => mapRow(row));
+}
+
+export { DbError, UniqueConstraintError, ForeignKeyError, NotNullError, CheckConstraintError, NotFoundError, ConnectionError, ConnectionPoolExhaustedError, parsePgError, executeQuery, getColumnNames, getDefaultColumns, getNotSensitiveColumns, getNotHiddenColumns, resolveSelectColumns, getTimestampColumns, getPrimaryKeyColumns, mapRow, mapRows };

package/dist/sql/index.d.ts

@@ -0,0 +1,213 @@
+/**
+* Casing conversion utilities for camelCase <-> snake_case.
+*
+* Used by SQL builders to convert JavaScript property names (camelCase)
+* to PostgreSQL column names (snake_case) and vice versa.
+*/
+/**
+* Convert a camelCase string to snake_case.
+*
+* Handles acronyms correctly:
+* - "parseJSON" -> "parse_json"
+* - "getHTTPSUrl" -> "get_https_url"
+* - "htmlParser" -> "html_parser"
+*/
+declare function camelToSnake(str: string): 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
+*/
+interface DeleteOptions {
+	readonly table: string;
+	readonly where?: Record<string, unknown>;
+	readonly returning?: "*" | readonly string[];
+}
+interface DeleteResult {
+	readonly sql: string;
+	readonly params: readonly unknown[];
+}
+/**
+* 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
+*/
+interface OnConflictOptions {
+	readonly columns: readonly string[];
+	readonly action: "nothing" | "update";
+	readonly updateColumns?: readonly string[];
+	/** Explicit update values for ON CONFLICT DO UPDATE SET (used by upsert). */
+	readonly updateValues?: Record<string, unknown>;
+}
+interface InsertOptions {
+	readonly table: string;
+	readonly data: Record<string, unknown> | readonly Record<string, unknown>[];
+	readonly returning?: "*" | readonly string[];
+	readonly onConflict?: OnConflictOptions;
+	/** Column names (camelCase) that should use NOW() instead of a parameterized value when the value is "now". */
+	readonly nowColumns?: readonly string[];
+}
+interface InsertResult {
+	readonly sql: string;
+	readonly params: readonly unknown[];
+}
+/**
+* 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
+*/
+interface SelectOptions {
+	readonly table: string;
+	readonly columns?: readonly string[];
+	readonly where?: Record<string, unknown>;
+	readonly orderBy?: Record<string, "asc" | "desc">;
+	readonly limit?: number;
+	readonly offset?: number;
+	readonly withCount?: boolean;
+	/** 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;
+}
+interface SelectResult {
+	readonly sql: string;
+	readonly params: readonly unknown[];
+}
+/**
+* Build a SELECT statement from the given options.
+*/
+declare function buildSelect(options: SelectOptions): SelectResult;
+/**
+* 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[];
+}
+/**
+* SQL tagged template with escape hatch.
+*
+* Use as a tagged template literal for automatic parameterization:
+*   sql`SELECT * FROM users WHERE id = ${userId}`
+*
+* Use sql.raw() for trusted raw SQL injection:
+*   sql.raw('column_name')
+*
+* Compose fragments by nesting sql`` inside sql``:
+*   const where = sql`WHERE active = ${true}`;
+*   const query = sql`SELECT * FROM users ${where}`;
+*/
+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>;
+	readonly where?: Record<string, unknown>;
+	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[];
+}
+interface UpdateResult {
+	readonly sql: string;
+	readonly params: readonly unknown[];
+}
+/**
+* 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.
+*/
+interface WhereResult {
+	readonly sql: string;
+	readonly params: readonly unknown[];
+}
+interface WhereFilter {
+	readonly [key: string]: unknown;
+	readonly OR?: readonly WhereFilter[];
+	readonly AND?: readonly WhereFilter[];
+	readonly NOT?: WhereFilter;
+}
+/**
+* Build a WHERE clause from a filter object.
+*
+* @param filter - The filter object with column conditions
+* @param paramOffset - Starting parameter offset (0-based, params start at $offset+1)
+* @returns WhereResult with the SQL string (without WHERE keyword) and parameter values
+*/
+declare function buildWhere(filter: WhereFilter | undefined, paramOffset?: number): 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

@@ -0,0 +1,64 @@
+import {
+  buildDelete,
+  buildInsert,
+  buildSelect,
+  buildUpdate,
+  buildWhere
+} from "../shared/chunk-3f2grpak.js";
+import {
+  camelToSnake,
+  snakeToCamel
+} from "../shared/chunk-hrfdj0rr.js";
+// src/sql/tagged.ts
+function isSqlFragment(value) {
+  return typeof value === "object" && value !== null && "_tag" in value && value._tag === "SqlFragment";
+}
+function renumberParams(sqlStr, offset) {
+  let counter = 0;
+  return sqlStr.replace(/\$(\d+)/g, () => {
+    counter++;
+    return `$${offset + counter}`;
+  });
+}
+function sqlTag(strings, ...values) {
+  const sqlParts = [];
+  const allParams = [];
+  for (let i = 0;i < strings.length; i++) {
+    const part = strings[i] ?? "";
+    sqlParts.push(part);
+    if (i < values.length) {
+      const value = values[i];
+      if (isSqlFragment(value)) {
+        const renumbered = renumberParams(value.sql, allParams.length);
+        sqlParts.push(renumbered);
+        allParams.push(...value.params);
+      } else {
+        allParams.push(value);
+        sqlParts.push(`$${allParams.length}`);
+      }
+    }
+  }
+  return {
+    _tag: "SqlFragment",
+    sql: sqlParts.join(""),
+    params: allParams
+  };
+}
+function rawSql(value) {
+  return {
+    _tag: "SqlFragment",
+    sql: value,
+    params: []
+  };
+}
+var sql = Object.assign(sqlTag, { raw: rawSql });
+export {
+  sql,
+  snakeToCamel,
+  camelToSnake,
+  buildWhere,
+  buildUpdate,
+  buildSelect,
+  buildInsert,
+  buildDelete
+};

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@vertz/db",
+  "version": "0.2.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "Database layer for Vertz — typed queries, migrations, codegen",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vertz-dev/vertz.git",
+    "directory": "packages/db"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./sql": {
+      "types": "./dist/sql/index.d.ts",
+      "import": "./dist/sql/index.js"
+    },
+    "./internals": {
+      "types": "./dist/internals.d.ts",
+      "import": "./dist/internals.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin/index.d.ts",
+      "import": "./dist/plugin/index.js"
+    },
+    "./diagnostic": {
+      "types": "./dist/diagnostic/index.d.ts",
+      "import": "./dist/diagnostic/index.js"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js"
+    },
+    "./schema-derive": {
+      "types": "./dist/schema-derive/index.d.ts",
+      "import": "./dist/schema-derive/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bunup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@electric-sql/pglite": "^0.3.14",
+    "@types/node": "^25.2.1",
+    "@vitest/coverage-v8": "^4.0.18",
+    "bunup": "latest",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@vertz/schema": "workspace:*",
+    "postgres": "^3.4.8"
+  }
+}