turbine-orm 0.76.0 → 0.77.0

package/dist/cjs/powdb.d.ts

@@ -56,7 +56,9 @@ import { type PgCompatPool, type PgCompatPoolClient, TurbineClient, type Turbine
 import { type Dialect } from './dialect.js';
 import type { EngineClientConfig } from './engine-config.js';
 import type { PowdbExec } from './powdb-introspect.js';
-import { type ColumnMetadata, type SchemaMetadata, type TableMetadata } from './schema.js';
+import { type PowdbCapabilities } from './powdb-shared.js';
+import { type SchemaMetadata } from './schema.js';
+export { ALL_POWDB_CAPABILITIES, coerceNativeValue, coerceValue, isJsonColumn, isPowdbDatetimeColumn, isStaleFramePowdbError, POWQL_KEYWORDS, type PowdbCapabilities, PowdbFloatParam, PowdbJsonParam, type PowqlType, powqlColumnType, quotePowqlDotted, quotePowqlIdent, requireCapability, rowToEntity, } from './powdb-shared.js';
 /**
  * Capability descriptor for PowDB. PowQL generation is owned by
  * {@link PowqlInterface} (not the SQL `Dialect`), so this dialect exists only to
@@ -82,33 +84,6 @@ import { type ColumnMetadata, type SchemaMetadata, type TableMetadata } from './
 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);
-}
-/**
- * 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;
-    readonly column?: string | undefined;
-    /** `column` is diagnostic only: it names the target column when serialization fails. */
-    constructor(value: unknown, column?: string | undefined);
-}
 /** The four shapes a PowQL result takes over the legacy string wire. */
 type PowdbResult = {
     kind: 'rows';
@@ -239,92 +214,6 @@ export declare function parsePowdbUrl(connectionString: string): PowdbConnOption
  * prove it is too old).
  */
 export declare function assertSupportedPowdbVersion(version: string | undefined): void;
-/**
- * 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;
-    /** ≥ 0.13: server-side joins, hash-accelerated and bounded. */
-    serverJoins: boolean;
-    /**
-     * ≥ 0.18: nested projections (shaped results), a projection field may be a
-     * whole correlated child query returning a per-parent JSON array. When set,
-     * eligible `with` clauses compile into the parent statement instead of the
-     * batched loaders.
-     */
-    nestedProjections: boolean;
-    /**
-     * ≥ 0.19: entity links (`link` DDL, scalar/block traversal). Capability is
-     * recognized (probe-only), but query generation deliberately does NOT consume
-     * links yet: turbine keeps composing its own nested projections (see the
-     * PowDB engine page for the rationale). Declaring a link permanently upgrades
-     * the on-disk catalog to v7, so this stays FALSE in ALL_POWDB_CAPABILITIES.
-     */
-    entityLinks: boolean;
-    /**
-     * ≥ 0.19.1: link INTROSPECTION, the `schema links` listing statement and the
-     * appended link rows in `describe <T>`. Only meaningful when probed (there is
-     * no query-generation flip behind it), so it stays FALSE in
-     * ALL_POWDB_CAPABILITIES like the other probe-only gates. Floored at the PATCH
-     * 0.19.1: the listing statement shipped there, not in 0.19.0.
-     */
-    linkIntrospection: boolean;
-    /**
-     * ≥ 0.19.1: scalar to-one link PATHS in query generation. Floored at the PATCH
-     * 0.19.1 (never 0.19.0) because 0.19.0 had silent-wrong-results link bugs
-     * (bare-dotted-path split, wrong aggregates over links) that make traversal
-     * unsafe; 0.19.1 turned those into hard errors. This flag flips real query
-     * generation (a to-one `with` whose child carries bigint/bytes compiles to
-     * link-path projections instead of a loader), so it stays FALSE in
-     * ALL_POWDB_CAPABILITIES: it must only light up behind a real version probe.
-     */
-    linkPaths: boolean;
-    /**
-     * ≥ 0.20: a comparison between a `datetime` column and an integer timestamp
-     * literal evaluates as microseconds. Below 0.20 that pairing was unhandled and
-     * fell back to comparing TYPE TAGS (every DateTime sorted above every Int), so
-     * `>` matched every non-null row, `=` and `<` matched none, and the answer
-     * additionally depended on whether the column carried an index. Turbine binds
-     * a JS `Date` as int micros, so that is exactly the shape it emits: every
-     * datetime predicate was silently wrong on an older engine.
-     *
-     * The `in` / `not in` LIST form is a separate, still-open engine bug that 0.20
-     * did NOT fix, so this flag does not unlock it: a datetime `in` list is
-     * COMPILED AWAY into the equality chain the engine does answer correctly (see
-     * `PowqlInterface.buildInList`). That expansion needs working binary
-     * comparisons, so it too sits behind this flag.
-     *
-     * Predominantly a refusal gate, but the `in` rewrite makes it a (bounded)
-     * generation flip as well. It stays ON in {@link ALL_POWDB_CAPABILITIES}
-     * anyway: with the flag OFF the datetime paths do not fall back to some other
-     * SQL, they refuse outright, so a hand-constructed pool defaulting to OFF
-     * would break datetime queries that work rather than protect anything.
-     */
-    datetimeCompare: boolean;
-    /**
-     * ≥ 0.20: `count(T { .col })` counts non-null values of `.col` (SQL's
-     * `COUNT(col)`), which is what Turbine's per-field `_count` means. Below 0.20
-     * both frontends ignored the projection and returned the ROW count, so
-     * `aggregate({ _count: { field: true } })` silently disagreed with every SQL
-     * engine on a nullable column. `count(T)` / `_count: true` is unaffected on
-     * every version. Refusal-only gate (the emitted PowQL does not change).
-     */
-    projectedCountNonNull: boolean;
-    /** Networked only: server ≥ 0.13 AND the client exposes `queryNativeRaw`. */
-    nativeRaw: boolean;
-}
 /**
  * PowQL's parser bounds the SHAPE of the AST it produces, not just its own
  * recursion: an `and` / `or` chain is parsed iteratively but re-wraps its
@@ -353,35 +242,6 @@ export interface PowdbCapabilities {
  * powql.ts.
  */
 export declare const POWQL_MAX_NESTING_DEPTH = 64;
