node-firebird 2.10.0 → 2.12.0

package/lib/wire/xsqlvar.js

@@ -3,9 +3,18 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SQLParamBool = exports.SQLParamDate = exports.SQLParamQuad = exports.SQLParamBuffer = exports.SQLParamString = exports.SQLParamDouble = exports.SQLParamDecFloat34 = exports.SQLParamDecFloat16 = exports.SQLParamInt128 = exports.SQLParamInt64 = exports.SQLParamInt = exports.SQLVarBoolean = exports.SQLVarTimeStampTzEx = exports.SQLVarTimeStampTz = exports.SQLVarTimeTzEx = exports.SQLVarTimeTz = exports.SQLVarTimeStamp = exports.SQLVarTime = exports.SQLVarDate = exports.SQLVarDouble = exports.SQLVarFloat = exports.SQLVarDecFloat34 = exports.SQLVarDecFloat16 = exports.SQLVarInt128 = exports.SQLVarInt64 = exports.SQLVarShort = exports.SQLVarInt = exports.SQLVarArray = exports.SQLVarBlob = exports.SQLVarQuad = exports.SQLVarString = exports.SQLVarNull = exports.SQLVarText = exports.SQLVarBase = void 0;
+exports.SQLParamBool = exports.SQLParamDate = exports.SQLParamQuad = exports.SQLParamBuffer = exports.SQLParamString = exports.SQLParamDouble = exports.SQLParamDecFloat34 = exports.SQLParamDecFloat16 = exports.SQLParamInt128 = exports.SQLParamInt64 = exports.SQLParamInt = exports.SQLVarBoolean = exports.SQLVarTimeStampTzEx = exports.SQLVarTimeStampTz = exports.SQLVarTimeTzEx = exports.SQLVarTimeTz = exports.SQLVarTimeStamp = exports.SQLVarTime = exports.SQLVarDate = exports.SQLVarDouble = exports.SQLVarFloat = exports.SQLVarDecFloat34 = exports.SQLVarDecFloat16 = exports.SQLVarInt128 = exports.SQLVarInt64 = exports.SQLVarShort = exports.SQLVarInt = exports.SQLVarArray = exports.SQLVarBlob = exports.SQLVarQuad = exports.SQLVarString = exports.SQLVarNull = exports.SQLVarText = exports.SQL_TYPE_NAMES = exports.SQLVarBase = void 0;
+exports.computeColumnKeys = computeColumnKeys;
+exports.camelizeKey = camelizeKey;
+exports.resolveKeyTransform = resolveKeyTransform;
+exports.resolveNestTables = resolveNestTables;
+exports.nestCell = nestCell;
+exports.describeField = describeField;
+exports.describeFields = describeFields;
+exports.parseRecordCounts = parseRecordCounts;
 exports.encodeDateTimeParts = encodeDateTimeParts;
 const const_1 = __importDefault(require("./const"));
