turbine-orm 0.49.0 → 0.50.0

package/dist/cjs/optional-peer-import.d.cts

@@ -0,0 +1,72 @@
+/**
+ * True dynamic `import()` for the optional peer dependencies (`mysql2`,
+ * `mssql`, `@zvndev/powdb-client`, `@zvndev/powdb-embedded`) — safe in BOTH
+ * build outputs, including for peers that are ESM-only.
+ *
+ * THE PROBLEM THIS FILE SOLVES (the `@zvndev/powdb-client` ≥ 0.9 CJS break):
+ * the engine subpaths load their optional peers with dynamic `import()` so the
+ * peers stay out of the static graph. The ESM build (`tsconfig.json`, module
+ * NodeNext) emits that `import()` verbatim. The CJS build (`tsconfig.cjs.json`,
+ * module CommonJS) however TRANSPILES `import()` into
+ * `Promise.resolve().then(() => require(...))` — and `require()` of an
+ * ESM-only package (no `require` export condition, e.g. powdb-client ≥ 0.9)
+ * throws `ERR_PACKAGE_PATH_NOT_EXPORTED`, breaking every CJS consumer.
+ *
+ * TypeScript offers no way to preserve `import()` under `module: CommonJS`,
+ * and the CJS pass cannot switch to `module: NodeNext` (the root package.json
+ * says `"type": "module"`, so NodeNext would classify every `.ts` source as
+ * ESM and emit ESM into dist/cjs). A `.cts` file is the escape hatch: it is
+ * CommonJS-format by extension regardless of package `type`, so under the ESM
+ * pass (NodeNext) it compiles to `dist/optional-peer-import.cjs` — a CommonJS
+ * file whose `import()` SURVIVES transpilation (NodeNext preserves dynamic
+ * import in CJS files precisely because it is the only way CJS can load ESM).
+ *
+ * That gives the published package two copies of this module:
+ *   - `dist/optional-peer-import.cjs`      (ESM pass, NodeNext)  — real `import()`
+ *   - `dist/cjs/optional-peer-import.cjs`  (CJS pass, CommonJS)  — lowered to `require()`
+ *
+ * The lowered copy works fine for CJS-loadable peers (`mysql2`, `mssql`, older
+ * powdb peers). When it hits an ESM-only peer, the `require()` fails with a
+ * recognizable code and this function falls back to delegating the load to the
+ * sibling NodeNext copy one directory up (`../optional-peer-import.cjs`) —
+ * which is a plain CommonJS file (loadable by `require()` on every supported
+ * Node) whose real `import()` then loads the ESM peer. The ESM-pass copy has
+ * no such sibling; its lazy `require` throws and the original error surfaces,
+ * so the fallback can never recurse.
+ *
+ * Keep this module dependency-free and side-effect-free: it must be loadable
+ * from both module systems on every supported Node (≥ 20) without pulling in
+ * anything else.
+ */
+/**
+ * Dynamically import an optional peer dependency. In the ESM build this is a
+ * plain `import()`. In the CJS build the first attempt is a transpiled
+ * `require()`; if the peer turns out to be ESM-only, the load is retried
+ * through the ESM-build sibling copy of this file, whose `import()` survived
+ * transpilation (see the module doc comment).
+ *
+ * @param specifier bare package specifier (e.g. `'@zvndev/powdb-client'`).
+ * @param allowEsmFallback internal recursion guard — the delegated call passes
+ *   `false` so a failure in the sibling copy can never bounce back.
+ */
+declare function importOptionalPeer(specifier: string, allowEsmFallback?: boolean): Promise<unknown>;
+/**
+ * Merged namespace so callers can reach {@link peerPackageVersion} off the same
+ * default import (`importOptionalPeer.peerPackageVersion(...)`). Lives in this
+ * `.cts` file for the same reason the dynamic import does: a `.cts` compiles to
+ * CommonJS in BOTH build passes, so `require` / `require.resolve` are natively
+ * available and `import.meta` is never emitted (which would break the CJS build
+ * and crash CJS consumers, see `resolveEmbeddedVersion` in powdb.ts).
+ */
+declare namespace importOptionalPeer {
+    /**
+     * Resolve an optional peer's declared `package.json` version WITHOUT loading
+     * the package itself (so an ESM-only peer never trips `require`). `require` is
+     * anchored on THIS module's location (inside the published `dist/`), so bare
+     * resolution walks up `node_modules` and finds the peer exactly where
+     * `import.meta.url` used to point, but it compiles under `module: CommonJS`
+     * too. Returns `null` when the peer / its package.json cannot be resolved.
+     */
+    function peerPackageVersion(specifier: string): string | null;
+}
+export = importOptionalPeer;

