turbine-orm 0.32.2 → 0.34.0

package/dist/powdb.d.ts

@@ -91,7 +91,21 @@ export declare class PowdbFloatParam {
     readonly value: number;
     constructor(value: number);
 }
-/** The four shapes a PowQL result takes over the wire. */
+/**
+ * Marker wrapper for a JS object/array bound to a `json` document column. Both
+ * transports serialize `value` with `JSON.stringify` and send the text as a
+ * `str` param / string literal, exactly how the PowDB docs insert a json
+ * document (the engine validates it as JSON text and stores the canonical
+ * binary form). Constructed in {@link PowqlInterface.param} when the target
+ * column is `json` and the value is a non-null object/array; a JS string
+ * written to a json column passes through RAW (same contract as pg jsonb,
+ * pass `'"x"'` to store the JSON string `"x"`), and `null` stays `null`.
+ */
+export declare class PowdbJsonParam {
+    readonly value: unknown;
+    constructor(value: unknown);
+}
+/** The four shapes a PowQL result takes over the legacy string wire. */
 type PowdbResult = {
     kind: 'rows';
     columns: string[];
@@ -106,11 +120,73 @@ type PowdbResult = {
     kind: 'message';
     message: string;
 };
+/**
+ * Local structural mirror of `@zvndev/powdb-client`'s `WireValue` (the lossless
+ * typed cell of the native wire surface). Defined here rather than imported so
+ * the optional peer's types never leak into Turbine's published `.d.ts` (a
+ * consumer without the peer installed must still `tsc` cleanly, same rule as
+ * every other optional-peer type in this module). `empty` = an unset value
+ * (distinct, for a json column, from a JSON-null document, which is
+ * `{ type: 'json', value: null }`).
+ */
+type PowdbWireValue = {
+    type: 'empty';
+} | {
+    type: 'int';
+    value: bigint;
+} | {
+    type: 'float';
+    value: number;
+} | {
+    type: 'bool';
+    value: boolean;
+} | {
+    type: 'str';
+    value: string;
+} | {
+    type: 'datetime';
+    value: bigint;
+} | {
+    type: 'uuid';
+    value: Uint8Array;
+} | {
+    type: 'bytes';
+    value: Uint8Array;
+} | {
+    type: 'json';
+    value: unknown;
+    pj1?: Uint8Array;
+};
+/** The native (lossless typed) result shape, mirroring `RawNativeQueryResult`. */
+type PowdbRawNativeResult = {
+    kind: 'rows';
+    columns: string[];
+    rows: PowdbWireValue[][];
+} | {
+    kind: 'scalar';
+    value: PowdbWireValue;
+} | {
+    kind: 'ok';
+    affected: bigint;
+} | {
+    kind: 'message';
+    message: string;
+};
 interface PowdbClient {
     readonly serverVersion: string;
     query(query: string, params?: PowdbParam[], opts?: {
         signal?: AbortSignal;
     }): Promise<PowdbResult>;
+    /**
+     * Lossless typed wire surface (client ≥ 0.13, server ≥ 0.13). Optional: an
+     * older client omits it, so every call site feature-detects
+     * `typeof c.queryNativeRaw === 'function'` before using it and falls back to
+     * {@link query}. It NEVER retries as a legacy query, replaying an ambiguous
+     * mutation is unsafe, so its use is additionally version-gated server-side.
+     */
+    queryNativeRaw?(query: string, params?: PowdbParam[], opts?: {
+        signal?: AbortSignal;
+    }): Promise<PowdbRawNativeResult>;
     close(): Promise<void>;
 }
 interface PowdbClientPool {
@@ -159,16 +235,78 @@ export declare function parsePowdbUrl(connectionString: string): PowdbConnOption
  * 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';
+/**
+ * Feature capabilities of a bound PowDB connection. Resolved once (from the
+ * probed server version on the networked transport, or the addon package
+ * version on embedded) and carried on the pool so {@link PowqlInterface} can
+ * gate PowQL features that only exist on newer engines, an old engine gets a
+ * typed {@link UnsupportedFeatureError} (E017) with a version hint instead of a
+ * raw PowQL parse error.
+ */
+export interface PowdbCapabilities {
+    /** Best-known engine version (e.g. `'0.13.0'`), or `null` when unknowable. */
+    engineVersion: string | null;
+    /** ≥ 0.12: `json` column type, `->` path filters / ordering / grouping. */
+    jsonDocs: boolean;
+    /** ≥ 0.13: `alter T add index (.col->seg)` expression indexes. */
+    docFieldIndexes: boolean;
+    /** ≥ 0.10: `schema` / `describe` introspection statements. */
+    introspection: boolean;
+    /** Networked only: server ≥ 0.13 AND the client exposes `queryNativeRaw`. */
+    nativeRaw: boolean;
+}
+/** The feature-gate capability keys (everything except the version/nativeRaw metadata). */
+type PowdbFeatureKey = 'jsonDocs' | 'docFieldIndexes' | 'introspection';
+/**
+ * Trusted-caller default: every FEATURE gate on, engine version unknown. Used
+ * for a directly-constructed {@link PowdbPool} / {@link PowdbEmbeddedPool} that
+ * did not go through {@link turbinePowDB}'s version probe (e.g. an injected
+ * pool, or a unit-test pool). `nativeRaw` stays OFF here because it flips the
+ * actual wire path and must only be enabled after a real server-version probe,
+ * never inferred from a bare construction.
+ */
+export declare const ALL_POWDB_CAPABILITIES: PowdbCapabilities;
+/**
+ * Derive {@link PowdbCapabilities} from an engine version string. A non-semver /
+ * unknown version turns every gate OFF (the E017 hint then tells the caller to
+ * upgrade or pass `assumeEngineVersion`). `nativeRaw` requires BOTH the client
+ * to expose `queryNativeRaw` (passed in) AND server ≥ 0.13.
+ */
+export declare function capabilitiesFromVersion(version: string | undefined | null, opts?: {
+    hasNativeRaw?: boolean;
+}): PowdbCapabilities;
+/**
+ * Throw a version-hinting {@link UnsupportedFeatureError} (E017) when a gated
+ * PowQL feature is used on an engine that does not support it. Keeps old engines
+ * getting clean typed errors instead of raw PowQL parse failures.
+ */
+export declare function requireCapability(caps: PowdbCapabilities, key: PowdbFeatureKey, feature: string): void;
+/**
+ * PowQL column types Turbine emits: the four writable scalars plus PowDB's
+ * native `json` document type (added to the map in the 0.12/0.13 parity round,
+ * see {@link isJsonColumn}). A `json` column stores a canonical binary document
+ * (sorted keys, int/float distinction preserved) that Turbine writes as a JSON
+ * string literal and reads back by parsing the canonical JSON text.
+ */
+export type PowqlType = 'str' | 'int' | 'float' | 'bool' | 'json';
+/**
+ * Does this column map to PowDB's native `json` document type? A Postgres
+ * `json`/`jsonb` type (via `dialectType`/`pgType`) is authoritative; otherwise
+ * the tsType heuristic (`Record<…>`, `object`, `unknown`, an object/array
+ * literal) that the four scalar branches do not claim. Array columns never map
+ * to json, a PowDB array only exists INSIDE a json document, so a Postgres
+ * array column has no PowDB shape and still throws in {@link powqlColumnType}.
+ */
+export declare function isJsonColumn(col: ColumnMetadata): boolean;
 /**
  * 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`
+ *   - JSON / object columns → `json` (native PowDB document type, ≥ 0.12)
  *   - everything else (incl. UUID/PK strings) → `str`
- * Array / JSON / bytes columns throw — they have no PowDB equivalent.
+ * Array (non-json) and bytes columns throw, they have no PowDB equivalent.
  */
 export declare function powqlColumnType(col: ColumnMetadata): PowqlType;
 /**
@@ -198,7 +336,18 @@ export declare const POWQL_KEYWORDS: ReadonlySet<string>;
  * errors when emitted bare, so quoting is strictly an improvement.
  */
 export declare function quotePowqlIdent(name: string): string;
-export declare function powqlSchemaDDL(schema: SchemaMetadata): string[];
+/**
+ * Options for {@link powqlSchemaDDL}. Additive: with no options the DDL is
+ * emitted unconditionally (pure-function callers / tests); pass `capabilities`
+ * to gate engine-version-specific features (json columns, and, since the
+ * 0.13 parity round, doc-field expression indexes) behind the connection's
+ * real capabilities. Doc-field expression index declarations plug into the
+ * per-table `indexes` surface consumed here without further signature churn.
+ */
+export interface PowqlSchemaDDLOptions {
+    capabilities?: PowdbCapabilities;
+}
+export declare function powqlSchemaDDL(schema: SchemaMetadata, opts?: PowqlSchemaDDLOptions): 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"`.
@@ -206,12 +355,26 @@ export declare function powqlSchemaDDL(schema: SchemaMetadata): string[];
  */
 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.
+ * Coerce a single cell that arrived over the NATIVE typed wire (decoded from a
+ * {@link PowdbWireValue}, so already a JS `bigint`/`number`/`boolean`/`string`/
+ * `NativeJson`/`Uint8Array`/`null`, never a bare `"null"` string). Unlike
+ * {@link coerceValue} this NEVER collapses the string `"null"` to `null`: an
+ * absent value already decoded to `null` (from the `empty` cell), so a genuine
+ * str `"null"` stays the string `"null"` (fixes the legacy-wire wart on the
+ * native transport). `datetime`-shaped cells (int micros) become `Date`; a
+ * bigint on a `number` column follows the int8 safe-integer policy.
+ */
+export declare function coerceNativeValue(value: unknown, col: ColumnMetadata): unknown;
+/**
+ * Map one raw PowDB row into a typed entity (camelCase fields, coerced values).
+ * Only the columns present in `raw` are emitted, so partial `select`
+ * projections round-trip unchanged. `native` selects the coercion policy: the
+ * default `false` handles the legacy string wire (every cell is a string, via
+ * {@link coerceValue}); `true` handles the native typed wire, where non-string
+ * cells arrive pre-typed and go through {@link coerceNativeValue} (see F3).
+ * Callers on the native transport pass `this.pool.capabilities.nativeRaw`.
  */
-export declare function rowToEntity(raw: Record<string, unknown>, meta: TableMetadata): Record<string, unknown>;
+export declare function rowToEntity(raw: Record<string, unknown>, meta: TableMetadata, native?: boolean): Record<string, unknown>;
 /**
  * Translate a PowDB error into a typed Turbine error. Handles BOTH transports,
  * whose error shapes differ:
@@ -226,6 +389,16 @@ export declare function rowToEntity(raw: Record<string, unknown>, meta: TableMet
  * fire for both transports), then fall through to the networked `.code` switch.
  */
 export declare function wrapPowdbError(err: unknown): Error;
+/**
+ * True when `err` is the stale-wire-frame {@link ConnectionError} produced by
+ * {@link wrapPowdbError} (its `.cause` is a `protocol_error` PowDBError, or the
+ * message carries the invalid-state signature). The opt-in read retry
+ * (`retryStaleReads`, evaluated in {@link PowqlInterface}'s exec seam) uses this
+ * to decide whether a first-statement READ may be replayed once on a fresh
+ * connection; writes are NEVER retried (an ambiguous mutation reply is unsafe
+ * to replay, matching the client's own native-path policy).
+ */
+export declare function isStaleFramePowdbError(err: unknown): boolean;
 type QueryArg = string | {
     name?: string;
     text: string;
@@ -251,12 +424,31 @@ export interface PowdbPoolOptions {
      * *after* the transaction has begun.
      */
     transactionQueueTimeoutMs?: number;
+    /**
+     * Feature capabilities of the bound connection. Set by {@link turbinePowDB}
+     * from the probed engine version; defaults to {@link ALL_POWDB_CAPABILITIES}
+     * (feature gates on, `nativeRaw` off, engine version unknown) for a
+     * directly-constructed pool: a "trusted caller".
+     */
+    capabilities?: PowdbCapabilities;
+    /**
+     * Opt in to replaying a first-statement READ once, on a fresh connection,
+     * when it fails with the stale-wire-frame {@link ConnectionError} (see
+     * {@link isStaleFramePowdbError}). Networked only; writes and mid-transaction
+     * statements are NEVER retried. Read by {@link PowqlInterface}'s exec seam.
+     * Default `false` (typed-error-only).
+     */
+    retryStaleReads?: boolean;
 }
 /**
  * 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).
+ * `text` is **PowQL**, not SQL ({@link PowqlInterface} generates it). On the
+ * legacy string wire cells come back as strings; when `capabilities.nativeRaw`
+ * is set (server ≥ 0.13 + a client exposing `queryNativeRaw`) this pool routes
+ * through the typed native wire instead, so cells arrive pre-typed (a json int
+ * as `bigint`, etc.) and each result is tagged with the wire that served it
+ * ({@link PowdbTaggedResult}). Per-column JS coercion still happens in
+ * `PowqlInterface` (it owns the schema metadata), keyed on that per-result tag.
  */
 export declare class PowdbPool implements PgCompatPool {
     readonly pool: PowdbClientPool;
@@ -280,7 +472,18 @@ export declare class PowdbPool implements PgCompatPool {
      * live socket holding the process open until the server's idle timeout.
      */
     private readonly checkedOut;
+    /** Feature capabilities of the bound server (probed version + native-wire feature-detect). */
+    readonly capabilities: PowdbCapabilities;
+    /** Opt-in first-statement-read replay on a stale wire frame (read by {@link PowqlInterface}). */
+    readonly retryStaleReads: boolean;
     constructor(pool: PowdbClientPool, toParam?: (v: unknown, i: number) => PowdbParam, options?: PowdbPoolOptions);
+    /**
+     * Run one statement on `c`, choosing the lossless native typed wire when the
+     * server supports it (`capabilities.nativeRaw`) AND this client exposes
+     * `queryNativeRaw` (a defensive per-call feature-detect, so a heterogeneous
+     * injected pool cannot crash). Otherwise the legacy string wire, unchanged.
+     */
+    private runOnClient;
     query(text: QueryArg, values?: unknown[]): Promise<any>;
     /**
      * Typed guard mirroring {@link PowdbEmbeddedPool}: after `end()` the driver
@@ -358,6 +561,14 @@ export declare class PowdbEmbeddedPool implements PgCompatPool {
     private readonly txGate;
     /** Hold taken by a `begin` issued via `query()` directly (no checked-out client). */
     private readonly poolHoldRef;
+    /**
+     * Feature capabilities of the embedded engine (resolved from the addon
+     * package version). `nativeRaw` is always false: the embedded addon exposes
+     * no native typed-wire surface (its rows are `string[][]`, the legacy wire).
+     */
+    readonly capabilities: PowdbCapabilities;
+    /** Carried for surface uniformity with {@link PowdbPool}; inert on embedded (no protocol_error frames). */
+    readonly retryStaleReads: boolean;
     constructor(db: EmbeddedDatabase, options?: PowdbPoolOptions);
     /** Materialize `$N` params and hand the PowQL to the in-process engine. */
     private exec;
@@ -372,6 +583,7 @@ export declare class PowdbEmbeddedPool implements PgCompatPool {
     connect(): Promise<PgCompatPoolClient>;
     end(): Promise<void>;
 }
+export { introspectPowdbDatabase, type PowdbExec, type PowdbIntrospectOptions, } from './powdb-introspect.js';
 export { PowqlInterface } from './powql.js';
 /** Options for {@link turbinePowDB}. */
 export interface TurbinePowdbOptions extends Pick<TurbineConfig, 'logging' | 'defaultLimit' | 'warnOnUnlimited'> {
@@ -385,8 +597,32 @@ export interface TurbinePowdbOptions extends Pick<TurbineConfig, 'logging' | 'de
      * transactions queue and run one at a time; only a re-entrant
      * `db.$transaction` (opened inside an active transaction callback) throws
      * E017 — queueing that shape would deadlock.
+     *
+     * Ignored when you inject an already-constructed {@link PowdbPool} (it carries
+     * its own {@link PowdbPoolOptions}); set it on that pool's constructor instead.
      */
     transactionQueueTimeoutMs?: number;
+    /**
+     * Opt in to replaying a first-statement READ once (on a fresh connection)
+     * when it fails with the stale-wire-frame {@link ConnectionError} that a
+     * request can hit after a long idle gap. Networked only; WRITES and any
+     * statement inside a transaction are NEVER retried (an ambiguous mutation
+     * reply is unsafe to replay). Default `false`: the error is surfaced typed
+     * so the caller can decide. See the retry recipe in the docs.
+     *
+     * Ignored when you inject an already-constructed {@link PowdbPool} (it carries
+     * its own {@link PowdbPoolOptions}); set it on that pool's constructor instead.
+     */
+    retryStaleReads?: boolean;
+    /**
+     * Override the detected engine version used for capability gating. For exotic
+     * deployments and injected pools whose version cannot be probed (a non-semver
+     * server string, or an addon whose package.json cannot be resolved): pass
+     * e.g. `'0.13.0'` to unlock the features that version supports. Without it, an
+     * undetectable version turns every version-gated feature OFF (with a hinting
+     * E017).
+     */
+    assumeEngineVersion?: string;
     /**
      * Driver-module injection for the networked target forms (URL / host+port):
      * bypasses the dynamic `import('@zvndev/powdb-client')` and uses this object