+const serialize_1 = require("./serialize");
 /***************************************
  *
  *   SQLVar
@@ -68,6 +77,215 @@ function resolveTextEncoding(options) {
 class SQLVarBase {
 }
 exports.SQLVarBase = SQLVarBase;
+/**
+ * Compute the object-row property keys for a statement's output columns,
+ * honouring the nestTables and lowercase_keys options. The table qualifier
+ * is the query's relation alias when one is used (relationAlias, requested
+ * via isc_info_sql_relation_alias), the relation name otherwise, so
+ * self-joins nest under their query aliases. Expression columns (no source
+ * relation) qualify as '' exactly like mysql2: they nest under the '' key,
+ * and in separator mode become '<sep>alias' — always prefixing keeps
+ * qualified keys collision-free (a bare expression alias could otherwise
+ * collide with a real column's 'table<sep>column' key). Used by the fetch
+ * decoder and by fetchBlobSyncRow, which must agree on where each column
+ * landed in the row.
+ */
+function computeColumnKeys(output, nestTables, lowercaseKeys, transform) {
+    return output.map((column) => {
+        let key = column.alias || '';
+        if (lowercaseKeys) {
+            key = key.toLowerCase();
+        }
+        if (transform) {
+            key = transform(key);
+        }
+        if (nestTables !== true && typeof nestTables !== 'string') {
+            return { key };
+        }
+        let table = column.relationAlias || column.relation || '';
+        if (lowercaseKeys) {
+            table = table.toLowerCase();
+        }
+        if (transform) {
+            table = transform(table);
+        }
+        if (nestTables === true) {
+            return { table, key };
+        }
+        return { key: table + nestTables + key };
+    });
+}
+/** FIRST_NAME → firstName (the transformKeys: 'camel' built-in). */
+function camelizeKey(key) {
+    const parts = String(key).toLowerCase().split('_');
+    let out = parts[0] || '';
+    for (let i = 1; i < parts.length; i++) {
+        const part = parts[i];
+        if (part) {
+            out += part.charAt(0).toUpperCase() + part.slice(1);
+        }
+    }
+    return out;
+}
+/**
+ * Resolve the effective transformKeys value (per-query wins over the
+ * connection option) into a callable mapper, or undefined when off.
+ * A custom mapper is guarded like the typeCast hook: a throw inside the
+ * row-decode loop would be mistaken for an incomplete packet and desync
+ * the response queue, so failures fall back to the untransformed key.
+ */
+function resolveKeyTransform(queryOptions, connectionOptions) {
+    const value = resolveQueryOption('transformKeys', queryOptions, connectionOptions);
+    if (value === 'camel') {
+        return camelizeKey;
+    }
+    if (typeof value !== 'function') {
+        return undefined;
+    }
+    return (key) => {
+        try {
+            return String(value(key));
+        }
+        catch (err) {
+            console.warn('[node-firebird] transformKeys mapper threw for key "%s": %s — using the untransformed key', key, err && err.message);
+            return key;
+        }
+    };
+}
+/**
+ * Shared precedence rule for per-query-overridable connection options:
+ * the per-query value wins whenever it is present (even if falsy), the
+ * connection option applies otherwise.
+ */
+function resolveQueryOption(name, queryOptions, connectionOptions) {
+    if (queryOptions && queryOptions[name] !== undefined) {
+        return queryOptions[name];
+    }
+    return connectionOptions ? connectionOptions[name] : undefined;
+}
+/**
+ * Resolve the effective nestTables value: the per-query option wins over
+ * the connection option. The decoder and fetchBlobSyncRow both use this —
+ * they must agree on whether nesting is active or blob cells are looked
+ * up in the wrong place.
+ */
+function resolveNestTables(queryOptions, connectionOptions) {
+    return resolveQueryOption('nestTables', queryOptions, connectionOptions);
+}
+/**
+ * The object a column's value lives in: the row itself, or — when the
+ * column carries a nestTables table qualifier — the row's per-table
+ * sub-object, created on first use. Every site that reads or writes a
+ * cell by ColumnKey must resolve it through here.
+ */
+function nestCell(row, table) {
+    if (table === undefined) {
+        return row;
+    }
+    return row[table] || (row[table] = {});
+}
+//------------------------------------------------------
+/** Human-readable names for the SQL_* wire type codes. */
+exports.SQL_TYPE_NAMES = {
+    [const_1.default.SQL_TEXT]: 'TEXT',
+    [const_1.default.SQL_VARYING]: 'VARYING',
+    [const_1.default.SQL_SHORT]: 'SHORT',
+    [const_1.default.SQL_LONG]: 'LONG',
+    [const_1.default.SQL_FLOAT]: 'FLOAT',
+    [const_1.default.SQL_DOUBLE]: 'DOUBLE',
+    [const_1.default.SQL_D_FLOAT]: 'D_FLOAT',
+    [const_1.default.SQL_TIMESTAMP]: 'TIMESTAMP',
+    [const_1.default.SQL_BLOB]: 'BLOB',
+    [const_1.default.SQL_ARRAY]: 'ARRAY',
+    [const_1.default.SQL_QUAD]: 'QUAD',
+    [const_1.default.SQL_TYPE_TIME]: 'TIME',
+    [const_1.default.SQL_TYPE_DATE]: 'DATE',
+    [const_1.default.SQL_INT64]: 'INT64',
+    [const_1.default.SQL_INT128]: 'INT128',
+    [const_1.default.SQL_TIMESTAMP_TZ]: 'TIMESTAMP_TZ',
+    [const_1.default.SQL_TIMESTAMP_TZ_EX]: 'TIMESTAMP_TZ_EX',
+    [const_1.default.SQL_TIME_TZ]: 'TIME_TZ',
+    [const_1.default.SQL_TIME_TZ_EX]: 'TIME_TZ_EX',
+    [const_1.default.SQL_DEC16]: 'DEC16',
+    [const_1.default.SQL_DEC34]: 'DEC34',
+    [const_1.default.SQL_BOOLEAN]: 'BOOLEAN',
+    [const_1.default.SQL_NULL]: 'NULL',
+};
+/**
+ * Public column-metadata shape for one output descriptor: the vocabulary
+ * both the typeCast hook and withMeta `fields` deliver. Keep the two in
+ * lockstep by building both through here.
+ */
+function describeField(meta) {
+    return {
+        type: meta.type,
+        typeName: exports.SQL_TYPE_NAMES[meta.type] || 'UNKNOWN',
+        subType: meta.subType,
+        scale: meta.scale,
+        length: meta.length,
+        nullable: meta.nullable,
+        field: meta.field,
+        relation: meta.relation,
+        relationAlias: meta.relationAlias,
+        relationSchema: meta.relationSchema,
+        alias: meta.alias,
+    };
+}
+/**
+ * Map a statement's output descriptors to the column-metadata array
+ * delivered in withMeta results ({ rows, fields, ... }).
+ */
+function describeFields(output) {
+    return (output || []).map(describeField);
+}
+/**
+ * Parse the op_info_sql response buffer of a Const.RECORDS_INFO request
+ * into per-verb row counts. The buffer holds an isc_info_sql_records
+ * cluster (2-byte total length, then nested isc_info_req_*_count items,
+ * each 2-byte length + little-endian integer) terminated by isc_info_end.
+ */
+function parseRecordCounts(buffer) {
+    const counts = { selectCount: 0, insertCount: 0, updateCount: 0, deleteCount: 0 };
+    if (!buffer || !buffer.length) {
+        return counts;
+    }
+    // this runs inside a response callback — a malformed/truncated buffer
+    // must yield partial counts, never a throw
+    try {
+        const br = new serialize_1.BlrReader(buffer);
+        while (br.pos < br.buffer.length) {
+            const item = br.readByteCode();
+            if (item === const_1.default.isc_info_end || item === const_1.default.isc_info_truncated) {
+                break;
+            }
+            if (item === const_1.default.isc_info_sql_records) {
+                br.pos += 2; // skip the cluster's total length; nested items follow
+                continue;
+            }
+            switch (item) {
+                case const_1.default.isc_info_req_select_count:
+                    counts.selectCount = br.readInt() || 0;
+                    break;
+                case const_1.default.isc_info_req_insert_count:
+                    counts.insertCount = br.readInt() || 0;
+                    break;
+                case const_1.default.isc_info_req_update_count:
+                    counts.updateCount = br.readInt() || 0;
+                    break;
+                case const_1.default.isc_info_req_delete_count:
+                    counts.deleteCount = br.readInt() || 0;
+                    break;
+                default:
+                    // unknown item: its 2-byte length prefix tells us how far to skip
+                    br.pos += 2 + br.buffer.readUInt16LE(br.pos);
+            }
+        }
+    }
+    catch (e) {
+        // fall through with whatever was parsed so far
+    }
+    return counts;
+}
 //------------------------------------------------------
 class SQLVarText extends SQLVarBase {
     decode(data, lowerV13, options) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "node-firebird",
-    "version": "2.10.0",
+    "version": "2.12.0",
     "description": "Pure JavaScript and Asynchronous Firebird client for Node.js.",
     "keywords": [
         "firebird",

package/src/pool.ts

@@ -26,7 +26,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.
  */
 class Pool extends Events.EventEmitter {
     attach: AttachFn;
@@ -37,6 +42,8 @@ class Pool extends Events.EventEmitter {
     max: number;
     min: number;
     idleTimeoutMillis: number;
+    maxUses: number;
+    maxLifetimeMillis: number;
     pending: Callback[];
     options: any;
     _destroyed: boolean;
@@ -52,22 +59,50 @@ class Pool extends Events.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: any): boolean {
+        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: any): void {
+        var self = this;
+        this._forget(db);
+        db.connection._pooled = false;
+        try {
+            db.detach(function(err?: any) {
+                if (err) self._emitError(err, db);
+            });
+        } catch (e) {
+            self._emitError(e, db);
+        }
+    }
+
     /** Physical connections owned by the pool (idle + in use). */
     get totalCount(): number {
         return this.internaldb.length;
@@ -124,19 +159,18 @@ class Pool extends Events.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?: any) {
-                    if (err) self._emitError(err, db);
-                });
-            } catch (e) {
-                self._emitError(e, db);
-            }
+            self._retire(db);
         });
     }
 
