turbine-orm 0.21.0 → 0.22.0

package/dist/cli/ui.d.ts

@@ -40,7 +40,7 @@ export declare const symbols: {
     readonly bottomLeft: "+" | "╰";
     readonly bottomRight: "+" | "╯";
     readonly tee: "|" | "├";
-    readonly teeEnd: "└" | "\\";
+    readonly teeEnd: "\\" | "└";
 };
 export declare function box(content: string, options?: {
     title?: string;

package/dist/client.js

@@ -113,7 +113,9 @@ export class TransactionClient {
             // We use a proxy pool that routes queries through the transaction client
             const txPool = this.createTxPool();
             const txOpts = { ...this.queryOptions, _txScoped: true };
-            qi = new QueryInterface(txPool, name, this.schema, this.middlewares, txOpts);
+            qi = txOpts.queryInterfaceFactory
+                ? txOpts.queryInterfaceFactory(txPool, name, this.schema, this.middlewares, txOpts)
+                : new QueryInterface(txPool, name, this.schema, this.middlewares, txOpts);
             this.tableCache.set(name, qi);
         }
         return qi;
@@ -254,6 +256,11 @@ export class TurbineClient {
             preparedStatements: envDisablePrepared ? false : (config.preparedStatements ?? !config.pool),
             sqlCache: config.sqlCache ?? true,
             dialect: config.dialect,
+            // Non-SQL backends (PowDB) inject a factory that builds their own query
+            // interface (PowqlInterface) instead of the SQL QueryInterface. SQL engines
+            // never set this, so `table()` keeps constructing `new QueryInterface`.
+            queryInterfaceFactory: config
+                .queryInterfaceFactory,
             _onQuery: (event) => {
                 if (this.queryListeners.size === 0)
                     return;
@@ -405,7 +412,9 @@ export class TurbineClient {
     table(name) {
         let qi = this.tableCache.get(name);
         if (!qi) {
-            qi = new QueryInterface(this.pool, name, this.schema, this.middlewares, this.queryOptions);
+            qi = this.queryOptions?.queryInterfaceFactory
+                ? this.queryOptions.queryInterfaceFactory(this.pool, name, this.schema, this.middlewares, this.queryOptions)
+                : new QueryInterface(this.pool, name, this.schema, this.middlewares, this.queryOptions);
             this.tableCache.set(name, qi);
         }
         return qi;

package/dist/powdb.d.ts

@@ -0,0 +1,338 @@
+/**
+ * turbine-orm/powdb — Turbine's PowDB / PowQL backend.
+ *
+ * PowDB is a single-node embedded database with its own query language, **PowQL**
+ * (not SQL), reached over `@zvndev/powdb-client`'s binary TCP protocol. PowDB is a
+ * different shape than the SQL engines, so this module does NOT route through the
+ * SQL `Dialect` / `QueryInterface`: it ships a parallel {@link PowqlInterface} that
+ * generates PowQL, plugged into `TurbineClient` via the `queryInterfaceFactory`
+ * seam. The four SQL engines are untouched.
+ *
+ * PowDB realities shape the design (all verified firsthand against a live
+ * `powdb-server` / the embedded addon, see `docs/strategy/powdb-parity-matrix.md`):
+ *   - **`RETURNING` (since 0.7.0)** — `create/createMany/update/delete` append the
+ *     trailing `returning` keyword (`RETURNING *`, all columns) and read the
+ *     affected rows back in one round-trip. `upsert` is the lone exception (its
+ *     statement rejects `returning`) and reselects by primary key.
+ *   - **No generated IDs** — the app must supply every value → Turbine generates a
+ *     client-side UUID for the primary key when it has a default.
+ *   - **`uuid`/`datetime`/`bytes` columns can't hold client-supplied values** (no
+ *     literal, no working cast on the wire) → Turbine maps everything onto the four
+ *     writable types (`str`/`int`/`float`/`bool`); `Date` → `int` epoch micros;
+ *     `string` PKs hold UUID strings.
+ *   - **No JSON aggregation / link navigation** — single-query nested `with` is
+ *     impossible → it degrades to batched N+1 loaders (Phase B).
+ *   - **Single global write lock; no savepoints/isolation/pipelining** — nested
+ *     transactions / isolation / vector / LISTEN-NOTIFY / RLS throw.
+ *
+ * `@zvndev/powdb-client` is an **optional peer dependency** loaded by dynamic
+ * import; `npm i turbine-orm` still pulls only `pg`.
+ *
+ * @example
+ * ```ts
+ * import { turbinePowDB } from 'turbine-orm/powdb';
+ * import { SCHEMA } from './generated/turbine/metadata.js';
+ *
+ * const db = await turbinePowDB({ host: '127.0.0.1', port: 5433 }, SCHEMA);
+ * const user = await db.table('users').create({ data: { name: 'Ada' } }); // UUID id auto-generated
+ * const found = await db.table('users').findMany({ where: { name: 'Ada' }, limit: 10 });
+ * await db.disconnect();
+ * ```
+ *
+ * @module
+ */
+import { type PgCompatPool, type PgCompatPoolClient, TurbineClient, type TurbineConfig } from './client.js';
+import { type Dialect } from './dialect.js';
+import type { ColumnMetadata, SchemaMetadata, TableMetadata } from './schema.js';
+/**
+ * Capability descriptor for PowDB. PowQL generation is owned by
+ * {@link PowqlInterface} (not the SQL `Dialect`), so this dialect exists only to
+ * drive `TurbineClient`'s capability gating and transaction keywords:
+ *   - `supports*` flags are all `false` for the Postgres-only features, so
+ *     `$listen`/`$notify`, RLS `sessionContext`/`$withSession`, and pgvector
+ *     throw a clear {@link UnsupportedFeatureError} (E017) at the client surface
+ *     instead of emitting SQL that PowDB cannot parse.
+ *   - `begin`/`commit`/`rollback` are lowercase PowQL keywords (verified on the
+ *     wire) so a single-level `$transaction` works.
+ *   - PowDB has a single global write lock and supports neither savepoints nor
+ *     nested/concurrent transactions. The `savepoint*` keywords therefore throw
+ *     {@link UnsupportedFeatureError} (E017): a nested `tx.$transaction` emits a
+ *     savepoint synchronously (before any DB call) and so fails fast with a
+ *     clear typed error instead of leaking PowDB's cryptic `Parse(... 'sp_1')`.
+ *     The pool-level begin-while-active guard (see {@link PowdbPool}) catches the
+ *     other re-entrant shape — a fresh top-level `db.$transaction` opened inside
+ *     an already-open one — before it can deadlock on the write lock.
+ * Isolation levels remain Phase B.
+ */
+export declare const powdbDialect: Dialect;
+/** A single value PowDB accepts as a positional `$N` parameter. */
+type PowdbParam = string | number | bigint | boolean | null;
+/**
+ * Marker wrapper for a value bound to a `float` column. The networked driver
+ * unwraps it to the plain number (the wire param is unchanged), but the
+ * *embedded* literal encoder reads it to emit a float-form PowQL literal (`42`
+ * → `42.0`) so an integer-valued float column stays unambiguously a float.
+ * Constructed in {@link PowqlInterface.param}.
+ */
+export declare class PowdbFloatParam {
+    readonly value: number;
+    constructor(value: number);
+}
+/** The four shapes a PowQL result takes over the wire. */
+type PowdbResult = {
+    kind: 'rows';
+    columns: string[];
+    rows: string[][];
+} | {
+    kind: 'scalar';
+    value: string;
+} | {
+    kind: 'ok';
+    affected: bigint;
+} | {
+    kind: 'message';
+    message: string;
+};
+interface PowdbClient {
+    readonly serverVersion: string;
+    query(query: string, params?: PowdbParam[], opts?: {
+        signal?: AbortSignal;
+    }): Promise<PowdbResult>;
+    close(): Promise<void>;
+}
+interface PowdbClientPool {
+    acquire(): Promise<PowdbClient>;
+    release(c: PowdbClient): void;
+    destroy(c: PowdbClient): void;
+    withClient<T>(fn: (c: PowdbClient) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+}
+/** Connection options for {@link turbinePowDB} — host/port, not a connection string. */
+export interface PowdbConnOptions {
+    host: string;
+    port: number;
+    dbName?: string;
+    user?: string;
+    password?: string | null;
+    connectTimeoutMs?: number;
+    tls?: boolean;
+}
+/** Minimum PowDB server version the networked transport requires. */
+export declare const MIN_POWDB_VERSION = "0.7.0";
+/**
+ * Parse a `powdb://[user[:pass]@]host[:port][/db]` connection string into
+ * {@link PowdbConnOptions} (consistency with `turbineMysql`/`turbineMssql`,
+ * which accept a URL). Defaults: host `127.0.0.1`, port `5433`.
+ */
+export declare function parsePowdbUrl(connectionString: string): PowdbConnOptions;
+/**
+ * Fail fast if a networked PowDB server is older than {@link MIN_POWDB_VERSION}.
+ * Turbine's write path relies on the trailing `returning` keyword and the
+ * int→float coercion fix, both of which landed in 0.7.0. Embedded exposes no
+ * version method, so this is networked-only (the embedded peer is pinned ^0.7.0
+ * at install time). A non-semver / empty version string is tolerated (we cannot
+ * prove it is too old).
+ */
+export declare function assertSupportedPowdbVersion(version: string | undefined): void;
+/** PowQL column types Turbine is willing to emit (the four writable scalars). */
+export type PowqlType = 'str' | 'int' | 'float' | 'bool';
+/**
+ * Map a Turbine column to the PowQL DDL type used in `defineSchema` →
+ * `type T { … }`. Turbine never emits PowDB's `uuid`/`datetime`/`bytes` types,
+ * which cannot hold client-supplied values on the wire (no literal, no cast):
+ *   - `Date` → `int` (epoch micros)   - `boolean` → `bool`
+ *   - integral `number`/`bigint` → `int`   - fractional `number` → `float`
+ *   - everything else (incl. UUID/PK strings) → `str`
+ * Array / JSON / bytes columns throw — they have no PowDB equivalent.
+ */
+export declare function powqlColumnType(col: ColumnMetadata): PowqlType;
+/**
+ * Generate PowQL DDL (`type T { … }`) for every table in a schema. Used to
+ * provision a PowDB database from a code-first `defineSchema`/`SchemaMetadata`
+ * (PowDB has no migration runner yet). The primary key column is declared
+ * `required unique`; non-nullable columns are `required`.
+ */
+export declare function powqlSchemaDDL(schema: SchemaMetadata): string[];
+/**
+ * Coerce a single PowDB wire string into the JS value its column type implies.
+ * Every PowDB value arrives as a string; NULL arrives as the bareword `"null"`.
+ * Metadata resolves the `"null"` ambiguity for nullable non-string columns.
+ */
+export declare function coerceValue(raw: string, col: ColumnMetadata): unknown;
+/**
+ * Map one raw PowDB row (snake-cased columns → raw wire strings, as produced by
+ * {@link PowdbPool}) into a typed entity (camelCase fields, coerced values).
+ * Only the columns present in `raw` are emitted, so partial `select` projections
+ * round-trip unchanged.
+ */
+export declare function rowToEntity(raw: Record<string, unknown>, meta: TableMetadata): Record<string, unknown>;
+/**
+ * Translate a PowDB error into a typed Turbine error. Handles BOTH transports,
+ * whose error shapes differ:
+ *   - **networked** (`@zvndev/powdb-client`) tags errors with a *semantic*
+ *     `.code` (`connect_failed`, `timeout`, `query_failed`, …);
+ *   - **embedded** (`@zvndev/powdb-embedded` napi addon) tags EVERY error
+ *     `code:'GenericFailure'`, so the class can only be recovered from the
+ *     message text (`Execution("column 'email' is required …")`,
+ *     `Execution("type mismatch …")`, `Parse(…)`, `StorageError(…)`).
+ *
+ * So we always run the unique-constraint and message-shape checks first (they
+ * fire for both transports), then fall through to the networked `.code` switch.
+ */
+export declare function wrapPowdbError(err: unknown): Error;
+type QueryArg = string | {
+    name?: string;
+    text: string;
+    values?: unknown[];
+};
+/**
+ * A {@link PgCompatPool} backed by a `@zvndev/powdb-client` `Pool`. The query
+ * `text` is **PowQL**, not SQL — {@link PowqlInterface} generates it. Rows come
+ * back as raw strings here; per-column JS coercion happens in `PowqlInterface`
+ * (it owns the schema metadata).
+ */
+export declare class PowdbPool implements PgCompatPool {
+    readonly pool: PowdbClientPool;
+    private readonly toParam;
+    private closed;
+    /**
+     * Pool-level single-writer guard. PowDB holds one global write lock, so at
+     * most one transaction may be open across the whole pool. A `begin` issued
+     * while this is `true` is rejected (it would otherwise check out a second
+     * connection and block on the lock forever — the networked re-entrant hang).
+     */
+    private activeTransaction;
+    constructor(pool: PowdbClientPool, toParam?: (v: unknown, i: number) => PowdbParam);
+    /**
+     * Enforce the single-writer model on a transaction-control statement. Throws
+     * (before any query runs) if a `begin` arrives while a transaction is open;
+     * otherwise flips the pool-level flag. Returns the control kind so the caller
+     * can decide whether it even needs to hit the engine.
+     */
+    private guardTxControl;
+    query(text: QueryArg, values?: unknown[]): Promise<any>;
+    connect(): Promise<PgCompatPoolClient>;
+    end(): Promise<void>;
+}
+/** The embedded addon's result shape (matches {@link PowdbResult} but with optional fields). */
+interface EmbeddedQueryResult {
+    kind: string;
+    columns?: string[];
+    rows?: string[][];
+    value?: string;
+    affected?: bigint;
+    message?: string;
+}
+/** A single in-process embedded database handle (`@zvndev/powdb-embedded`). */
+interface EmbeddedDatabase {
+    query(powql: string): EmbeddedQueryResult;
+    querySql(sql: string): EmbeddedQueryResult;
+    queryReadonly(powql: string): EmbeddedQueryResult;
+    isPoisoned(): boolean;
+    /** WAL durability selector — `@zvndev/powdb-embedded` ≥ 0.7.1. */
+    setSyncMode?(mode: string): void;
+}
+/**
+ * Encode a JS value as a **PowQL literal** for the embedded driver, which takes
+ * no params array — `$N` placeholders must be materialized into the query text.
+ *
+ * This is the single place Turbine builds PowQL text from a value, so it is the
+ * security-critical surface. String encoding matches PowDB's lexer
+ * (`crates/query/src/lexer.rs`) exactly: a string literal is `"…"`, and inside
+ * it the lexer recognizes only the escapes `\"`, `\\`, `\n`, `\t` (any other
+ * `\x` drops the backslash and keeps `x`; every non-`\`/non-`"` char — raw
+ * newlines, CR, unicode — is taken literally). So we escape `\` → `\\` and
+ * `"` → `\"` (the only breakout vectors), render `\n`/`\t` as their recognized
+ * escapes, and leave everything else raw. Verified against the real engine:
+ * quotes, backslashes, `$N`, `"); drop … --`, raw CR, and emoji all round-trip
+ * as data and cannot break out of the literal or inject a second statement.
+ */
+export declare function encodePowqlLiteral(value: unknown): string;
+/**
+ * Substitute every `$N` placeholder in a generator-produced PowQL template with
+ * the encoded literal of `params[N-1]`. Safe because the template is produced by
+ * {@link PowqlInterface} and contains **no** user string literals — the only
+ * `$<digits>` tokens are genuine positional placeholders, so a single scan
+ * cannot accidentally rewrite a `$N` that is itself part of a value (values are
+ * params, never inlined into the template by the generator).
+ */
+export declare function materializePowql(powql: string, params: unknown[]): string;
+/**
+ * A {@link PgCompatPool} backed by an in-process `@zvndev/powdb-embedded`
+ * `Database`. The embedded addon takes **no params array** — its `query(powql)`
+ * accepts only a string — so this pool materializes each positional `$N` into a
+ * PowQL literal via {@link materializePowql} before handing the text to the
+ * engine. One handle, single connection: transaction keywords (`begin`/`commit`/
+ * `rollback`) are issued serially as ordinary queries.
+ */
+export declare class PowdbEmbeddedPool implements PgCompatPool {
+    private readonly db;
+    private closed;
+    /**
+     * Single-writer guard. The embedded engine is one handle with one global
+     * write lock — only one transaction may be open at a time. A re-entrant
+     * `begin` (a fresh top-level `db.$transaction` opened inside an open one)
+     * would otherwise hit PowDB's raw "already in a transaction" parse error;
+     * this surfaces a typed error instead. (Nested `tx.$transaction` is caught
+     * earlier still, by the savepoint override in {@link powdbDialect}.)
+     */
+    private activeTransaction;
+    constructor(db: EmbeddedDatabase);
+    /** Enforce the single-writer model on a transaction-control statement. */
+    private guardTxControl;
+    private run;
+    query(text: QueryArg, values?: unknown[]): Promise<any>;
+    connect(): Promise<PgCompatPoolClient>;
+    end(): Promise<void>;
+}
+export { PowqlInterface } from './powql.js';
+/** Options for {@link turbinePowDB}. */
+export interface TurbinePowdbOptions extends Pick<TurbineConfig, 'logging' | 'defaultLimit' | 'warnOnUnlimited'> {
+    /** Max pooled connections (default 10). Networked transport only. */
+    connectionLimit?: number;
+}
+/**
+ * Selects the **embedded** transport — an in-process `@zvndev/powdb-embedded`
+ * database at the given data directory (no server, no socket). The value is the
+ * data dir path. Preview: Full-durability checkpoint-bound; built binaries ship
+ * for macOS (arm64/x64) and Unix-glibc only (Intel-mac/musl/Windows fall back to
+ * a from-source `npm run build`).
+ *
+ * @example
+ * ```ts
+ * const db = await turbinePowDB({ embedded: '/var/data/app.powdb' }, SCHEMA);
+ * // Faster writes (fsync off the commit path, bounded-loss) — requires addon >= 0.7.1:
+ * const fast = await turbinePowDB({ embedded: '/var/data/app.powdb', syncMode: 'normal' }, SCHEMA);
+ * ```
+ */
+export interface TurbinePowdbEmbeddedTarget {
+    embedded: string;
+    /**
+     * WAL durability for the embedded engine (requires `@zvndev/powdb-embedded` ≥ 0.7.1):
+     * `'full'` (default — fsync per commit), `'normal'` (fsync off the commit path,
+     * ~15–40× faster writes, bounded loss on OS crash/power loss), `'off'` (bench-only).
+     */
+    syncMode?: 'full' | 'normal' | 'off';
+    /** Per-query memory budget in bytes (requires `@zvndev/powdb-embedded` ≥ 0.7.1). */
+    memoryLimit?: number;
+}
+/**
+ * Bind Turbine to PowDB. `target` is one of:
+ *   - a `powdb://[user[:pass]@]host[:port][/db]` connection string → a
+ *     **networked** `@zvndev/powdb-client` pool (consistency with
+ *     `turbineMysql`/`turbineMssql`);
+ *   - a host/port options object → a **networked** `@zvndev/powdb-client` pool;
+ *   - an `{ embedded: <data-dir> }` object → an in-process
+ *     `@zvndev/powdb-embedded` database (no server);
+ *   - an already-constructed `@zvndev/powdb-client` `Pool` or {@link PowdbPool}
+ *     (injection — you own its lifecycle and `disconnect()` is a no-op).
+ *
+ * On the networked transport the server version is probed and a clear
+ * {@link ConnectionError} is thrown if it is older than {@link MIN_POWDB_VERSION}
+ * (the `returning` keyword / int->float coercion fix Turbine relies on).
+ *
+ * Resolves to a `TurbineClient` whose `table()` accessors generate **PowQL** via
+ * {@link PowqlInterface}. The SQL `Dialect` is not involved.
+ */
+export declare function turbinePowDB(target: string | PowdbConnOptions | PowdbClientPool | PowdbPool | TurbinePowdbEmbeddedTarget, schema: SchemaMetadata, options?: TurbinePowdbOptions): Promise<TurbineClient>;
+//# sourceMappingURL=powdb.d.ts.map