package/dist/cjs/pipeline-submittable.d.ts

@@ -0,0 +1,93 @@
+/**
+ * turbine-orm — Real Postgres pipeline protocol implementation
+ *
+ * Uses the pg extended-query protocol wire methods (parse/bind/describe/execute/sync)
+ * exposed on pg.Client's Connection object to send multiple queries in a single
+ * TCP flush. This achieves true 1-RTT pipeline execution instead of the sequential
+ * await-per-query approach.
+ *
+ * The approach (listener-swap):
+ *   1. Detach the pg.Client's event listeners from the Connection
+ *   2. Attach our own state-machine listeners
+ *   3. Cork the TCP stream, push all protocol messages, uncork (one TCP write)
+ *   4. Drive a state machine over backend response events
+ *   5. Restore original listeners and release the client
+ *
+ * This is the same pattern used by pg-cursor and pg-query-stream, but extended
+ * to handle N queries in a single pipeline.
+ */
+import type { EventEmitter } from 'node:events';
+import type { DeferredQuery } from './query/index.js';
+/** The pg Connection object — an EventEmitter with wire-protocol methods */
+export interface PgConnection extends EventEmitter {
+    stream: {
+        cork?: () => void;
+        uncork?: () => void;
+        writable?: boolean;
+        destroy?: (err?: Error) => void;
+        write?: (...args: unknown[]) => boolean;
+    };
+    parse(query: {
+        text: string;
+        name?: string;
+        types?: number[];
+    }): void;
+    bind(config: {
+        portal?: string;
+        statement?: string;
+        values?: unknown[];
+        binary?: boolean;
+        valueMapper?: (val: unknown, index: number) => unknown;
+    }): void;
+    describe(msg: {
+        type: 'S' | 'P';
+        name?: string;
+    }): void;
+    execute(config: {
+        portal?: string;
+        rows?: number;
+    }): void;
+    sync(): void;
+}
+/** A pg PoolClient with the internal fields we need */
+export interface PgPoolClient {
+    connection: PgConnection;
+    /** pg.Client sets this to control query queue draining */
+    readyForQuery: boolean;
+    /** Type parser overrides (if the client has custom type parsers) */
+    _types?: unknown;
+    release(err?: Error | boolean): void;
+}
+export interface PipelineRunOptions {
+    /**
+     * Whether to wrap the pipeline in BEGIN/COMMIT (default: true).
+     * When true, all queries execute atomically. On error, ROLLBACK is sent.
+     * When false, each query gets its own Sync message for error isolation.
+     */
+    transactional?: boolean;
+    /** Timeout in milliseconds. If exceeded, the connection is destroyed. */
+    timeout?: number;
+}
+/**
+ * Execute multiple queries using the Postgres extended-query pipeline protocol.
+ *
+ * All protocol messages are buffered into a single TCP write via cork/uncork.
+ * The backend processes them in order and sends back results which our state
+ * machine collects.
+ *
+ * @param client - A pg PoolClient with an accessible Connection
+ * @param queries - Array of DeferredQuery descriptors
+ * @param options - Pipeline options (transactional, timeout)
+ * @returns Array of transformed results in the same order as queries
+ */
+export declare function runPipelined<T extends readonly DeferredQuery<unknown>[]>(client: PgPoolClient, queries: T, options?: PipelineRunOptions): Promise<unknown[]>;
+/**
+ * Check whether a pool client supports the extended-query pipeline protocol.
+ *
+ * Returns true if the client has a Connection object with the required wire
+ * protocol methods (parse, bind, describe, execute, sync) and is an EventEmitter.
+ *
+ * Returns false for HTTP-based drivers (Neon HTTP, Vercel Postgres), mock pools,
+ * and any pool that doesn't expose pg internals.
+ */
+export declare function supportsExtendedPipeline(poolClient: unknown): poolClient is PgPoolClient;

package/dist/cjs/pipeline.d.ts

