@b9g/zen 0.1.1 → 0.1.3

package/src/impl/errors.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Structured error types for database operations.
+ *
+ * All database errors extend DatabaseError, which includes an error code
+ * for programmatic error handling.
+ */
+export type DatabaseErrorCode = "VALIDATION_ERROR" | "TABLE_DEFINITION_ERROR" | "MIGRATION_ERROR" | "MIGRATION_LOCK_ERROR" | "QUERY_ERROR" | "NOT_FOUND" | "ALREADY_EXISTS" | "CONSTRAINT_VIOLATION" | "CONNECTION_ERROR" | "TRANSACTION_ERROR" | "ENSURE_ERROR" | "SCHEMA_DRIFT_ERROR" | "CONSTRAINT_PREFLIGHT_ERROR";
+/**
+ * Base error class for all database errors.
+ *
+ * Includes an error code for programmatic handling.
+ */
+export declare class DatabaseError extends Error {
+    readonly code: DatabaseErrorCode;
+    constructor(code: DatabaseErrorCode, message: string, options?: ErrorOptions);
+}
+/**
+ * Thrown when Zod validation fails during insert/update.
+ */
+export declare class ValidationError extends DatabaseError {
+    readonly fieldErrors: Record<string, string[]>;
+    constructor(message: string, fieldErrors?: Record<string, string[]>, options?: ErrorOptions);
+}
+/**
+ * Thrown when table definition is invalid (e.g., dots in names).
+ */
+export declare class TableDefinitionError extends DatabaseError {
+    readonly tableName?: string;
+    readonly fieldName?: string;
+    constructor(message: string, tableName?: string, fieldName?: string, options?: ErrorOptions);
+}
+/**
+ * Thrown when migration fails.
+ */
+export declare class MigrationError extends DatabaseError {
+    readonly fromVersion: number;
+    readonly toVersion: number;
+    constructor(message: string, fromVersion: number, toVersion: number, options?: ErrorOptions);
+}
+/**
+ * Thrown when migration lock cannot be acquired.
+ */
+export declare class MigrationLockError extends DatabaseError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Thrown when a query fails.
+ */
+export declare class QueryError extends DatabaseError {
+    readonly sql?: string;
+    constructor(message: string, sql?: string, options?: ErrorOptions);
+}
+/**
+ * Thrown when an expected entity is not found.
+ */
+export declare class NotFoundError extends DatabaseError {
+    readonly tableName: string;
+    readonly id?: unknown;
+    constructor(tableName: string, id?: unknown, options?: ErrorOptions);
+}
+/**
+ * Thrown when trying to create an entity that already exists.
+ */
+export declare class AlreadyExistsError extends DatabaseError {
+    readonly tableName: string;
+    readonly field?: string;
+    readonly value?: unknown;
+    constructor(tableName: string, field?: string, value?: unknown, options?: ErrorOptions);
+}
+/**
+ * Thrown when a database constraint is violated.
+ *
+ * Constraint violations are detected at the database level and converted
+ * from driver-specific errors into this normalized format.
+ *
+ * **Stable fields**: All fields are always present with defined types.
+ * Best-effort extraction from driver errors means some may be undefined.
+ *
+ * **Transaction behavior**: This error is thrown immediately and does NOT
+ * auto-rollback. The caller or driver transaction wrapper handles rollback.
+ */
+export declare class ConstraintViolationError extends DatabaseError {
+    /**
+     * Type of constraint that was violated.
+     * "unknown" if the specific type couldn't be determined from the error.
+     */
+    readonly kind: "unique" | "foreign_key" | "check" | "not_null" | "unknown";
+    /**
+     * Name of the constraint (e.g., "users_email_unique", "users.email").
+     * May be undefined if the database error didn't include it.
+     */
+    readonly constraint?: string;
+    /**
+     * Table name where the violation occurred.
+     * May be undefined if not extractable from the error.
+     */
+    readonly table?: string;
+    /**
+     * Column name involved in the violation.
+     * May be undefined if not extractable from the error.
+     */
+    readonly column?: string;
+    constructor(message: string, details: {
+        kind: "unique" | "foreign_key" | "check" | "not_null" | "unknown";
+        constraint?: string;
+        table?: string;
+        column?: string;
+    }, options?: ErrorOptions);
+}
+/**
+ * Thrown when database connection fails.
+ */
+export declare class ConnectionError extends DatabaseError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Thrown when a transaction fails.
+ */
+export declare class TransactionError extends DatabaseError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Operation type for ensure operations.
+ */
+export type EnsureOperation = "ensureTable" | "ensureConstraints" | "copyColumn";
+/**
+ * Thrown when an ensure operation fails.
+ *
+ * Includes step information for diagnosing partial failures,
+ * since DDL is not reliably transactional on all databases (especially MySQL).
+ */
+export declare class EnsureError extends DatabaseError {
+    /** The operation that failed */
+    readonly operation: EnsureOperation;
+    /** The table being operated on */
+    readonly table: string;
+    /** The step index where failure occurred (0-based) */
+    readonly step: number;
+    constructor(message: string, details: {
+        operation: EnsureOperation;
+        table: string;
+        step: number;
+    }, options?: ErrorOptions);
+}
+/**
+ * Thrown when schema drift is detected.
+ *
+ * Schema drift occurs when an existing database object doesn't match
+ * the expected schema definition. For example, a column exists but
+ * has a different type, or an index covers different columns.
+ */
+export declare class SchemaDriftError extends DatabaseError {
+    /** The table where drift was detected */
+    readonly table: string;
+    /** Description of what drifted */
+    readonly drift: string;
+    /** Suggested action to resolve */
+    readonly suggestion?: string;
+    constructor(message: string, details: {
+        table: string;
+        drift: string;
+        suggestion?: string;
+    }, options?: ErrorOptions);
+}
+/**
+ * Thrown when a constraint preflight check finds violations.
+ *
+ * Before adding a UNIQUE constraint or foreign key to existing data,
+ * a preflight check verifies data integrity. This error is thrown
+ * when violations are found, including the query used to detect them.
+ */
+export declare class ConstraintPreflightError extends DatabaseError {
+    /** The table being constrained */
+    readonly table: string;
+    /** The constraint being added (e.g., "unique:email" or "fk:authorId") */
+    readonly constraint: string;
+    /** Number of violating rows */
+    readonly violationCount: number;
+    /** The SQL query that found the violations - run it to see details */
+    readonly query: string;
+    constructor(message: string, details: {
+        table: string;
+        constraint: string;
+        violationCount: number;
+        query: string;
+    }, options?: ErrorOptions);
+}
+/**
+ * Check if an error is a DatabaseError.
+ */
+export declare function isDatabaseError(error: unknown): error is DatabaseError;
+/**
+ * Check if an error has a specific error code.
+ */
+export declare function hasErrorCode(error: unknown, code: DatabaseErrorCode): error is DatabaseError;