@@ -175,6 +209,7 @@ class Pool extends Events.EventEmitter {
             }
             // Idle connection available — hand it out immediately.
             self.dbinuse++;
+            db.__poolUseCount = (db.__poolUseCount || 0) + 1;
             self.emit('acquire', db);
             cb(null, db);
         } else {
@@ -235,6 +270,8 @@ class Pool extends Events.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)
@@ -244,6 +281,12 @@ class Pool extends Events.EventEmitter {
                         if (db.connection._isClosed || db.connection._isDetach || db.connection._pooled === false) {
                             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/src/sql-template.ts

@@ -0,0 +1,196 @@
+/***************************************
+ *
+ *   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 class SqlIdentifier {
+    name: string;
+    constructor(name: string) {
+        this.name = name;
+    }
+}
+
+/**
+ * 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 function quoteIdentifier(name: string): string {
+    return String(name)
+        .split('.')
+        .map((part) => '"' + part.replace(/"/g, '""') + '"')
+        .join('.');
+}
+
+/** Compiled form of a tagged query: SQL text with `?` placeholders + params. */
+export interface CompiledQuery {
+    text: string;
+    params: any[];
+}
+
+function compile(strings: readonly string[], values: any[], active?: Set<any>): CompiledQuery {
+    let text = '';
+    const params: any[] = [];
+
+    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.
+ */
+export class SqlQuery<T = any> implements PromiseLike<T[]> {
+    readonly strings: readonly string[];
+    readonly values: any[];
+    private executor: SqlExecutor;
+    private queryOptions?: QueryOptions;
+    private executed?: Promise<any>;
+    private executedMeta?: boolean;
+
+    constructor(executor: SqlExecutor, strings: readonly string[], values: any[]) {
+        this.executor = executor;
+        this.strings = strings;
+        this.values = values;
+    }
+
+    /** The compiled SQL text (`?` placeholders) and parameter array. */
+    toQuery(): CompiledQuery {
+        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: QueryOptions): this {
+        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(): Promise<QueryResult<T>> {
+        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.
+     */
+    private run(withMeta: boolean): Promise<any> {
+        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<R1 = T[], R2 = never>(
+        onfulfilled?: ((value: T[]) => R1 | PromiseLike<R1>) | null,
+        onrejected?: ((reason: any) => R2 | PromiseLike<R2>) | null
+    ): Promise<R1 | R2> {
+        return this.run(false).then(onfulfilled, onrejected);
+    }
+
+    catch<R = never>(onrejected?: ((reason: any) => R | PromiseLike<R>) | null): Promise<T[] | R> {
+        return this.then(undefined, onrejected);
+    }
+
+    finally(onfinally?: (() => void) | null): Promise<T[]> {
+        return this.run(false).finally(onfinally) as 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 function makeSqlTag(executor: SqlExecutor): SqlTag {
+    return function sql(first: any, ...values: any[]): any {
+        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\'))');
+    } as SqlTag;
+}