-/** The feature-gate capability keys (everything except the version/nativeRaw metadata). */
-type PowdbFeatureKey = 'jsonDocs' | 'docFieldIndexes' | 'introspection' | 'serverJoins' | 'nestedProjections' | 'entityLinks' | 'linkIntrospection' | 'linkPaths' | 'datetimeCompare' | 'projectedCountNonNull';
-/**
- * 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. `nestedProjections` stays OFF for
- * the same reason: it changes the generated PowQL for every `with` query, and
- * an unprobed engine below 0.18 would reject the syntax outright.
- * `entityLinks` stays OFF for a stronger reason still: declaring a link
- * one-way-upgrades the on-disk catalog to v7 and locks out pre-0.19 binaries,
- * so it must only ever light up behind a real version probe.
- * `linkIntrospection` / `linkPaths` stay OFF for the same probe-only discipline:
- * `linkPaths` flips real query generation (a to-one `with` compiling to link
- * projections), and `linkIntrospection` is only meaningful once genuinely
- * probed, so both must come from a real version resolution, never a bare
- * construction.
- * `datetimeCompare` / `projectedCountNonNull` stay ON here for the same
- * trusted-caller reason as `jsonDocs` and `serverJoins`. Neither is a fallback
- * gate: with the flag OFF the affected query is REFUSED, not served by some
- * other statement, so defaulting them off would break working queries rather
- * than protect anything. Every path that can learn the engine version
- * (`turbinePowDB`, embedded or networked) resolves them from a real probe; this
- * fallback only covers a hand-constructed or injected pool, whose owner is
- * asserting the engine is current.
- */
-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
@@ -391,117 +251,6 @@ export declare const ALL_POWDB_CAPABILITIES: PowdbCapabilities;
 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.