package/src/impl/query.d.ts

@@ -0,0 +1,249 @@
+/**
+ * Query layer - tagged template SQL with parameterized queries.
+ *
+ * Generates SELECT statements with prefixed column aliases for entity normalization.
+ */
+import { type Table, type DriverDecoder } from "./table.js";
+import { type SQLTemplate } from "./template.js";
+import { type SQLDialect } from "./sql.js";
+export type { SQLDialect } from "./sql.js";
+export interface QueryOptions {
+    dialect?: SQLDialect;
+}
+export interface ParsedQuery {
+    sql: string;
+    params: unknown[];
+}
+/**
+ * Render a SQL template to {sql, params} format.
+ * Useful for testing and debugging template output.
+ *
+ * @param template - SQLTemplate tuple [strings, ...values]
+ * @param dialect - SQL dialect for identifier quoting (default: sqlite)
+ * @returns {sql, params} for the rendered template
+ */
+export declare function renderFragment(template: SQLTemplate, dialect?: SQLDialect): {
+    sql: string;
+    params: unknown[];
+};
+/**
+ * Build SELECT clause as a template with ident markers.
+ *
+ * Returns a template tuple that can be rendered with renderSQL().
+ * All identifiers use ident() markers instead of dialect-specific quoting.
+ *
+ * @example
+ * const {strings, values} = buildSelectColumnsTemplate([posts, users]);
+ * // values contains ident markers: [ident("posts"), ident("id"), ident("posts.id"), ...]
+ */
+export declare function buildSelectColumnsTemplate(tables: Table<any>[]): {
+    strings: TemplateStringsArray;
+    values: unknown[];
+};
+/**
+ * Build SELECT clause with prefixed column aliases.
+ *
+ * For derived tables (created via Table.derive()), this function:
+ * - Skips derived fields when outputting regular columns
+ * - Appends derived SQL expressions with auto-generated aliases
+ *
+ * @example
+ * buildSelectColumns([posts, users], "sqlite")
+ * // { sql: '"posts"."id" AS "posts.id", ...', params: [] }
+ *
+ * @example
+ * // With derived table
+ * const PostsWithCount = Posts.derive('likeCount', z.number())`COUNT(*)`;
+ * buildSelectColumns([PostsWithCount], "sqlite")
+ * // { sql: '"posts"."id" AS "posts.id", ..., COUNT(*) AS "posts.likeCount"', params: [] }
+ */
+export declare function buildSelectColumns(tables: Table<any>[], dialect?: SQLDialect): {
+    sql: string;
+    params: unknown[];
+};
+/**
+ * Expand a template by flattening nested fragments and converting tables to ident markers.
+ *
+ * This produces a flat template tuple with:
+ * - SQLTemplate tuples merged in
+ * - Table objects converted to ident() markers
+ * - Regular values passed through
+ *
+ * The result can be rendered with renderSQL() for final SQL output.
+ *
+ * @param strings - Template strings
+ * @param values - Template values
+ * @returns Flat template tuple {strings, values}
+ */
+export declare function expandTemplate(strings: TemplateStringsArray, values: unknown[]): {
+    strings: TemplateStringsArray;
+    values: unknown[];
+};
+/**
+ * Parse a tagged template into SQL string and params array.
+ *
+ * Supports:
+ * - SQL templates/fragments: merged and parameterized
+ * - Table objects: interpolated as quoted table names
+ * - Other values: become parameterized placeholders
+ *
+ * @example
+ * parseTemplate`WHERE id = ${userId} AND active = ${true}`
+ * // { sql: "WHERE id = ? AND active = ?", params: ["user-123", true] }
+ *
+ * @example
+ * parseTemplate`WHERE ${where(Users, { role: "admin" })}`
+ * // { sql: "WHERE role = ?", params: ["admin"] }
+ *
+ * @example
+ * parseTemplate`FROM ${Posts} JOIN ${Users} ON ...`
+ * // { sql: 'FROM "posts" JOIN "users" ON ...', params: [] }
+ */
+export declare function parseTemplate(strings: TemplateStringsArray, values: unknown[], dialect?: SQLDialect): ParsedQuery;
+/**
+ * Build a full SELECT query as a template with ident markers.
+ *
+ * Returns a template tuple that can be rendered with renderSQL().
+ * The userClauses string is appended as-is (it should already contain placeholders).
+ *
+ * @example
+ * const {strings, values} = buildQueryTemplate([posts, users], "WHERE published = ?");
+ * // values contains ident markers plus any params from derived expressions
+ */
+/**
+ * @internal
+ * Build a query template from tables and raw SQL clauses.
+ *
+ * WARNING: userClauses is appended verbatim as raw SQL. Do not pass untrusted input.
+ * For parameterized queries, use Database methods or tagged templates instead.
+ */
+export declare function buildQueryTemplate(tables: Table<any>[], userClauses?: string): {
+    strings: TemplateStringsArray;
+    values: unknown[];
+};
+/**
+ * @internal
+ * Build a full SELECT query for tables with user-provided clauses.
+ *
+ * WARNING: userClauses is appended verbatim as raw SQL. Do not pass untrusted input.
+ * For parameterized queries, use Database methods or tagged templates instead.
+ *
+ * @example
+ * buildQuery([posts, users], "JOIN users ON users.id = posts.author_id WHERE published = ?", "sqlite")
+ */
+export declare function buildQuery(tables: Table<any>[], userClauses: string, dialect?: SQLDialect): {
+    sql: string;
+    params: unknown[];
+};
+/**
+ * Create a tagged template function for querying tables.
+ *
+ * @example
+ * const query = createQuery([posts, users], "sqlite");
+ * const { sql, params } = query`
+ *   JOIN users ON users.id = posts.author_id
+ *   WHERE published = ${true}
+ * `;
+ */
+export declare function createQuery(tables: Table<any>[], dialect?: SQLDialect): (strings: TemplateStringsArray, ...values: unknown[]) => ParsedQuery;
+/**
+ * Parse a raw SQL template (no table-based SELECT generation).
+ *
+ * @example
+ * const { sql, params } = rawQuery`SELECT COUNT(*) FROM posts WHERE author_id = ${userId}`;
+ */
+export declare function rawQuery(strings: TemplateStringsArray, ...values: unknown[]): ParsedQuery;
+/**
+ * Create a raw query function for a specific dialect.
+ */
+export declare function createRawQuery(dialect: SQLDialect): (strings: TemplateStringsArray, ...values: unknown[]) => ParsedQuery;
+/**
+ * Entity normalization - Apollo-style entity deduplication with reference resolution.
+ *
+ * Takes raw SQL results with prefixed columns and returns normalized entities
+ * with references resolved to actual object instances.
+ */
+/**
+ * Raw row from SQL query with prefixed column names.
+ * @example { "posts.id": "p1", "posts.authorId": "u1", "users.id": "u1", "users.name": "Alice" }
+ */
+export type RawRow = Record<string, unknown>;
+/**
+ * Entity map keyed by "table:primaryKey"
+ */
+export type EntityMap = Map<string, Record<string, unknown>>;
+/**
+ * Table map by table name for lookup
+ */
+export type TableMap = Map<string, Table<any>>;
+/**
+ * Extract entity data from a raw row for a specific table.
+ *
+ * @example
+ * extractEntityData({ "posts.id": "p1", "users.id": "u1" }, "posts")
+ * // { id: "p1" }
+ */
+export declare function extractEntityData(row: RawRow, tableName: string): Record<string, unknown> | null;
+/**
+ * Get the primary key value for an entity.
+ */
+export declare function getPrimaryKeyValue(entity: Record<string, unknown>, table: Table<any>): string | null;
+/**
+ * Create entity key for the entity map.
+ */
+export declare function entityKey(tableName: string, primaryKey: string): string;
+/**
+ * Build an entity map from raw rows.
+ *
+ * Entities are deduplicated - same primary key = same object instance.
+ * Each entity is parsed through its table's schema for type coercion
+ * (e.g., z.coerce.date() converts date strings to Date objects).
+ */
+export declare function buildEntityMap(rows: RawRow[], tables: Table<any>[], driver?: DriverDecoder): EntityMap;
+/**
+ * Resolve references for all entities in the map.
+ *
+ * Resolves both forward references (belongs-to) and reverse references (has-many).
+ *
+ * **Forward references** (`as`): Populates referenced entity as a single object.
+ * **Reverse references** (`reverseAs`): Populates array of referencing entities.
+ *
+ * **Performance**: Uses indexing to avoid O(n²) scans - builds index once per table,
+ * then attaches in O(n).
+ *
+ * **Ordering**: Reverse relationship arrays follow query result order, which is
+ * database-dependent unless you specify ORDER BY in your SQL.
+ */
+export declare function resolveReferences(entities: EntityMap, tables: Table<any>[]): void;
+/**
+ * Apply derived properties to entities.
+ *
+ * Derived properties are non-enumerable lazy getters that transform already-fetched data.
+ * They must be pure functions (no I/O, no side effects).
+ */
+export declare function applyDerivedProperties(entities: EntityMap, tables: Table<any>[]): void;
+/**
+ * Extract main table entities from the entity map in row order.
+ *
+ * Maintains the order from the original query results.
+ */
+export declare function extractMainEntities<T>(rows: RawRow[], mainTable: Table<any>, entities: EntityMap): T[];
+/**
+ * Normalize raw SQL rows into deduplicated entities with resolved references.
+ *
+ * @example
+ * const rows = [
+ *   { "posts.id": "p1", "posts.authorId": "u1", "users.id": "u1", "users.name": "Alice" },
+ *   { "posts.id": "p2", "posts.authorId": "u1", "users.id": "u1", "users.name": "Alice" },
+ * ];
+ *
+ * const posts = normalize(rows, [posts, users]);
+ * // posts[0].author === posts[1].author  // Same instance!
+ */
+export declare function normalize<T>(rows: RawRow[], tables: Table<any>[], driver?: DriverDecoder): T[];
+/**
+ * Normalize a single row into an entity.
+ *
+ * Returns null if the main table has no data (e.g., no match).
+ */
+export declare function normalizeOne<T>(row: RawRow | null, tables: Table<any>[], driver?: DriverDecoder): T | null;

