turbine-orm 0.81.0 → 0.90.0

package/dist/cjs/pipeline-submittable.js

@@ -22,10 +22,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.pipelineClientNeedsDiscard = pipelineClientNeedsDiscard;
+exports.batchMayWrite = batchMayWrite;
 exports.runPipelined = runPipelined;
 exports.supportsExtendedPipeline = supportsExtendedPipeline;
 const _pg_1 = __importDefault(require("pg"));
 const errors_js_1 = require("./errors.js");
+const transaction_state_js_1 = require("./transaction-state.js");
 // Read off pg's own module object (`pg.Result` IS `pg/lib/result`, `pg.utils`
 // IS `pg/lib/utils`) rather than imported by subpath, so the whole driver comes
 // through the one `#pg` alias that edge bundles swap out (see src/pg-edge.ts).
@@ -94,6 +96,16 @@ function restoreListeners(emitter, snapshot) {
 // ---------------------------------------------------------------------------
 // Core pipeline execution
 // ---------------------------------------------------------------------------
+/** A statement that only reads: its transform may run after COMMIT, since there is nothing to undo. */
+const READ_ONLY_STATEMENT = /^\s*select\b/i;
+/**
+ * Whether a transactional batch must hold its COMMIT until the transforms have
+ * run. Anything that is not a plain SELECT counts as a write, so a statement
+ * this cannot classify costs a round trip rather than correctness.
+ */
+function batchMayWrite(queries) {
+    return queries.some((q) => !READ_ONLY_STATEMENT.test(q.sql));
+}
 /**
  * Execute multiple queries using the Postgres extended-query pipeline protocol.
  *
@@ -120,11 +132,20 @@ async function runPipelined(client, queries, options = {}) {
         // State machine
         // -----------------------------------------------------------------------
         /**
-         * Total expected commandComplete events:
-         * - Transactional: BEGIN + N queries + COMMIT = N + 2
-         * - Non-transactional: N queries
+         * True when the batch is sent as BEGIN + queries + Sync and the COMMIT
+         * follows only once every transform has succeeded (see
+         * {@link PipelineRunOptions.transactional}).
          */
-        const totalCommands = transactional ? queries.length + 2 : queries.length;
+        const holdCommit = transactional && batchMayWrite(queries);
+        /**
+         * Where the exchange is: the batch itself, or the single follow-up
+         * statement (the held COMMIT, or the recovery ROLLBACK) sent after it.
+         */
+        let phase = 'batch';
+        /** The command tag the held COMMIT came back with (`ROLLBACK` when the server rolled back). */
+        let commitTag;
+        /** Transformed results, computed before a held COMMIT is sent. */
+        let transformed;
         /**
          * Expected readyForQuery events:
          * - Transactional: 1 (single Sync at end)
@@ -150,20 +171,17 @@ async function runPipelined(client, queries, options = {}) {
         let cleaned = false;
         /** Transaction status reported by the most recent ReadyForQuery. */
         let txStatus;
-        /** Whether the recovery ROLLBACK has already been sent (it is sent at most once). */
-        let rollbackSent = false;
         /**
          * Map commandComplete index to the corresponding results[] index.
          * In transactional mode: index 0 = BEGIN, 1..N = queries, N+1 = COMMIT
-         * In non-transactional mode: index maps 1:1
+         * (absent when the COMMIT is held). In non-transactional mode: 1:1.
+         * Follow-up statements belong to no query.
          */
         function commandToQueryIndex(cmdIdx) {
-            if (transactional) {
-                if (cmdIdx === 0 || cmdIdx === totalCommands - 1)
-                    return null;
-                return cmdIdx - 1;
-            }
-            return cmdIdx;
+            if (phase !== 'batch')
+                return null;
+            const qIdx = transactional ? cmdIdx - 1 : cmdIdx;
+            return qIdx >= 0 && qIdx < queries.length ? qIdx : null;
         }
         /** Get the current query-results index for row data */
         function currentQueryIndex() {
@@ -222,30 +240,56 @@ async function runPipelined(client, queries, options = {}) {
                 return true;
             if (txStatus === undefined && !(transactional && pipelineError))
                 return true;
-            if (!transactional || rollbackSent) {
-                // Either nothing to roll back (non-transactional mode opens no
-                // transaction of its own), or the rollback already ran and did not
-                // clear the status. Hand the client back marked for disposal.
-                if (txStatus === 'E' || txStatus === 'T') {
-                    Object.defineProperty(client, PIPELINE_DISCARD, { value: true, enumerable: false, configurable: true });
-                }
+            if (!transactional) {
+                // Non-transactional mode opens no transaction of its own, so there is
+                // nothing to roll back. Hand the client back marked for disposal.
+                markDiscardIfInTransaction();
                 return true;
             }
-            rollbackSent = true;
+            return !sendFollowUp('ROLLBACK', 'rollback');
+        }
+        /** Mark the client for disposal when the backend still reports an open or failed transaction. */
+        function markDiscardIfInTransaction() {
+            if (txStatus === 'E' || txStatus === 'T') {
+                Object.defineProperty(client, PIPELINE_DISCARD, { value: true, enumerable: false, configurable: true });
+            }
+        }
+        /**
+         * Send one statement after the batch (the held COMMIT or the recovery
+         * ROLLBACK) with its own Sync; its ReadyForQuery finishes the exchange.
+         * Returns false when the socket would not take it, in which case the
+         * connection is marked for disposal, since it cannot be repaired from here.
+         */
+        function sendFollowUp(text, next) {
+            phase = next;
             try {
-                connection.parse({ text: 'ROLLBACK', name: '' });
-                connection.bind({ portal: '', statement: '', values: [], valueMapper: prepareValue });
-                connection.execute({ portal: '', rows: 0 });
-                connection.sync();
-                return false;
+                connection.stream.cork?.();
+                try {
+                    connection.parse({ text, name: '' });
+                    connection.bind({ portal: '', statement: '', values: [], valueMapper: prepareValue });
+                    connection.execute({ portal: '', rows: 0 });
+                    connection.sync();
+                }
+                finally {
+                    connection.stream.uncork?.();
+                }
+                return true;
             }
-            catch {
-                // The socket would not take the rollback, so this connection cannot be
-                // repaired from here. Mark it and let the caller drop it.
+            catch (err) {
                 Object.defineProperty(client, PIPELINE_DISCARD, { value: true, enumerable: false, configurable: true });
-                return true;
+                if (!pipelineError)
+                    pipelineError = err instanceof Error ? err : new Error(String(err));
+                return false;
             }
         }
+        /** Run every query's transform, in order; the first throw propagates. */
+        function transformAll() {
+            const out = [];
+            for (let i = 0; i < queries.length; i++) {
+                out.push(queries[i].transform(results[i]));
+            }
+            return out;
+        }
         function finalize() {
             cleanup();
             if (transactional && pipelineError) {
@@ -288,14 +332,14 @@ async function runPipelined(client, queries, options = {}) {
                 }));
                 return;
             }
-            // All succeeded, transform results
-            try {
-                const transformed = [];
-                for (let i = 0; i < queries.length; i++) {
-                    const q = queries[i];
-                    transformed.push(q.transform(results[i]));
-                }
+            // All succeeded. A held COMMIT ran the transforms before committing;
+            // a read-only batch runs them now (there is nothing to undo).
+            if (transformed) {
                 resolve(transformed);
+                return;
+            }
+            try {
+                resolve(transformAll());
             }
             catch (err) {
                 reject(err);
@@ -328,6 +372,8 @@ async function runPipelined(client, queries, options = {}) {
             }
         }
         function onCommandComplete(msg) {
+            if (phase === 'commit')
+                commitTag = msg.command ?? msg.text;
             const qIdx = currentQueryIndex();
             if (qIdx !== null && qIdx >= 0 && qIdx < results.length) {
                 results[qIdx].addCommandComplete(msg);
@@ -374,15 +420,41 @@ async function runPipelined(client, queries, options = {}) {
         }
         function onReadyForQuery(msg) {
             txStatus = msg?.status;
-            // The recovery ROLLBACK's own ReadyForQuery is not one of the batch's, so
+            // A follow-up statement's own ReadyForQuery is not one of the batch's, so
             // it must not advance the counter that decides when the batch is done.
-            if (rollbackSent) {
+            if (phase === 'rollback') {
+                markDiscardIfInTransaction();
+                finalize();
+                return;
+            }
+            if (phase === 'commit') {
+                // PostgreSQL answers COMMIT in a failed transaction with the tag
+                // ROLLBACK and no error. Nothing here sends COMMIT after an error, but
+                // the answer is checked rather than assumed.
+                if (!pipelineError && commitTag === 'ROLLBACK')
+                    pipelineError = (0, transaction_state_js_1.rolledBackError)(undefined, 'transaction');
+                markDiscardIfInTransaction();
                 finalize();
                 return;
             }
             rfqCount++;
             if (rfqCount < expectedRfq)
                 return;
+            if (holdCommit && !pipelineError && txStatus !== 'E') {
+                try {
+                    transformed = transformAll();
+                }
+                catch (err) {
+                    // A transform refused its result: roll the batch's writes back.
+                    pipelineError = err instanceof Error ? err : new Error(String(err));
+                    if (!sendFollowUp('ROLLBACK', 'rollback'))
+                        finalize();
+                    return;
+                }
+                if (!sendFollowUp('COMMIT', 'commit'))
+                    finalize();
+                return;
+            }
             if (settleTransactionState())
                 finalize();
         }
@@ -429,7 +501,8 @@ async function runPipelined(client, queries, options = {}) {
             if (transactional) {
                 // ---- Transactional mode ----
                 // BEGIN + N×(parse+bind+describe+execute) + COMMIT + sync
-                // One sync = one ReadyForQuery
+                // One sync = one ReadyForQuery. A batch that may write leaves the
+                // COMMIT out here and sends it after the transforms (holdCommit).
                 // BEGIN
                 connection.parse({ text: 'BEGIN', name: '' });
                 connection.bind({ portal: '', statement: '', values: [], valueMapper: prepareValue });
@@ -446,10 +519,11 @@ async function runPipelined(client, queries, options = {}) {
                     connection.describe({ type: 'P', name: '' });
                     connection.execute({ portal: '', rows: 0 });
                 }
-                // COMMIT
-                connection.parse({ text: 'COMMIT', name: '' });
-                connection.bind({ portal: '', statement: '', values: [], valueMapper: prepareValue });
-                connection.execute({ portal: '', rows: 0 });
+                if (!holdCommit) {
+                    connection.parse({ text: 'COMMIT', name: '' });
+                    connection.bind({ portal: '', statement: '', values: [], valueMapper: prepareValue });
+                    connection.execute({ portal: '', rows: 0 });
+                }
                 // Single Sync
                 connection.sync();
             }

package/dist/cjs/pipeline.js

@@ -22,10 +22,21 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.executePipeline = executePipeline;
 exports.pipelineSupported = pipelineSupported;
+const checkout_js_1 = require("./checkout.js");
 const connection_guard_js_1 = require("./connection-guard.js");
 const dialect_js_1 = require("./dialect.js");
 const errors_js_1 = require("./errors.js");
 const pipeline_submittable_js_1 = require("./pipeline-submittable.js");
+const transaction_state_js_1 = require("./transaction-state.js");
+/**
+ * Run one deferred query on the batch's connection. An engine without
+ * RETURNING (MySQL) attaches a `reselect` plan that runs the write and then
+ * fetches its row; sending `q.sql` alone would hand the transform a row-less
+ * result, which a single-row write reads as "not found".
+ */
+function runOne(client, q) {
+    return q.reselect ? q.reselect((sql, params) => client.query(sql, params)) : client.query(q.sql, q.params);
+}
 /**
  * Execute queries sequentially on an already-acquired connection.
  * This is the fallback path for clients that don't support the extended-query
@@ -55,19 +66,16 @@ async function runSequential(client, queries, dialect, options = {}) {
         for (const q of queries) {
             let raw;
             try {
-                raw = await client.query(q.sql, q.params);
+                raw = await runOne(client, q);
             }
             catch (err) {
                 throw (0, errors_js_1.wrapPgError)(err);
             }
+            // Transformed BEFORE the COMMIT, so a transform that refuses its result
+            // (a `...OrThrow` miss, an optimistic-lock conflict) rolls the batch back.
             results.push(q.transform(raw));
         }
-        try {
-            await client.query(dialect.commitStatement());
-        }
-        catch (err) {
-            throw (0, errors_js_1.wrapPgError)(err);
-        }
+        await (0, transaction_state_js_1.commitTransaction)(client, dialect.commitStatement());
         return results;
     }
     catch (err) {
@@ -145,7 +153,7 @@ async function runIndependent(client, queries) {
         const q = queries[i];
         let raw;
         try {
-            raw = await client.query(q.sql, q.params);
+            raw = await runOne(client, q);
         }
         catch (err) {
             const wrapped = (0, errors_js_1.wrapPgError)(err);
@@ -192,24 +200,11 @@ async function executePipeline(pool, queries, options) {
     if (queries.length === 0) {
         return [];
     }
-    // Acquire a single client, reused for both capability check and execution.
-    // The checkout is wrapped because a connection-level failure (28P01 wrong
-    // password, an unverifiable TLS cert, ECONNREFUSED) happens HERE, before any
-    // query runs. Unwrapped it escapes as a raw pg DatabaseError whose `.code`
-    // holds a SQLSTATE, which is the same property Turbine puts TURBINE_E0NN in,
-    // so a caller switching on `.code` silently receives a value from a foreign
-    // namespace. The transaction and nested-write checkouts were wrapped for this
-    // reason; this was the last sibling still bare.
-    let client;
-    try {
-        client = await pool.connect();
-    }
-    catch (err) {
-        throw (0, errors_js_1.wrapPgError)(err);
-    }
-    // Guarded for the checkout window, see connection-guard.ts: a connection that
-    // dies mid-batch emits 'error', which with no listener exits the process.
-    const checkout = (0, connection_guard_js_1.guardCheckout)(client);
+    // One client, reused for both capability check and execution. The shared
+    // checkout types a connection-level failure (wrong password, TLS, refused,
+    // an exhausted pool) and guards the checkout window: a connection that dies
+    // mid-batch emits 'error', which with no listener exits the process.
+    const { client, checkout } = await (0, checkout_js_1.acquireConnection)(pool);
     try {
         if ((0, pipeline_submittable_js_1.supportsExtendedPipeline)(client)) {
             // Real pipeline path, uses extended-query protocol wire methods

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

@@ -13,8 +13,8 @@
  * 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.
+ *   - Embedded / owned pool: `exec = async (q) => ({ rows: await db.rawUnsafe(q) })`
+ *     using a live `turbinePowDB` client.
  *   - 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[][]`
@@ -66,6 +66,7 @@
  * 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 TurbineLogger } from './logger.js';
 import { type PowdbCapabilities } from './powdb-shared.js';
 import type { SchemaMetadata } from './schema.js';
 /** A minimal rows-returning executor over a PowDB connection (embedded or networked). */
@@ -86,6 +87,8 @@ export interface PowdbIntrospectOptions {
      * to run ungated; the pool paths that know the version pass it through.
      */
     capabilities?: PowdbCapabilities;
+    /** Where a table without a usable primary key is reported. Defaults to the console logger. */
+    logger?: TurbineLogger;
 }
 /**
  * Read a live PowDB database into {@link SchemaMetadata} via `schema` +

package/dist/cjs/powdb-introspect.js

@@ -14,8 +14,8 @@
  * 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.
+ *   - Embedded / owned pool: `exec = async (q) => ({ rows: await db.rawUnsafe(q) })`
+ *     using a live `turbinePowDB` client.
  *   - 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[][]`
@@ -71,6 +71,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.introspectPowdbDatabase = introspectPowdbDatabase;
 const errors_js_1 = require("./errors.js");
 const introspect_js_1 = require("./introspect.js");
+const logger_js_1 = require("./logger.js");
 const powdb_shared_js_1 = require("./powdb-shared.js");
 const schema_js_1 = require("./schema.js");
 /** Coerce a wire cell to string (legacy wire cells are strings; native cells may be typed). */
@@ -136,7 +137,9 @@ async function introspectPowdbDatabase(exec, options = {}) {
     }
     // include / exclude + default bookkeeping-table exclusions (F12).
     const tableNames = (0, introspect_js_1.applyTableFilters)(candidateTables, options);
-    const tables = {};
+    // Keyed by catalog names, so prototype-less: a table or column named
+    // `__proto__`, `constructor` or `toString` is data, never a prototype member.
+    const tables = (0, introspect_js_1.nullRecord)();
     for (const tableName of tableNames) {
         // `describe` needs the table name in bare-identifier position → quote it so
         // a reserved-word / non-bare table name (`order`) does not become a parse
@@ -157,11 +160,11 @@ async function introspectPowdbDatabase(exec, options = {}) {
             index: asString(r.index),
         }));
         const columns = [];
-        const columnMap = {};
-        const reverseColumnMap = {};
+        const columnMap = (0, introspect_js_1.nullRecord)();
+        const reverseColumnMap = (0, introspect_js_1.nullRecord)();
         const dateColumns = new Set();
-        const dialectTypes = {};
-        const pgTypes = {};
+        const dialectTypes = (0, introspect_js_1.nullRecord)();
+        const pgTypes = (0, introspect_js_1.nullRecord)();
         const allColumns = [];
         const uniqueColumns = [];
         const indexes = [];
@@ -209,15 +212,17 @@ async function introspectPowdbDatabase(exec, options = {}) {
                 });
             }
         }
+        // Two columns resolving to one field would fold into one property on read.
+        (0, introspect_js_1.assertDistinctColumnFields)(tableName, columns);
         // Primary key: first non-nullable unique column, preferring one named `id`.
         let primaryKey = [];
         if (pkCandidates.length > 0) {
             primaryKey = [pkCandidates.includes('id') ? 'id' : pkCandidates[0]];
         }
         else {
-            console.warn(`[turbine] PowDB introspection: table "${tableName}" has no non-nullable unique column; ` +
+            (0, logger_js_1.logTo)(options.logger ?? logger_js_1.consoleLogger, 'warn', `PowDB introspection: table "${(0, introspect_js_1.printableCatalogName)(tableName)}" has no non-nullable unique column; ` +
                 'primaryKey is [] (single-row operations will fail). Supply a primary key via code-first ' +
-                '`defineSchema` metadata if this table needs findUnique/update/delete by id.');
+                '`defineSchema` metadata if this table needs findUnique/update/delete by id.', { code: 'powdb-introspect-no-primary-key', table: tableName });
         }
         tables[tableName] = {
             name: tableName,
@@ -233,7 +238,7 @@ async function introspectPowdbDatabase(exec, options = {}) {
             // Populated below from `schema links` when the engine supports link
             // introspection (>= 0.19.1); stays `{}` otherwise (PowDB has no declared
             // foreign keys, so pre-link introspection reports no relations).
-            relations: {},
+            relations: (0, introspect_js_1.nullRecord)(),
             indexes,
         };
     }
@@ -243,7 +248,7 @@ async function introspectPowdbDatabase(exec, options = {}) {
     if (options.capabilities?.linkIntrospection) {
         await introspectPowdbLinks(exec, tables);
     }
-    return { tables, enums: {} };
+    return { tables, enums: (0, introspect_js_1.nullRecord)() };
 }
 /**
  * Read `schema links` and populate {@link TableMetadata.relations}: the first
@@ -278,8 +283,8 @@ async function introspectPowdbLinks(exec, tables) {
         cardinality: asString(r.cardinality),
     }));
     for (const link of linkRows) {
-        const owner = tables[link.owner];
-        const target = tables[link.target];
+        const owner = Object.hasOwn(tables, link.owner) ? tables[link.owner] : undefined;
+        const target = Object.hasOwn(tables, link.target) ? tables[link.target] : undefined;
         // A link referencing a filtered-out (include/exclude) table is skipped: we
         // cannot describe the target, so the relation would be unusable.
         if (!owner || !target)
@@ -324,13 +329,13 @@ async function introspectPowdbLinks(exec, tables) {
 }
 /** True when `name` already names a relation OR a column field/name on `meta`. */
 function relationNameTaken(meta, name) {
-    if (meta.relations[name])
+    if (Object.hasOwn(meta.relations, name))
         return true;
     return meta.columns.some((c) => c.field === name || c.name === name);
 }
 /** Add a relation to a table's relations map (keyed by its camelCase name). */
 function addRelation(meta, rel) {
-    if (meta.relations[rel.name])
+    if (Object.hasOwn(meta.relations, rel.name))
         return; // never clobber an existing relation
     meta.relations[rel.name] = rel;
 }

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

@@ -233,15 +233,36 @@ export type PowqlType = 'str' | 'int' | 'float' | 'bool' | 'json';
  * asserts the equivalence over a corpus rather than asserting my reading of it.
  */
 export declare function baseTsType(tsType: string): string;
+/** A schema's enum types (`SchemaMetadata.enums`): type name to labels, in declaration order. */
+export type PowdbEnums = Readonly<Record<string, readonly string[]>>;
 /**
- * Does this column map to PowDB's native `json` document type? A Postgres
+ * The labels of the enum type this column is declared as, or `undefined` when
+ * it is not an enum column of `enums`.
+ *
+ * An enum column carries its TYPE NAME as `dialectType` / `pgType` and a
+ * `tsType` that says nothing useful (`unknown` from `defineSchema`, a union of
+ * the labels from introspection), so the column's own metadata cannot answer
+ * the question: the schema's `enums` map is the only authority. PowDB has no
+ * enum type, so such a column is a `str` holding the label text, which is what
+ * PostgreSQL stores and returns. Without this the tsType heuristic in
+ * {@link isJsonColumn} declared a `defineSchema` enum column as `json`, and
+ * writing a label failed as invalid JSON.
+ */
+export declare function powdbEnumLabels(col: ColumnMetadata, enums: PowdbEnums | undefined): readonly string[] | undefined;
+/**
+ * Does this column map to PowDB's native `json` document type? An enum column
+ * of `enums` never does (see {@link powdbEnumLabels}). 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}.
+ *
+ * `enums` is optional for callers outside Turbine; every call inside the
+ * engine passes the schema's map (a source scan in fx-powdb-r2.test.ts
+ * checks it).
  */
-export declare function isJsonColumn(col: ColumnMetadata): boolean;
+export declare function isJsonColumn(col: ColumnMetadata, enums?: PowdbEnums): boolean;
 /**
  * Map a Turbine column to the PowQL DDL type used in `defineSchema` →
  * `type T { … }`. Turbine never emits PowDB's `uuid`/`datetime`/`bytes` types,
@@ -249,10 +270,20 @@ export declare function isJsonColumn(col: ColumnMetadata): boolean;
  *   - `Date` → `int` (epoch micros)   - `boolean` → `bool`
  *   - integral `number`/`bigint` → `int`   - fractional `number` → `float`
  *   - JSON / object columns → `json` (native PowDB document type, ≥ 0.12)
+ *   - an enum column of `enums` → `str` (the label text)
  *   - 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;
+export declare function powqlColumnType(col: ColumnMetadata, enums?: PowdbEnums): PowqlType;
+/**
+ * Is this a `numeric` / `decimal` / `money` column that PowDB stores as `str`?
+ *
+ * A Postgres-sourced decimal surfaces as a JS string (so its digits survive),
+ * and PowDB has no decimal type, so the column is DDL'd as PowQL `str`. Every
+ * comparison, ordering and aggregate the engine runs on it is then a TEXT
+ * operation, which is why the query generator refuses those on such a column.
+ */
+export declare function isPowdbDecimalTextColumn(col: ColumnMetadata, enums?: PowdbEnums): boolean;
 /**
  * Is a column stored as `int` epoch micros but surfaced as a JS `Date`?
  *
@@ -325,7 +356,7 @@ export declare function quotePowqlDotted(name: string): string;
  * 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;
+export declare function coerceValue(raw: string, col: ColumnMetadata, enums?: PowdbEnums): 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`/
@@ -354,7 +385,7 @@ export declare function coerceNativeValue(value: unknown, col: ColumnMetadata):
  * 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>;
+export declare function rowToEntity(raw: Record<string, unknown>, meta: TableMetadata, native?: boolean, enums?: PowdbEnums): Record<string, unknown>;
 /**
  * True when `err` is the stale-wire-frame {@link ConnectionError} produced by
  * {@link wrapPowdbError} (its `.cause` is a `protocol_error` PowDBError, or the