@@ -0,0 +1,71 @@
+/**
+ * turbine-orm — Pipeline execution
+ *
+ * Pipelines batch multiple independent queries into a single database round-trip.
+ * Instead of N sequential awaits (N round-trips), you get 1 round-trip for all N queries.
+ *
+ * How it works:
+ *   1. Each query method (findUnique, count, etc.) can produce a DeferredQuery descriptor
+ *      containing the SQL, params, and a transform function.
+ *   2. pipeline() collects these descriptors, checks whether the underlying pool client
+ *      supports the extended-query pipeline protocol, and either:
+ *      (a) executes them via real Postgres pipeline protocol (one TCP flush), or
+ *      (b) falls back to sequential execution on a single connection.
+ *
+ * Real pipeline mode uses `src/pipeline-submittable.ts` which drives the pg Connection's
+ * wire-protocol methods (parse/bind/describe/execute/sync) directly with listener-swap.
+ *
+ * Sequential fallback covers HTTP-based drivers (Neon HTTP, Vercel Postgres, Cloudflare
+ * Hyperdrive), mock pools in tests, and any pool that doesn't expose pg internals.
+ */
+import type pg from 'pg';
+import type { DeferredQuery } from './query/index.js';
+export interface PipelineOptions {
+    /**
+     * Whether to wrap the pipeline in a transaction (default: true).
+     *
+     * - `true` (default): All queries execute atomically within BEGIN/COMMIT.
+     *   If any query fails, the entire batch is rolled back.
+     *
+     * - `false`: Each query is independent. A failure in one query does NOT
+     *   affect others. On partial failure, a `PipelineError` is thrown with
+     *   per-query results in `.results`.
+     */
+    transactional?: boolean;
+    /** Timeout in milliseconds. If exceeded, the connection is destroyed. */
+    timeout?: number;
+}
+/**
+ * Execute multiple deferred queries in a single batch.
+ *
+ * On pg.Pool-backed connections with the standard TCP driver, this uses the
+ * real Postgres extended-query pipeline protocol for true 1-RTT execution.
+ * On HTTP-based drivers (Neon HTTP, Vercel Postgres, etc.) or mock pools,
+ * it falls back to sequential execution on a single connection.
+ *
+ * @example
+ * ```ts
+ * const [user, count, posts] = await executePipeline(pool, [
+ *   db.users.buildFindUnique({ where: { id: 1 } }),
+ *   db.posts.buildCount({ where: { orgId: 1 } }),
+ *   db.posts.buildFindMany({ where: { userId: 1 }, limit: 10 }),
+ * ]);
+ * ```
+ */
+export declare function executePipeline<T extends readonly DeferredQuery<unknown>[]>(pool: pg.Pool, queries: T, options?: PipelineOptions): Promise<PipelineResults<T>>;
+/**
+ * Check whether a pool supports the real pipeline protocol.
+ * Call this to determine at runtime whether pipelines will use the fast path
+ * or fall back to sequential execution.
+ *
+ * Note: This acquires and immediately releases a connection to inspect it.
+ */
+export declare function pipelineSupported(pool: pg.Pool): Promise<boolean>;
+/**
+ * Extract the result types from a tuple of DeferredQuery objects.
+ * If you pass [DeferredQuery<User>, DeferredQuery<number>, DeferredQuery<Post[]>],
+ * you get back [User, number, Post[]].
+ */
+export type PipelineResults<T extends readonly DeferredQuery<unknown>[]> = {
+    [K in keyof T]: T[K] extends DeferredQuery<infer R> ? R : never;
+};

package/dist/cjs/powdb-introspect.d.ts