- *
- * The error's first sentence already names the feature (`<feature> is
- * unsupported on "PowDB".`), so the hint says "Requires PowDB >= x" rather than
- * repeating the label: a long feature description read twice in one message
- * (`per-field \`_count\` … is unsupported … per-field \`_count\` … requires …`)
- * buries the version floor that is the actionable part.
- *
- * `extra` appends one more sentence for gates that have a workaround worth
- * naming (e.g. the read path that answers the same query without the gated
- * comparison).
- */
-export declare function requireCapability(caps: PowdbCapabilities, key: PowdbFeatureKey, feature: string, extra?: 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 (non-json) and bytes columns throw, they have no PowDB equivalent.
- */
-export declare function powqlColumnType(col: ColumnMetadata): PowqlType;
-/**
- * Is this column stored in PowDB's NATIVE `datetime` type (as opposed to the
- * `int` epoch micros Turbine's own DDL emits for a `Date` column)?
- *
- * Only the literal PowQL type name counts. `powqlColumnType` never returns
- * `datetime`, so a Turbine-provisioned table can never have one; the shapes that
- * do are a table created outside Turbine and read back through
- * `introspectPowdbDatabase` (which maps `datetime` → `{ tsType: 'Date',
- * dialectType: 'datetime' }`), or hand-written metadata declaring it. Deliberately
- * strict: a Postgres-sourced `timestamptz` column is DDL'd as PowQL `int`, so it
- * is NOT a PowDB datetime and must not be caught here.
- *
- * Matters because comparing a datetime column against the integer timestamp
- * literal Turbine binds was silently wrong below engine 0.20 (see
- * {@link PowdbCapabilities.datetimeCompare}).
- */
-export declare function isPowdbDatetimeColumn(col: ColumnMetadata): boolean;
-/**
- * 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`. A server-generated
- * column ({@link ColumnMetadata.isGenerated}) that maps to PowQL `int` gets the
- * `auto` modifier, so PowDB assigns a monotonic id on insert and Turbine stops
- * synthesizing a client-side value for it.
- */
-/**
- * PowQL reserved words, the v0.10 lexer keyword table from POWQL.md's
- * "Reserved Words and Quoting" section, including the v0.10 additions
- * `schema` and `describe`. Keyword matching is case-sensitive in the lexer,
- * so only the exact lowercase form collides.
- */
-export declare const POWQL_KEYWORDS: ReadonlySet<string>;
-/**
- * Backtick-quote an identifier when PowQL would otherwise lex it as a keyword
- * (or when it contains characters outside the bare-identifier grammar).
- * Applied only in bare-identifier positions, DDL type/field names, index DDL,
- * and `insert`/`update`/`upsert` assignment targets. Dotted references
- * (`.col` in filters/projections/ordering) bypass keyword lookup on every
- * engine version and deliberately stay bare for ≤0.9 compatibility. Backticks
- * parse on PowDB ≥ 0.10; on older engines these names were already parse
- * errors when emitted bare, so quoting is strictly an improvement.
- */
-export declare function quotePowqlIdent(name: string): string;
-/**
- * The DOTTED-position spelling of {@link quotePowqlIdent}: quote a name that
- * falls outside the bare-identifier grammar, and only that.
- *
- * A dotted reference (`.col` in a filter, projection, `order`, `group`, or an
- * `upsert on`) bypasses keyword lookup, so `.order` parses on every engine
- * version and stays bare here, which is the ≤0.9 compatibility decision
- * {@link quotePowqlIdent} documents and which this must not undo.
- *
- * What it does NOT excuse is interpolating the name RAW, which is what these
- * sites used to do. Keyword-ness is a parsing question; a name outside
- * `POWQL_BARE_IDENT` is a statement-integrity one, and that name is the only
- * thing that can carry PowQL syntax into a statement whose values are all bound
- * as `$N` params. Reaching it needs a hostile column name (an introspected
- * database, a generator, a migration authored elsewhere) since names come from
- * schema metadata, but "the names are trusted" is not the invariant the rest of
- * this engine is written to. So: bare when the grammar allows it (byte-identical
- * output for every ordinary and every keyword name), quoted when it does not,
- * where the bare form was a parse error anyway. Verified against the engine that
- * a quoted dotted reference parses everywhere the bare one does and yields the
- * same result-column name.
- */
-export declare function quotePowqlDotted(name: string): string;
 /**
  * Options for {@link powqlSchemaDDL}. Additive: with no options the DDL is
  * emitted unconditionally (pure-function callers / tests); pass `capabilities`
@@ -561,6 +310,15 @@ export interface PowdbDesiredLink {
 export declare function deriveDesiredLinks(schema: SchemaMetadata, onCollision?: (owner: string, name: string) => void): PowdbDesiredLink[];
 /** Render one {@link PowdbDesiredLink} as its create-only `link ...` DDL statement. */
 export declare function powdbLinkStatement(link: PowdbDesiredLink): string;
+/**
+ * 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`. A server-generated
+ * column ({@link ColumnMetadata.isGenerated}) that maps to PowQL `int` gets the
+ * `auto` modifier, so PowDB assigns a monotonic id on insert and Turbine stops
+ * synthesizing a client-side value for it.
+ */
 export declare function powqlSchemaDDL(schema: SchemaMetadata, opts?: PowqlSchemaDDLOptions): string[];
 /**
  * Existence-checked apply of entity-link DDL against a LIVE PowDB database.
@@ -583,41 +341,6 @@ export declare function powqlSchemaDDL(schema: SchemaMetadata, opts?: PowqlSchem
 export declare function applyPowdbLinks(exec: PowdbExec, schema: SchemaMetadata, options?: {
     capabilities?: PowdbCapabilities;
 }): Promise<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;
-/**
- * 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.
- *
- * A date cell can also arrive as a DIGIT STRING: a nested-projection block's
- * children ride a JSON array, and micros exceed `Number.MAX_SAFE_INTEGER`'s
- * decimal comfort, so the engine renders them as a JSON string. Before that
- * string was parsed here, a nested `with` handed back the raw micros text while
- * the batched loader and the native join both handed back a `Date` (the same
- * relation, three answers). Only an all-digit string is parsed; any other text
- * on a date column passes through untouched.
- */
-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, native?: boolean): Record<string, unknown>;
 /**
  * Translate a PowDB error into a typed Turbine error. Handles BOTH transports,
  * whose error shapes differ:
@@ -635,16 +358,6 @@ export declare function rowToEntity(raw: Record<string, unknown>, meta: TableMet
  * 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;