package/src/impl/sql.d.ts

@@ -0,0 +1,47 @@
+/**
+ * SQL rendering utilities for all dialects.
+ *
+ * This is the single source of truth for dialect-specific SQL rendering:
+ * - Identifier quoting
+ * - Placeholder syntax
+ * - SQL builtin resolution
+ * - Template rendering (for DDL and queries)
+ */
+export type SQLDialect = "sqlite" | "postgresql" | "mysql";
+/**
+ * Quote an identifier based on dialect.
+ * MySQL uses backticks, PostgreSQL/SQLite use double quotes.
+ */
+export declare function quoteIdent(name: string, dialect: SQLDialect): string;
+/**
+ * Get placeholder syntax based on dialect.
+ * PostgreSQL uses $1, $2, etc. MySQL/SQLite use ?.
+ */
+export declare function placeholder(index: number, dialect: SQLDialect): string;
+export { resolveSQLBuiltin } from "./builtins.js";
+/**
+ * Render a template to SQL string with parameters.
+ * Handles SQLIdentifier markers and regular values.
+ */
+export declare function renderSQL(strings: TemplateStringsArray, values: readonly unknown[], dialect: SQLDialect): {
+    sql: string;
+    params: unknown[];
+};
+/**
+ * Render a DDL template to SQL string.
+ * Handles identifiers (quoted), SQL builtins (resolved), and literal values (escaped/inlined).
+ * Used for CREATE TABLE, CREATE VIEW, etc.
+ */
+export declare function renderDDL(strings: TemplateStringsArray, values: readonly unknown[], dialect: SQLDialect): string;
+/**
+ * Build SQL from template parts with parameter placeholders.
+ *
+ * This is the shared implementation used by all Node drivers (MySQL, PostgreSQL, SQLite).
+ * Handles SQLBuiltin symbols, SQLIdentifiers, and regular parameter values.
+ *
+ * SQL builtins and identifiers are inlined directly; other values use placeholders.
+ */
+export declare function buildSQL(strings: TemplateStringsArray, values: unknown[], dialect: SQLDialect): {
+    sql: string;
+    params: unknown[];
+};