node-firebird 2.11.0 → 2.12.0

package/README.md

@@ -13,7 +13,7 @@
 - [Promises and async/await](#promises-and-asyncawait) — the `*Async` API plus `withConnection` / `withTransaction` helpers
 - [Connection types](#connection-types) — connection options, `firebird://` URIs and traditional connection strings, classic connections, pooling
 - [Database object (db)](#database-object-db) — database, transaction and statement methods/options
-- [Examples](#examples) — parametrized queries, named placeholders, nested result tables (nestTables), custom type parsers (typeCast), BLOBs, streaming big data, transactions, driver events, database events (POST_EVENT), service manager, charsets/encoding, Firebird 3.0–6.0 features
+- [Examples](#examples) — parametrized queries, tagged-template queries (sql), named placeholders, nested result tables (nestTables), row-key transforms (transformKeys), result metadata / affected rows (withMeta), custom type parsers (typeCast), BLOBs, streaming big data, transactions, driver events, database events (POST_EVENT), service manager, charsets/encoding, Firebird 3.0–6.0 features
 - [Extensive Examples](#extensive-examples) — DECFLOAT/INT128, query cancellation (AbortSignal), batch execution (bulk inserts), statement timeouts, scrollable cursors, RETURNING multiple rows, SKIP LOCKED, advanced pooling
 - [Using node-firebird with Express.js](#using-node-firebird-with-expressjs)
 - [FAQ](#faq)
@@ -154,6 +154,14 @@ Notes:
 
 ### Connection options
 
+Settings you leave out fall back to environment variables first — using
+Firebird's own conventions (`ISC_USER` and `ISC_PASSWORD`, the same
+variables isql honours) plus `FIREBIRD_HOST`, `FIREBIRD_PORT`,
+`FIREBIRD_DATABASE` and `FIREBIRD_ROLE` — and to the built-in defaults
+below (SYSDBA / masterkey / 127.0.0.1) only after that. Explicitly
+provided options always win, so credentials can stay out of code the
+same way `PGUSER`/`PGPASSWORD` work with pg.
+
 ```js
 var options = {};
 
@@ -186,6 +194,7 @@ options.owner = undefined; // optional; owner of a newly created database — le
 options.jsonAsObject = false; // optional; automatically stringify parameters and parse query results that contain JSON (FB >= 6.0)
 options.namedPlaceholders = false; // set to true to allow :name placeholders in SQL with a { name: value } params object (see Named placeholders)
 options.nestTables = false; // true nests object rows by source table (row[table][column]); a string separator flattens to 'table<sep>column' keys — see Nested result tables (nestTables). Overridable per query
+options.transformKeys = undefined; // 'camel' (FIRST_NAME → firstName) or a (key) => key mapper for object-row keys — see Transforming row keys (transformKeys). Overridable per query
 options.typeCast = undefined; // optional; custom type parser called for every result column value (see Custom type parsers)
 options.statementCacheSize = 0; // optional; per-connection LRU cache of prepared statements, 0 = disabled (see Prepared-statement cache)
 ```
@@ -293,9 +302,11 @@ The pool is an `EventEmitter` and exposes live counters, following the
 ```js
 const pool = Firebird.pool(10, {
     ...options,
-    idleTimeoutMillis: 30000, // close connections idle for 30s…
-    min: 2,                   // …but always keep 2 alive
+    idleTimeoutMillis: 30000,   // close connections idle for 30s…
+    min: 2,                     // …but always keep 2 alive
     connectTimeout: 5000,
+    maxUses: 7500,              // retire a connection after 7500 checkouts (pg's maxUses)
+    maxLifetimeMillis: 3600000, // …or 1h after creation (Postgres.js's max_lifetime)
 });
 
 pool.on('connect', (db) => console.log('new server connection'));
@@ -318,6 +329,12 @@ console.log({
   connection they ever created (issue [#329](https://github.com/hgourvest/node-firebird/issues/329)).
   The sweep also evicts idle connections whose socket has died, so callers
   don't receive them after a server restart (issue [#343](https://github.com/hgourvest/node-firebird/issues/343)).
+- `maxUses` and `maxLifetimeMillis` **recycle** physical connections: a
+  worn-out or over-age connection is closed for good when returned to the
+  pool (lifetime is also enforced on idle connections by the sweep, even
+  below `min`) and a replacement is created on demand. Recycling bounds
+  server-side resource drift on long-lived connections. Both default to 0
+  (off).
 - `error` is a background-error channel (idle eviction failures and the
   like); unlike a plain `EventEmitter`, it is only emitted when a listener
   is attached, so existing applications keep working unchanged.
@@ -453,6 +470,63 @@ Firebird.attach(options, function (err, db) {
 });
 ```
 
+### Tagged-template queries (sql)
+
+`db.sql` / `transaction.sql` offer a Postgres.js-style tagged-template API
+on top of the regular parameter machinery. Interpolated values are bound
+as positional parameters — never concatenated into the SQL — so the API is
+injection-safe by construction:
+
+```js
+const id = 2;
+const rows = await db.sql`SELECT NAME FROM EMP WHERE ID = ${id}`;
+// → executes  SELECT NAME FROM EMP WHERE ID = ?  with params [2]
+```
+
+The returned query is a **lazy thenable**: it runs when awaited (or via
+`.then`/`.catch`/`.finally`), exactly once. Until then it can be embedded
+in another tag as a **fragment**, splicing its text and parameters in
+place:
+
+```js
+const filter = db.sql`DEPT_ID = ${1} AND ACTIVE = ${true}`;
+const rows = await db.sql`SELECT * FROM EMP WHERE ${filter} ORDER BY ID`;
+```
+
+Arrays expand to placeholder lists (for `IN`), and calling the tag with a
+string produces a safely quoted, dot-qualified **identifier** for dynamic
+table/column names:
+
+```js
+await db.sql`SELECT * FROM EMP WHERE ID IN (${[1, 2, 3]})`;
+
+const col = 'NAME';
+await db.sql`SELECT ${db.sql(col)} FROM ${db.sql('S1.EMP')}`;
+// → SELECT "NAME" FROM "S1"."EMP"
+```
+
+`.options({...})` attaches per-query options (`timeout`, `signal`,
+`nestTables`, …), `.withMeta()` executes resolving the
+[full result object](#result-metadata-and-affected-rows-withmeta), and
+`.toQuery()` returns the compiled `{ text, params }` without executing —
+handy for logging and tests:
+
+```js
+const r = await db.sql`UPDATE EMP SET ACTIVE = false WHERE ID = ${9}`.withMeta();
+// r.affectedRows === 1
+```
+
+Sharp edges, made loud instead of silent: a query executes once, in the
+shape of its first consumer — consuming it again in the *other* shape
+(plain `await` after `.withMeta()`, or vice versa) throws, as does
+`.options()` after execution. Interpolating an **empty array** throws
+(it would compile to invalid SQL like `IN ()`), and circular fragments
+are rejected instead of overflowing the stack. The compiled text is
+positional-only, so the [named placeholders](#named-placeholders)
+rewriter is disabled for tagged queries — PSQL `:variable` references
+in an `EXECUTE BLOCK` template are safe even with `namedPlaceholders:
+true` on the connection.
+
 ### Named placeholders
 
 With the `namedPlaceholders: true` connection option, SQL may use `:name`
@@ -537,6 +611,76 @@ array rows are positional and need no qualification. Works on every
 supported Firebird version (the source-table metadata comes from the
 statement describe, available since Firebird 2.0).
 
+### Transforming row keys (transformKeys)
+
+`transformKeys` rewrites object-row keys — the counterpart of
+Postgres.js's `transform`. The built-in `'camel'` maps `FIRST_NAME` →
+`firstName`; a custom `(key) => key` mapper gives full control. Accepted
+at connection level and per query (per-query wins):
+
+```js
+const rows = await db.queryAsync('SELECT EMP_ID, FIRST_NAME FROM EMP_INFO', [],
+  { transformKeys: 'camel' });
+// rows[0] = { empId: 1, firstName: 'Ada' }
+```
+
+The transform runs after `lowercase_keys` and applies to both parts of
+[`nestTables`](#nested-result-tables-nesttables) keys (`row.e.empId`).
+Column *metadata* — `withMeta` `fields` and the `typeCast` hook — keeps
+the raw server aliases. A custom mapper that throws falls back to the
+untransformed key (with a console warning) rather than corrupting the
+row decode.
+
+### Result metadata and affected rows (withMeta)
+
+By default, queries deliver bare rows and DML row counts are not reported.
+The per-query `withMeta: true` option switches the result (callback and
+promise APIs alike) to a full result object, the counterpart of pg's
+`{ rows, rowCount, fields }` and mysql2's `affectedRows`:
+
+```js
+const r = await db.queryAsync('UPDATE EMP SET ACTIVE = false WHERE DEPT_ID = ?', [1],
+  { withMeta: true });
+// r = {
+//   rows: undefined,            // rows array (SELECT), row object (RETURNING), or undefined
+//   fields: [...],              // per-column metadata (see below)
+//   affectedRows: 2,            // what the server actually changed
+//   recordCounts: { selectCount: 0, insertCount: 0, updateCount: 2, deleteCount: 0 },
+//   warnings: [],               // isc_arg_warning entries from the execute response
+// }
+```
+
+For DML (`INSERT`/`UPDATE`/`DELETE`, including `... RETURNING` and
+`EXECUTE PROCEDURE`), `affectedRows` is the server-reported count
+(`isc_info_sql_records`) and `recordCounts` breaks it down per verb — this
+costs one extra lightweight info request per statement, which is why the
+option is opt-in. For `SELECT`, `affectedRows` is simply the number of rows
+returned (pg's `rowCount` convention) with no extra round-trip, and
+`recordCounts` is absent.
+
+Each entry in `fields` describes one output column — the same vocabulary
+the [typeCast hook](#custom-type-parsers-typecast) receives, plus
+nullability and the relation alias/schema:
+
+```js
+{ type: 448, typeName: 'VARYING', subType: 4, scale: 0, length: 80,
+  nullable: true, field: 'NAME', relation: 'EMP', relationAlias: '',
+  relationSchema: 'PUBLIC', alias: 'NAME' }
+```
+
+(`relationSchema` is filled on Firebird 6.0+; `subType` of a text column is
+its character-set id.) In TypeScript, `queryAsync<T>(sql, params,
+{ withMeta: true })` resolves to `QueryResult<T>` automatically. Server
+warnings attached to any response — not just queries — are also emitted as
+[`'warning'` driver events](#driver-events).
+
+The option is honoured by `query`/`execute` (and their `*Async` wrappers),
+on databases and transactions alike. It is ignored by the streaming APIs
+(`sequentially`, `queryStream` — rows bypass the result there) and by
+`executeBatch` (which has its own completion shape). For `EXECUTE
+PROCEDURE`, `affectedRows` reflects DML the procedure performed — a
+procedure that only returns values reports 0 alongside its row.
+
 ### Custom type parsers (typeCast)
 
 The `typeCast` connection option lets you override how column values are
@@ -1009,6 +1153,41 @@ Firebird.attach(options, function (err, db) {
 });
 ```
 
+#### Savepoints
+
+`transaction.savepoint(work)` runs `work` inside a savepoint (Firebird
+1.5+): on resolve the savepoint is **released**, on reject the transaction
+**rolls back to the savepoint** — undoing only `work`'s changes — and the
+error is rethrown while the transaction itself stays usable. Calls nest;
+names are generated automatically. This is the counterpart of
+Postgres.js's `sql.savepoint()` and mirrors `db.withTransaction`'s style:
+
+```js
+await db.withTransaction(async (tx) => {
+  await tx.sql`INSERT INTO ORDERS VALUES (${1}, ${'paid'})`;
+
+  try {
+    await tx.savepoint(async () => {
+      await tx.sql`INSERT INTO AUDIT VALUES (${1}, ${'optional enrichment'})`;
+      await maybeFailingStep(tx);
+    });
+  } catch (err) {
+    // the AUDIT insert is undone; the ORDERS insert survives and the
+    // transaction continues toward commit
+  }
+});
+```
+
+If the rollback-to itself fails (e.g. the connection died), the original
+error is still thrown, with the rollback failure attached as
+`err.savepointRollbackError`. A release failure does **not** roll the
+work back — only a `work` failure does.
+
+> **Note:** do not run sibling savepoints concurrently on one transaction
+> (`Promise.all`): Firebird's `RELEASE SAVEPOINT` also releases every
+> savepoint created after it, so interleaved siblings would release each
+> other. Nested (awaited) savepoints are fine.
+
 ### Driver Events
 
 Driver events are synchronous notifications emitted on the `Database` object for connection-level operations. Subscribe with `db.on(eventName, handler)`.
@@ -1060,6 +1239,15 @@ Firebird.attach(options, function (err, db) {
     // rows === Array
   });
 
+  db.on('warning', function (warning) {
+    // fired (next tick) for every isc_arg_warning the server attaches to a
+    // successful response — e.g. "parallel workers value capped" when
+    // parallelWorkers exceeds the server maximum. The listener above is
+    // registered inside the attach callback and still catches attach-time
+    // warnings, because emission is deferred by one tick.
+    // warning === { gdscode: Number, params?: Array, message: String }
+  });
+
   db.detach();
 });
 ```

package/lib/pool.d.ts

@@ -22,7 +22,12 @@ type AttachFn = (options: any, callback: Callback) => void;
  *
  * Options: max (factory argument), options.min (floor the reaper never
  * shrinks below), options.idleTimeoutMillis (close idle connections after
- * this many ms; 0/absent = never), options.connectTimeout.
+ * this many ms; 0/absent = never), options.connectTimeout,
+ * options.maxUses (retire a connection after this many checkouts — pg's
+ * maxUses), options.maxLifetimeMillis (retire a connection this many ms
+ * after it was created — Postgres.js's max_lifetime). Retirement happens
+ * when the connection is returned to the pool, and the sweep also closes
+ * over-lifetime idle connections; a replacement is created on demand.
  */
 declare class Pool extends Events.EventEmitter {
     attach: AttachFn;
@@ -33,11 +38,19 @@ declare class Pool extends Events.EventEmitter {
     max: number;
     min: number;
     idleTimeoutMillis: number;
+    maxUses: number;
+    maxLifetimeMillis: number;
     pending: Callback[];
     options: any;
     _destroyed: boolean;
     _reaper: NodeJS.Timeout | null;
     constructor(attach: AttachFn, max: number, options: any);
+    /** True when the connection exceeded maxUses / maxLifetimeMillis.
+     *  Both stamps are set unconditionally when the pool creates the
+     *  connection, so they can be read bare here. */
+    _isExpired(db: any): boolean;
+    /** Close a healthy pooled connection for good (reaper/retirement path). */
+    _retire(db: any): void;
     /** Physical connections owned by the pool (idle + in use). */
     get totalCount(): number;
     /** Connections sitting idle in the pool. */

package/lib/pool.js

@@ -25,7 +25,12 @@ const callback_1 = require("./callback");
  *
  * Options: max (factory argument), options.min (floor the reaper never
  * shrinks below), options.idleTimeoutMillis (close idle connections after
- * this many ms; 0/absent = never), options.connectTimeout.
+ * this many ms; 0/absent = never), options.connectTimeout,
+ * options.maxUses (retire a connection after this many checkouts — pg's
+ * maxUses), options.maxLifetimeMillis (retire a connection this many ms
+ * after it was created — Postgres.js's max_lifetime). Retirement happens
+ * when the connection is returned to the pool, and the sweep also closes
+ * over-lifetime idle connections; a replacement is created on demand.
  */
 class Pool extends events_1.default.EventEmitter {
     constructor(attach, max, options) {
@@ -38,21 +43,51 @@ class Pool extends events_1.default.EventEmitter {
         this.max = max || 4;
         this.min = (options && options.min > 0) ? Math.min(options.min, this.max) : 0;
         this.idleTimeoutMillis = (options && options.idleTimeoutMillis > 0) ? options.idleTimeoutMillis : 0;
+        this.maxUses = (options && options.maxUses > 0) ? options.maxUses : 0;
+        this.maxLifetimeMillis = (options && options.maxLifetimeMillis > 0) ? options.maxLifetimeMillis : 0;
         this.pending = []; // callbacks waiting for a free slot
         this.options = options;
         this._destroyed = false; // true after destroy() — prevents further use
         this._reaper = null;
-        if (this.idleTimeoutMillis) {
+        // the sweep serves both idle eviction and lifetime retirement of
+        // idle connections; base its cadence on the tightest configured limit
+        var sweepBasis = Math.min(this.idleTimeoutMillis || Infinity, this.maxLifetimeMillis || Infinity);
+        if (sweepBasis !== Infinity) {
             var self = this;
-            // Sweep at half the idle timeout (bounded to 100ms..30s) so a
-            // connection lives at most ~1.5x idleTimeoutMillis. unref() keeps
+            // Sweep at half the basis (bounded to 100ms..30s) so a
+            // connection lives at most ~1.5x its limit. unref() keeps
             // the timer from holding the process open.
-            var interval = Math.min(Math.max(this.idleTimeoutMillis / 2, 100), 30000);
+            var interval = Math.min(Math.max(sweepBasis / 2, 100), 30000);
             this._reaper = setInterval(function () { self._reap(); }, interval);
             if (this._reaper.unref)
                 this._reaper.unref();
         }
     }
+    /** True when the connection exceeded maxUses / maxLifetimeMillis.
+     *  Both stamps are set unconditionally when the pool creates the
+     *  connection, so they can be read bare here. */
+    _isExpired(db) {
+        if (this.maxUses > 0 && db.__poolUseCount >= this.maxUses)
+            return true;
+        if (this.maxLifetimeMillis > 0 && Date.now() - db.__poolCreatedAt >= this.maxLifetimeMillis)
+            return true;
+        return false;
+    }
+    /** Close a healthy pooled connection for good (reaper/retirement path). */
+    _retire(db) {
+        var self = this;
+        this._forget(db);
+        db.connection._pooled = false;
+        try {
+            db.detach(function (err) {
+                if (err)
+                    self._emitError(err, db);
+            });
+        }
+        catch (e) {
+            self._emitError(e, db);
+        }
+    }
     /** Physical connections owned by the pool (idle + in use). */
     get totalCount() {
         return this.internaldb.length;
@@ -105,22 +140,20 @@ class Pool extends events_1.default.EventEmitter {
                 self._forget(db);
                 return;
             }
+            // lifetime retirement applies even below min — recycling is the
+            // point; replacements are created on demand
+            if (self._isExpired(db)) {
+                self._retire(db);
+                return;
+            }
+            if (!self.idleTimeoutMillis)
+                return;
             if (self.internaldb.length <= self.min)
                 return;
             var idleSince = typeof db.__poolIdleSince === 'number' ? db.__poolIdleSince : now;
             if (now - idleSince < self.idleTimeoutMillis)
                 return;
-            self._forget(db);
-            db.connection._pooled = false;
-            try {
-                db.detach(function (err) {
-                    if (err)
-                        self._emitError(err, db);
-                });
-            }
-            catch (e) {
-                self._emitError(e, db);
-            }
+            self._retire(db);
         });
     }
     get(callback) {
@@ -155,6 +188,7 @@ class Pool extends events_1.default.EventEmitter {
             }
             // Idle connection available — hand it out immediately.
             self.dbinuse++;
+            db.__poolUseCount = (db.__poolUseCount || 0) + 1;
             self.emit('acquire', db);
             cb(null, db);
         }
@@ -212,6 +246,8 @@ class Pool extends events_1.default.EventEmitter {
                 }
                 if (!err) {
                     self.dbinuse++;
+                    db.__poolCreatedAt = Date.now();
+                    db.__poolUseCount = 1;
                     self.internaldb.push(db);
                     db.on('detach', function () {
                         // also in pool (could be a twice call to detach)
@@ -222,6 +258,13 @@ class Pool extends events_1.default.EventEmitter {
                             self.internaldb.splice(self.internaldb.indexOf(db), 1);
                             self.emit('remove', db);
                         }
+                        else if (self._isExpired(db)) {
+                            // worn out (maxUses / maxLifetimeMillis): close it
+                            // for good instead of returning it to the idle
+                            // pool. The re-fired detach event exits early via
+                            // the internaldb guard above.
+                            self._retire(db);
+                        }
                         else {
                             db.__poolIdleSince = Date.now();
                             self.pooldb.push(db);

package/lib/sql-template.d.ts

@@ -0,0 +1,81 @@
+/***************************************
+ *
+ *   Tagged-template query API (Postgres.js-style)
+ *
+ *   db.sql`SELECT * FROM EMP WHERE ID = ${id}`   →  lazy thenable query
+ *   db.sql('COLUMN NAME')                        →  quoted identifier
+ *
+ *   Interpolated values become positional `?` parameters — never string
+ *   concatenation — so the API is injection-safe by construction. A query
+ *   embedded inside another tag is treated as a fragment: its text and
+ *   parameters are spliced in place. Arrays expand to `?, ?, ?` lists for
+ *   IN clauses. Execution is lazy (on await/then) and happens exactly once.
+ *
+ ***************************************/
+import type { QueryOptions, QueryResult } from './types';
+/** Executor provided by Database/Transaction: runs text+params, resolves rows
+ *  (or the full QueryResult when options.withMeta is set). */
+export type SqlExecutor = (text: string, params: any[], options?: QueryOptions) => Promise<any>;
+/** A dynamically quoted identifier produced by sql('name'). */
+export declare class SqlIdentifier {
+    name: string;
+    constructor(name: string);
+}
+/**
+ * Quote a (possibly dot-qualified) identifier for dialect 3: each part is
+ * wrapped in double quotes with embedded quotes doubled, so user input can
+ * never break out of the identifier position.
+ */
+export declare function quoteIdentifier(name: string): string;
+/** Compiled form of a tagged query: SQL text with `?` placeholders + params. */
+export interface CompiledQuery {
+    text: string;
+    params: any[];
+}
+/**
+ * A lazily executed tagged query. Awaiting it (or calling then/catch/
+ * finally) runs it through the owning Database/Transaction exactly once;
+ * embedding it in another tag uses it as a fragment instead and never
+ * executes it.
+ */
+export declare class SqlQuery<T = any> implements PromiseLike<T[]> {
+    readonly strings: readonly string[];
+    readonly values: any[];
+    private executor;
+    private queryOptions?;
+    private executed?;
+    private executedMeta?;
+    constructor(executor: SqlExecutor, strings: readonly string[], values: any[]);
+    /** The compiled SQL text (`?` placeholders) and parameter array. */
+    toQuery(): CompiledQuery;
+    /**
+     * Attach per-query options (timeout, signal, nestTables, …). Must be
+     * called before the query executes — options attached afterwards would
+     * be silently ignored, so that throws instead.
+     */
+    options(queryOptions: QueryOptions): this;
+    /** Execute resolving the full { rows, fields, affectedRows, … } result. */
+    withMeta(): Promise<QueryResult<T>>;
+    /**
+     * A query executes exactly once, in the shape of its first consumer
+     * (plain rows via then/await, or the full result via withMeta).
+     * Consuming it again in the OTHER shape cannot be honoured from the
+     * cached promise, so it throws rather than silently returning the
+     * wrong shape.
+     */
+    private run;
+    then<R1 = T[], R2 = never>(onfulfilled?: ((value: T[]) => R1 | PromiseLike<R1>) | null, onrejected?: ((reason: any) => R2 | PromiseLike<R2>) | null): Promise<R1 | R2>;
+    catch<R = never>(onrejected?: ((reason: any) => R | PromiseLike<R>) | null): Promise<T[] | R>;
+    finally(onfinally?: (() => void) | null): Promise<T[]>;
+}
+/** The dual-use tag: template tag executes, string call quotes an identifier. */
+export interface SqlTag {
+    <T = any>(strings: TemplateStringsArray, ...values: any[]): SqlQuery<T>;
+    (identifier: string): SqlIdentifier;
+}
+/**
+ * Build the `sql` tag for a Database/Transaction. `executor` receives the
+ * compiled text, params and per-query options and must return a promise
+ * (Database/Transaction pass their queryAsync).
+ */
+export declare function makeSqlTag(executor: SqlExecutor): SqlTag;

package/lib/sql-template.js

@@ -0,0 +1,162 @@
+"use strict";
+/***************************************
+ *
+ *   Tagged-template query API (Postgres.js-style)
+ *
+ *   db.sql`SELECT * FROM EMP WHERE ID = ${id}`   →  lazy thenable query
+ *   db.sql('COLUMN NAME')                        →  quoted identifier
+ *
+ *   Interpolated values become positional `?` parameters — never string
+ *   concatenation — so the API is injection-safe by construction. A query
+ *   embedded inside another tag is treated as a fragment: its text and
+ *   parameters are spliced in place. Arrays expand to `?, ?, ?` lists for
+ *   IN clauses. Execution is lazy (on await/then) and happens exactly once.
+ *
+ ***************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SqlQuery = exports.SqlIdentifier = void 0;
+exports.quoteIdentifier = quoteIdentifier;
+exports.makeSqlTag = makeSqlTag;
+/** A dynamically quoted identifier produced by sql('name'). */
+class SqlIdentifier {
+    constructor(name) {
+        this.name = name;
+    }
+}
+exports.SqlIdentifier = SqlIdentifier;
+/**
+ * Quote a (possibly dot-qualified) identifier for dialect 3: each part is
+ * wrapped in double quotes with embedded quotes doubled, so user input can
+ * never break out of the identifier position.
+ */
+function quoteIdentifier(name) {
+    return String(name)
+        .split('.')
+        .map((part) => '"' + part.replace(/"/g, '""') + '"')
+        .join('.');
+}
+function compile(strings, values, active) {
+    let text = '';
+    const params = [];
+    for (let i = 0; i < strings.length; i++) {
+        text += strings[i];
+        if (i >= values.length) {
+            continue;
+        }
+        const value = values[i];
+        if (value instanceof SqlIdentifier) {
+            text += quoteIdentifier(value.name);
+        }
+        else if (value instanceof SqlQuery) {
+            // embedded fragment: splice its text and params in place. The
+            // same fragment may appear several times (a DAG), but a fragment
+            // containing itself would recurse forever — track the expansion
+            // stack and reject cycles with a diagnosable error.
+            active = active || new Set();
+            if (active.has(value)) {
+                throw new Error('circular sql fragment: a query is embedded (transitively) inside itself');
+            }
+            active.add(value);
+            const inner = compile(value.strings, value.values, active);
+            active.delete(value);
+            text += inner.text;
+            params.push(...inner.params);
+        }
+        else if (Array.isArray(value)) {
+            // IN (${[1, 2, 3]}) → IN (?, ?, ?)
+            if (!value.length) {
+                // '' would compile to `IN ()` — invalid SQL raising a server
+                // syntax error the caller never wrote; fail early instead
+                throw new Error('cannot interpolate an empty array (would compile to invalid SQL like "IN ()")');
+            }
+            text += value.map(() => '?').join(', ');
+            params.push(...value);
+        }
+        else {
+            text += '?';
+            params.push(value);
+        }
+    }
+    return { text, params };
+}
+/**
+ * A lazily executed tagged query. Awaiting it (or calling then/catch/
+ * finally) runs it through the owning Database/Transaction exactly once;
+ * embedding it in another tag uses it as a fragment instead and never
+ * executes it.
+ */
+class SqlQuery {
+    constructor(executor, strings, values) {
+        this.executor = executor;
+        this.strings = strings;
+        this.values = values;
+    }
+    /** The compiled SQL text (`?` placeholders) and parameter array. */
+    toQuery() {
+        return compile(this.strings, this.values);
+    }
+    /**
+     * Attach per-query options (timeout, signal, nestTables, …). Must be
+     * called before the query executes — options attached afterwards would
+     * be silently ignored, so that throws instead.
+     */
+    options(queryOptions) {
+        if (this.executed) {
+            throw new Error('sql query already executed — call .options() before awaiting it');
+        }
+        this.queryOptions = { ...this.queryOptions, ...queryOptions };
+        return this;
+    }
+    /** Execute resolving the full { rows, fields, affectedRows, … } result. */
+    withMeta() {
+        return this.run(true);
+    }
+    /**
+     * A query executes exactly once, in the shape of its first consumer
+     * (plain rows via then/await, or the full result via withMeta).
+     * Consuming it again in the OTHER shape cannot be honoured from the
+     * cached promise, so it throws rather than silently returning the
+     * wrong shape.
+     */
+    run(withMeta) {
+        if (this.executed) {
+            if (withMeta !== this.executedMeta) {
+                throw new Error(this.executedMeta
+                    ? 'sql query already executed via .withMeta() — await that result instead of the query'
+                    : 'sql query already executed as plain rows — call .withMeta() first, or build a new query');
+            }
+            return this.executed;
+        }
+        this.executedMeta = withMeta;
+        const { text, params } = compile(this.strings, this.values);
+        const options = withMeta ? { ...this.queryOptions, withMeta: true } : this.queryOptions;
+        this.executed = this.executor(text, params, options);
+        return this.executed;
+    }
+    then(onfulfilled, onrejected) {
+        return this.run(false).then(onfulfilled, onrejected);
+    }
+    catch(onrejected) {
+        return this.then(undefined, onrejected);
+    }
+    finally(onfinally) {
+        return this.run(false).finally(onfinally);
+    }
+}
+exports.SqlQuery = SqlQuery;
+/**
+ * Build the `sql` tag for a Database/Transaction. `executor` receives the
+ * compiled text, params and per-query options and must return a promise
+ * (Database/Transaction pass their queryAsync).
+ */
+function makeSqlTag(executor) {
+    return function sql(first, ...values) {
+        if (Array.isArray(first) && Object.prototype.hasOwnProperty.call(first, 'raw')) {
+            return new SqlQuery(executor, first, values);
+        }
+        if (typeof first === 'string') {
+            return new SqlIdentifier(first);
+        }
+        throw new Error('sql must be used as a template tag (sql`...`) or called with an identifier string (sql(\'NAME\'))');
+    };
+}