@@ -0,0 +1,84 @@
+/**
+ * turbine-orm/powdb — `describe`-based introspection.
+ *
+ * PowDB exposes its catalog through two ordinary rows-returning statements
+ * (keywords since engine 0.10):
+ *   - `schema` → one row per type: `{ name, columns }` (columns = a count).
+ *   - `describe <T>` / `schema <T>` → one row per column:
+ *     `{ column, type, nullable, index }` where `type` is a PowQL type name
+ *     (`str`/`int`/`float`/`bool`/`json`/`datetime`/`uuid`/`bytes`), `nullable`
+ *     is `"true"`/`"false"`, and `index` is `"unique"` / `"index"` / `""`.
+ *
+ * {@link introspectPowdbDatabase} turns those into the same {@link SchemaMetadata}
+ * shape the SQL introspectors produce, so a code-first PowDB database can be
+ * introspected for bootstrap/verification. It is transport-agnostic: the caller
+ * supplies an `exec(powql)` that returns row objects **keyed by column name**.
+ *   - Embedded / owned pool: `exec = async (q) => ({ rows: await db.raw([q]) })`
+ *     using a live `turbinePowDB` client's `raw` tagged template.
+ *   - Networked: the raw `@zvndev/powdb-client` returns POSITIONAL rows
+ *     (`{ columns: string[], rows: string[][] }`), so zip them into records.
+ *     A bare `(await client.query(q)).rows` would hand this function `string[][]`
+ *     whose `.name` cell is `undefined` and every table would silently drop out:
+ *     ```ts
+ *     const exec = async (q) => {
+ *       const r = await client.query(q);
+ *       return { rows: r.rows.map((row) => Object.fromEntries(r.columns.map((c, i) => [c, row[i]]))) };
+ *     };
+ *     ```
+ *     (A mis-shaped exec is now caught: if `schema` returns rows but none carry
+ *     a `name`, {@link introspectPowdbDatabase} throws instead of returning an
+ *     empty schema.)
+ *
+ * IMPORTANT LIMITATIONS (all documented, none silent):
+ *   - Relations are ALWAYS `{}`: PowDB has no declared foreign keys, so
+ *     `describe` cannot report them. The recommended flow for relation-aware
+ *     metadata is code-first `defineSchema` + `schemaDefToMetadata`; use
+ *     introspection to bootstrap or verify column shape.
+ *   - Primary key is a HEURISTIC (`describe` has no PK concept): PowDB marks a
+ *     PK column as `required unique`, so the first non-nullable `unique` column
+ *     is chosen (a column named `id` wins ties). A table with no such column
+ *     yields `primaryKey: []` and a warning; single-row ops on it fail loudly.
+ *   - `isGenerated` is always `false`: `describe` does not expose PowDB's `auto`
+ *     modifier, so an introspected int PK is treated as client-supplied unless
+ *     the caller hand-edits the metadata.
+ *   - Doc-field expression indexes are INVISIBLE to `describe`, so they never
+ *     round-trip; only plain `unique`/`index` columns appear in `indexes`.
+ *   - `datetime` / `uuid` / `bytes` columns map to read-oriented TS types
+ *     (`Date` / `string` / `Uint8Array`). Turbine never emits those PowQL types
+ *     on write, so writing to such a column may not round-trip.
+ *
+ * v1 is a PROGRAMMATIC API (exported from `turbine-orm/powdb`); the CLI's
+ * `turbine generate` still defaults to Postgres. Routing a `powdb://` URL
+ * through the CLI would additionally need: a `powdbDialect.introspector`
+ * wired to a networked `exec`, and `cli/config.ts` teaching the generate
+ * funnel to construct a PowDB client instead of a `pg` client for `powdb://`.
+ */
+import { type PowdbCapabilities } from './powdb.js';
+import type { SchemaMetadata } from './schema.js';
+/** A minimal rows-returning executor over a PowDB connection (embedded or networked). */
+export type PowdbExec = (powql: string) => Promise<{
+    rows: Record<string, unknown>[];
+}>;
+/** Options controlling which tables {@link introspectPowdbDatabase} reads. */
+export interface PowdbIntrospectOptions {
+    /** Only introspect these table names (snake_case, as PowDB reports them). */
+    include?: string[];
+    /** Skip these table names. */
+    exclude?: string[];
+    /**
+     * Bound connection capabilities. When supplied AND `introspection` (engine
+     * >= 0.10) is false, this throws a version-hinting {@link UnsupportedFeatureError}
+     * (E017) up front instead of letting a pre-0.10 engine reject the `schema` /
+     * `describe` keywords with an opaque parse error. Omit it (the bare-exec path)
+     * to run ungated; the pool paths that know the version pass it through.
+     */
+    capabilities?: PowdbCapabilities;
+}
+/**
+ * Read a live PowDB database into {@link SchemaMetadata} via `schema` +
+ * `describe <T>` statements run through the supplied {@link PowdbExec}.
+ *
+ * @param exec Rows-returning executor (embedded `db.raw` or networked `client.query`).
+ * @param options `include`/`exclude` table filters.
+ */
+export declare function introspectPowdbDatabase(exec: PowdbExec, options?: PowdbIntrospectOptions): Promise<SchemaMetadata>;