@nshiab/simple-data-analysis-core 1.0.1 → 2.0.1

package/esm/helpers/flushAllTables.js

@@ -0,0 +1,411 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import cleanSQL from "./cleanSQL.js";
+import ensureSpatial from "./ensureSpatial.js";
+import extractTypes from "./extractTypes.js";
+import mergeOptions from "./mergeOptions.js";
+import queryDB from "./queryDB.js";
+import quoteIdentifier from "./quoteIdentifier.js";
+import { getRegisteredTables } from "./tableRegistry.js";
+import { getAsyncOperationFrame, isDrainingAsyncOperationFrame, runWhileDrainingAsyncOperationFrame, runWithAsyncOperationFrame, } from "./asyncOperationContext.js";
+/**
+ * The databases whose flush is executing on the current async call chain.
+ * Queries issued by the flush itself (fused statements, barriers, DESCRIBE)
+ * re-enter flushAllTables through queryDB and must not trigger a new flush,
+ * while queries from concurrent observers must wait for the in-flight flush
+ * instead of reading mid-flush state.
+ */
+const flushContext = new AsyncLocalStorage();
+/**
+ * Runs `fn` with `sdb` exempt from the top-level flush. Queries issued by an
+ * asynchronous barrier can still drain operations queued inside that barrier.
+ * Used by the flush itself and by connection setup, whose queries must run
+ * before any queued operation.
+ */
+export function runExemptFromFlush(sdb, fn) {
+    const exempt = new Set(flushContext.getStore());
+    exempt.add(sdb);
+    return flushContext.run(exempt, fn);
+}
+/**
+ * Executes the pending operations of all tables in program order: every
+ * queued operation carries a database-wide sequence number, so operations
+ * on different tables replay exactly in the order the user queued them,
+ * like immediate execution would. Consecutive fusable operations on the
+ * same table compose as CTEs into a single statement; barriers execute
+ * in order between fused segments.
+ *
+ * Every query execution point goes through this (via queryDB). Only one
+ * flush runs at a time: concurrent observers wait for the in-flight flush,
+ * then flush whatever queued in the meantime, so an awaited observer always
+ * answers from fully executed state.
+ */
+export default async function flushAllTables(sdb) {
+    const frame = getAsyncOperationFrame(sdb);
+    if (frame !== undefined) {
+        if (!isDrainingAsyncOperationFrame(frame)) {
+            await drainAsyncOperationFrame(frame);
+        }
+        return;
+    }
+    if (flushContext.getStore()?.has(sdb)) {
+        // A query issued by the top-level flush itself.
+        return;
+    }
+    while (sdb.flushPromise !== null) {
+        // Another observer's flush is running: wait for it instead of reading
+        // mid-flush state, then flush anything queued in the meantime.
+        try {
+            await sdb.flushPromise;
+        }
+        catch {
+            // The error belongs to the observer that started that flush; this
+            // observer only cares that the flush is over.
+        }
+    }
+    if (sdb.pendingCount === 0) {
+        return;
+    }
+    const promise = runExemptFromFlush(sdb, () => flush(sdb));
+    sdb.flushPromise = promise;
+    try {
+        await promise;
+    }
+    finally {
+        sdb.flushPromise = null;
+    }
+}
+async function flush(sdb) {
+    // Take ownership of every queue upfront, in program order.
+    const entries = [];
+    for (const table of getRegisteredTables(sdb)) {
+        for (const op of table.pendingOps.splice(0, table.pendingOps.length)) {
+            entries.push({ table, op });
+        }
+    }
+    sdb.pendingCount = 0;
+    await replayEntries(sdb, entries);
+}
+async function replayEntries(sdb, pendingEntries) {
+    const entries = [...pendingEntries].sort((a, b) => a.op.sequence - b.op.sequence);
+    let open = null;
+    // The table whose operation is executing, for error attribution: on
+    // failure, that table's chain aborts and the other tables' pending work
+    // goes back to their queues.
+    let executing = null;
+    // The entry being dispatched, if it is neither executed nor part of an
+    // open segment yet.
+    let current = null;
+    const runOpenSegment = async () => {
+        if (open === null) {
+            return;
+        }
+        const segment = open;
+        open = null;
+        executing = segment.table;
+        await runSegment(segment.table, segment.ops);
+        executing = null;
+    };
+    let index = 0;
+    try {
+        for (; index < entries.length; index++) {
+            const entry = entries[index];
+            // Release the reference: a consumed operation (and whatever its
+            // closures capture, like loadArray data) must not stay alive for the
+            // rest of the flush.
+            entries[index] = null;
+            current = entry;
+            const { table, op } = entry;
+            if (open !== null && open.table !== table) {
+                await runOpenSegment();
+            }
+            if (op.kind === "barrier") {
+                // A barrier is multi-statement by nature and can read or write any
+                // table, so everything pending executes first.
+                await runOpenSegment();
+                executing = table;
+                await op.execute();
+                executing = null;
+                current = null;
+                continue;
+            }
+            if (op.kind === "asyncBarrier") {
+                // An asynchronous extension barrier also captures and drains builder
+                // operations queued by its callback before replay continues.
+                await runOpenSegment();
+                executing = table;
+                await runAsyncBarrier(table, op);
+                executing = null;
+                current = null;
+                continue;
+            }
+            const reads = op.rawSQL === undefined
+                ? []
+                : referencedTables(op.rawSQL, sdb);
+            if (reads.includes(table)) {
+                // User-supplied SQL referencing the operation's own table must read
+                // the state produced by the previous steps, which a fused chain
+                // can't provide (the name would resolve to the pre-chain table). So
+                // the chain materializes and the operation runs on its own.
+                await runOpenSegment();
+                executing = table;
+                await runStepwise(table, op);
+                executing = null;
+                current = null;
+                continue;
+            }
+            const sourceSegment = open;
+            const segmentSource = sourceSegment?.ops[0];
+            if (op.kind === "fusable" &&
+                segmentSource?.kind === "source" &&
+                (op.requiresMaterializedInput ||
+                    (op.needsSpatial && segmentSource.schema === undefined))) {
+                // Materialize only the external source when this operation needs a
+                // stable physical input, or when a spatial operation would otherwise
+                // make DuckDB scan an unknown source once for schema inference and
+                // again for execution. Earlier transforms remain open and fuse with
+                // this operation.
+                const source = segmentSource;
+                const pending = sourceSegment?.ops.slice(1) ?? [];
+                open = null;
+                executing = table;
+                await runSegment(table, [source]);
+                executing = null;
+                open = { table, ops: [...pending, op] };
+                current = null;
+                continue;
+            }
+            if (op.kind === "source") {
+                // A source replaces the target table from an external relation. It
+                // starts a new segment rather than consuming any segment already open
+                // on the same table.
+                await runOpenSegment();
+                open = { table, ops: [op] };
+                current = null;
+                continue;
+            }
+            if (open === null) {
+                open = { table, ops: [] };
+            }
+            open.ops.push(op);
+            current = null;
+        }
+        await runOpenSegment();
+    }
+    catch (error) {
+        // The failing table's chain aborts, like a v1 script stopping at the
+        // failing line. The other tables' pending work was queued successfully
+        // and goes back to their queues, to execute at their next observation.
+        const failing = executing;
+        const requeue = (table, op) => {
+            if (table !== failing) {
+                table.pendingOps.push(op);
+                sdb.pendingCount++;
+            }
+        };
+        if (current !== null) {
+            requeue(current.table, current.op);
+        }
+        if (open !== null) {
+            for (const op of open.ops) {
+                requeue(open.table, op);
+            }
+        }
+        for (let i = index + 1; i < entries.length; i++) {
+            const entry = entries[i];
+            if (entry !== null) {
+                requeue(entry.table, entry.op);
+            }
+        }
+        throw error;
+    }
+}
+async function runAsyncBarrier(table, op) {
+    await runWithAsyncOperationFrame(table.sdb, async (frame) => {
+        await op.execute();
+        await drainAsyncOperationFrame(frame);
+    });
+}
+async function drainAsyncOperationFrame(frame) {
+    while (frame.drainPromise !== null) {
+        try {
+            await frame.drainPromise;
+        }
+        catch {
+            // The observer that started the drain receives its failure. A concurrent
+            // observer waits for that drain to finish, then handles remaining work.
+        }
+    }
+    if (frame.entries.length === 0) {
+        return;
+    }
+    // Start on the next microtask so drainPromise is visible before replay can
+    // re-enter user code or another observer can attempt the same drain.
+    const promise = Promise.resolve().then(() => runWhileDrainingAsyncOperationFrame(frame, async () => {
+        while (frame.entries.length > 0) {
+            const entries = frame.entries.splice(0, frame.entries.length);
+            await replayEntries(frame.sdb, entries);
+        }
+    }));
+    frame.drainPromise = promise;
+    try {
+        await promise;
+    }
+    finally {
+        if (frame.drainPromise === promise) {
+            frame.drainPromise = null;
+        }
+    }
+}
+/**
+ * Returns the tables of the database whose names appear in the given SQL
+ * fragments. Matching is conservative (a column sharing a table's name
+ * counts as a reference): a false positive only costs fusion, never
+ * correctness.
+ */
+function referencedTables(rawSQL, sdb) {
+    const referenced = [];
+    for (const table of getRegisteredTables(sdb)) {
+        const escaped = table.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const pattern = new RegExp(`(?<![\\w"])"?${escaped}"?(?![\\w"])`, "i");
+        if (rawSQL.some((sql) => pattern.test(sql))) {
+            referenced.push(table);
+        }
+    }
+    return referenced;
+}
+async function runSegment(table, ops) {
+    if (ops.length === 1) {
+        await runStepwise(table, ops[0]);
+        return;
+    }
+    if (ops.some(needsSpatial)) {
+        await ensureSpatial(table);
+    }
+    // Each fragment is cleaned individually: cleanSQL's WHERE handling must not
+    // cross fragment boundaries once they are composed into one statement.
+    const ctes = [];
+    // The schema of the next fragment's input, reused while operations declare
+    // they preserve it, so a run of same-shape steps costs at most one
+    // DESCRIBE round-trip.
+    let schema = null;
+    for (let i = 0; i < ops.length; i++) {
+        const op = ops[i];
+        try {
+            const compiled = await compileOp(table, op, ctes, schema);
+            ctes.push(compiled.cte);
+            schema = compiled.schema;
+        }
+        catch (error) {
+            // Flush-time validation (or a broken earlier fragment surfacing at
+            // DESCRIBE) fails the chain at this operation. The steps before it
+            // already succeeded in program order, so they execute before the
+            // error propagates — like a v1 script failing at this line.
+            if (ctes.length > 0) {
+                await executeFused(table, ops.slice(0, i), ctes);
+            }
+            throw error;
+        }
+    }
+    await executeFused(table, ops, ctes);
+}
+async function compileOp(table, op, ctes, schema) {
+    if (op.kind === "source") {
+        return {
+            cte: {
+                alias: `s${ctes.length + 1}`,
+                select: cleanSQL(op.buildSelect()),
+                values: [],
+            },
+            schema: op.schema ?? null,
+        };
+    }
+    const input = ctes.length === 0
+        ? quoteIdentifier(table.name)
+        : quoteIdentifier(ctes[ctes.length - 1].alias);
+    const inputSchema = op.needsSchema && schema === null
+        ? await describeChain(table, ctes)
+        : schema;
+    const buildSchema = inputSchema ?? {};
+    const outputSchema = inputSchema === null
+        ? null
+        : op.outputSchema !== undefined
+            ? op.outputSchema(inputSchema)
+            : op.preservesSchema === true
+                ? inputSchema
+                : null;
+    return {
+        cte: {
+            alias: `s${ctes.length + 1}`,
+            select: cleanSQL(op.buildSelect(input, buildSchema)),
+            values: resolveValues(op, buildSchema),
+        },
+        schema: outputSchema,
+    };
+}
+async function executeFused(table, ops, ctes) {
+    const query = `CREATE OR REPLACE TABLE ${quoteIdentifier(table.name)} AS WITH ${ctes.map((c) => `${quoteIdentifier(c.alias)} AS (${c.select})`).join(", ")} SELECT * FROM ${quoteIdentifier(ctes[ctes.length - 1].alias)}`;
+    try {
+        await queryDB(table, query, mergeOptions(table, {
+            table: table.name,
+            method: ops.map((op) => op.method).join(" + "),
+            parameters: Object.fromEntries(ops.map((op, i) => [`${i + 1}. ${op.method}`, op.parameters])),
+            values: ctes.flatMap((cte) => cte.values),
+            noClean: true,
+        }));
+    }
+    catch (fusedError) {
+        // Re-run the segment step by step to pinpoint the culprit method and
+        // report it exactly as immediate execution would have.
+        for (const op of ops) {
+            await runStepwise(table, op);
+        }
+        // Every step succeeded on its own: the failure came from the fusion
+        // itself. The table now holds the correct stepwise result, so we warn
+        // instead of throwing.
+        console.warn(`The fused query for ${ops.map((op) => op.method).join(" + ")} failed, but running the methods one by one succeeded. Please report this as a bug to https://github.com/nshiab/simple-data-analysis-core/issues.\n${fusedError instanceof Error ? fusedError.message : String(fusedError)}`);
+    }
+}
+async function runStepwise(table, op) {
+    if (needsSpatial(op)) {
+        await ensureSpatial(table);
+    }
+    // Compilation is shared with the fused path, so both paths execute the same
+    // cleaned fragment with the same bound values and schema handling.
+    const compiled = await compileOp(table, op, [], null);
+    await queryDB(table, `CREATE OR REPLACE TABLE ${quoteIdentifier(table.name)} AS ${compiled.cte.select}`, mergeOptions(table, {
+        table: table.name,
+        method: op.method,
+        parameters: op.parameters,
+        values: compiled.cte.values,
+        noClean: true,
+    }));
+}
+function needsSpatial(op) {
+    return op.kind === "fusable" && op.needsSpatial === true;
+}
+function resolveValues(op, schema) {
+    return typeof op.values === "function" ? op.values(schema) : op.values ?? [];
+}
+/**
+ * Returns the schema at the current point in the fused chain. With no CTEs
+ * yet, this describes the table itself; otherwise it describes the output of
+ * the last fragment. DESCRIBE is planning-only, so no data is computed.
+ */
+async function describeChain(table, ctes) {
+    const select = ctes.length === 0
+        ? `SELECT * FROM ${quoteIdentifier(table.name)}`
+        : `WITH ${ctes.map((c) => `${quoteIdentifier(c.alias)} AS (${c.select})`).join(", ")} SELECT * FROM ${quoteIdentifier(ctes[ctes.length - 1].alias)}`;
+    const query = ctes.length === 0
+        ? `DESCRIBE ${quoteIdentifier(table.name)}`
+        : `DESCRIBE ${select}`;
+    const values = ctes.flatMap((cte) => cte.values);
+    const types = await queryDB(table, query, mergeOptions(table, {
+        table: table.name,
+        method: null,
+        parameters: null,
+        returnData: true,
+        values,
+        noClean: true,
+    }));
+    return extractTypes(types);
+}

package/esm/helpers/formatMissingTables.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Formats a missing-table error with the requested and available table names.
+ *
+ * @param method - The SDA method looking up the tables.
+ * @param missingTables - The requested table names that were not found.
+ * @param availableTables - The table names currently available.
+ * @returns An actionable missing-table error message.
+ *
+ * @example
+ * ```ts
+ * const message = formatMissingTables(
+ *   "getTable()",
+ *   ["missing"],
+ *   ["votes", "districts"],
+ * );
+ * ```
+ */
+export default function formatMissingTables(method: string, missingTables: string[], availableTables: string[]): string;
+//# sourceMappingURL=formatMissingTables.d.ts.map

package/esm/helpers/formatMissingTables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatMissingTables.d.ts","sourceRoot":"","sources":["../../src/helpers/formatMissingTables.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,OAAO,UAAU,mBAAmB,CACzC,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,EAAE,EACvB,eAAe,EAAE,MAAM,EAAE,GACxB,MAAM,CAUR"}

package/esm/helpers/formatMissingTables.js

@@ -0,0 +1,29 @@
+import quoteIdentifier from "./quoteIdentifier.js";
+/**
+ * Formats a missing-table error with the requested and available table names.
+ *
+ * @param method - The SDA method looking up the tables.
+ * @param missingTables - The requested table names that were not found.
+ * @param availableTables - The table names currently available.
+ * @returns An actionable missing-table error message.
+ *
+ * @example
+ * ```ts
+ * const message = formatMissingTables(
+ *   "getTable()",
+ *   ["missing"],
+ *   ["votes", "districts"],
+ * );
+ * ```
+ */
+export default function formatMissingTables(method, missingTables, availableTables) {
+    const missing = [...missingTables].sort();
+    const available = [...availableTables].sort();
+    const missingDescription = missing.length === 1
+        ? `table ${quoteIdentifier(missing[0])}`
+        : `tables ${missing.map(quoteIdentifier).join(", ")}`;
+    const availableDescription = available.length === 0
+        ? "No tables are currently available."
+        : `Available tables: ${available.map(quoteIdentifier).join(", ")}.`;
+    return `${method} could not find ${missingDescription}. ${availableDescription}`;
+}

package/esm/helpers/getCurrentDatabase.d.ts

@@ -0,0 +1,3 @@
+import type SimpleDB from "../class/SimpleDB.js";
+export default function getCurrentDatabase(sdb: SimpleDB): Promise<string>;
+//# sourceMappingURL=getCurrentDatabase.d.ts.map

package/esm/helpers/getCurrentDatabase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getCurrentDatabase.d.ts","sourceRoot":"","sources":["../../src/helpers/getCurrentDatabase.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAC;AAEjD,wBAA8B,kBAAkB,CAC9C,GAAG,EAAE,QAAQ,GACZ,OAAO,CAAC,MAAM,CAAC,CAKjB"}

package/esm/helpers/getCurrentDatabase.js

@@ -0,0 +1,7 @@
+import queryDbFile from "./queryDbFile.js";
+export default async function getCurrentDatabase(sdb) {
+    const rows = await queryDbFile(sdb, "SELECT current_database() AS name;", {
+        returnData: true,
+    });
+    return rows[0].name;
+}

package/esm/helpers/getDbFileType.d.ts

@@ -0,0 +1,2 @@
+export default function getDbFileType(file: string): "duckdb" | "sqlite";
+//# sourceMappingURL=getDbFileType.d.ts.map

package/esm/helpers/getDbFileType.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getDbFileType.d.ts","sourceRoot":"","sources":["../../src/helpers/getDbFileType.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,OAAO,UAAU,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAOvE"}

package/esm/helpers/getDbFileType.js

@@ -0,0 +1,9 @@
+import { extname } from "node:path";
+export default function getDbFileType(file) {
+    const extension = extname(file).slice(1).toLowerCase();
+    if (extension === "db" || extension === "duckdb")
+        return "duckdb";
+    if (extension === "sqlite")
+        return "sqlite";
+    throw new Error(`The extension ${extension} is not supported. Please use .db, .duckdb or .sqlite instead.`);
+}

package/esm/helpers/getDbIndexes.d.ts

@@ -0,0 +1,4 @@
+import type SimpleDB from "../class/SimpleDB.js";
+import type { IndexDefinition } from "./indexDefinitions.js";
+export default function getDbIndexes(sdb: SimpleDB): Record<string, IndexDefinition[]>;
+//# sourceMappingURL=getDbIndexes.d.ts.map

package/esm/helpers/getDbIndexes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getDbIndexes.d.ts","sourceRoot":"","sources":["../../src/helpers/getDbIndexes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,MAAM,CAAC,OAAO,UAAU,YAAY,CAClC,GAAG,EAAE,QAAQ,GACZ,MAAM,CAAC,MAAM,EAAE,eAAe,EAAE,CAAC,CAKnC"}

package/esm/helpers/getDbIndexes.js

@@ -0,0 +1,4 @@
+export default function getDbIndexes(sdb) {
+    return Object.fromEntries(sdb.getTables().filter((table) => table.indexes.length > 0)
+        .map((table) => [table.name, structuredClone(table.indexes)]));
+}

package/esm/helpers/getStatExpression.d.ts

@@ -0,0 +1,10 @@
+export type Stat = "count" | "countDistinct" | "countNull" | "min" | "max" | "mean" | "median" | "sum" | "skew" | "stdDev" | "variance";
+export declare const allStats: readonly Stat[];
+/** Returns whether a DuckDB type is temporal for statistic compatibility. */
+export declare function isTemporalStatType(type: string | undefined): boolean;
+/**
+ * Returns the aggregate expression for one statistic of one column, or `null`
+ * when the statistic is not supported for the column type.
+ */
+export default function getStatExpression(stat: Stat, type: string | undefined, reference: string, decimals: number | undefined): string | null;
+//# sourceMappingURL=getStatExpression.d.ts.map

package/esm/helpers/getStatExpression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getStatExpression.d.ts","sourceRoot":"","sources":["../../src/helpers/getStatExpression.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,IAAI,GACZ,OAAO,GACP,eAAe,GACf,WAAW,GACX,KAAK,GACL,KAAK,GACL,MAAM,GACN,QAAQ,GACR,KAAK,GACL,MAAM,GACN,QAAQ,GACR,UAAU,CAAC;AAEf,eAAO,MAAM,QAAQ,EAAE,SAAS,IAAI,EAYnC,CAAC;AAqBF,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,GAAG,SAAS,GACvB,OAAO,CAET;AAED;;;GAGG;AACH,MAAM,CAAC,OAAO,UAAU,iBAAiB,CACvC,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,MAAM,GAAG,IAAI,CAsCf"}

package/esm/helpers/getStatExpression.js

@@ -0,0 +1,75 @@
+export const allStats = [
+    "count",
+    "countDistinct",
+    "countNull",
+    "min",
+    "max",
+    "mean",
+    "median",
+    "sum",
+    "skew",
+    "stdDev",
+    "variance",
+];
+const aggregateFunctions = {
+    min: "MIN",
+    max: "MAX",
+    mean: "AVG",
+    median: "MEDIAN",
+    sum: "SUM",
+    skew: "SKEWNESS",
+    stdDev: "STDDEV",
+    variance: "VARIANCE",
+};
+const temporalStatTypes = [
+    "DATE",
+    "TIME",
+    "TIMESTAMP",
+    "TIMESTAMP_MS",
+    "TIMESTAMP WITH TIME ZONE",
+];
+/** Returns whether a DuckDB type is temporal for statistic compatibility. */
+export function isTemporalStatType(type) {
+    return typeof type === "string" && temporalStatTypes.includes(type);
+}
+/**
+ * Returns the aggregate expression for one statistic of one column, or `null`
+ * when the statistic is not supported for the column type.
+ */
+export default function getStatExpression(stat, type, reference, decimals) {
+    if (typeof type === "string" && type.toLowerCase().includes("geometry")) {
+        return null;
+    }
+    if (stat === "count") {
+        return `CAST(COUNT(*) AS INTEGER)`;
+    }
+    if (stat === "countDistinct") {
+        return `CAST(COUNT(DISTINCT ${reference}) AS INTEGER)`;
+    }
+    if (stat === "countNull") {
+        return `CAST(COUNT(CASE WHEN ${reference} IS NULL THEN 1 END) AS INTEGER)`;
+    }
+    if (type === "VARCHAR") {
+        return null;
+    }
+    if (isTemporalStatType(type) &&
+        ["mean", "sum", "skew", "stdDev", "variance"].includes(stat)) {
+        return null;
+    }
+    const aggregateFunction = aggregateFunctions[stat];
+    if (aggregateFunction === undefined) {
+        return null;
+    }
+    const aggregate = `${aggregateFunction}(${reference})`;
+    return typeof decimals === "number" &&
+        typeof type === "string" &&
+        ![
+            "VARCHAR",
+            "DATE",
+            "TIME",
+            "TIMESTAMP",
+            "TIMESTAMP WITH TIME ZONE",
+        ].includes(type)
+        ? `ROUND(${aggregate}, ${decimals})`
+        : aggregate;
+}

package/esm/helpers/index.d.ts

@@ -12,9 +12,12 @@
  * const arr = stringToArray("single");
  * ```
  */
+import "../_dnt.polyfills.js";
 export { default as createDirectory } from "./createDirectory.js";
 export { default as mergeOptions } from "./mergeOptions.js";
 export { default as parseValue } from "./parseValue.js";
 export { default as queryDB } from "./queryDB.js";
+export { default as queueAsyncBarrier } from "./queueAsyncBarrier.js";
+export { default as quoteIdentifier } from "./quoteIdentifier.js";
 export { default as stringToArray } from "./stringToArray.js";
 //# sourceMappingURL=index.d.ts.map

package/esm/helpers/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/helpers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/helpers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,sBAAsB,CAAC;AAG9B,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,OAAO,IAAI,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,oBAAoB,CAAC"}

package/esm/helpers/index.js

@@ -12,8 +12,11 @@
  * const arr = stringToArray("single");
  * ```
  */
+import "../_dnt.polyfills.js";
 export { default as createDirectory } from "./createDirectory.js";
 export { default as mergeOptions } from "./mergeOptions.js";
 export { default as parseValue } from "./parseValue.js";
 export { default as queryDB } from "./queryDB.js";
+export { default as queueAsyncBarrier } from "./queueAsyncBarrier.js";
+export { default as quoteIdentifier } from "./quoteIdentifier.js";
 export { default as stringToArray } from "./stringToArray.js";

package/esm/helpers/indexDefinitions.d.ts

@@ -0,0 +1,30 @@
+/** The metadata required to identify and recreate a DuckDB HNSW index. */
+export type VssIndexDefinition = {
+    kind: "vss";
+    name: string;
+    column: string;
+    options: {
+        efConstruction?: number;
+        efSearch?: number;
+        M?: number;
+    };
+};
+/** The metadata required to identify and recreate a DuckDB full-text index. */
+export type FtsIndexDefinition = {
+    kind: "fts";
+    name: string;
+    idColumn: string;
+    textColumn: string;
+    options: {
+        stemmer?: string;
+        stopwords?: string;
+        ignore?: string;
+        stripAccents?: boolean;
+        lower?: boolean;
+    };
+};
+/** A complete index definition stored by a SimpleTable. */
+export type IndexDefinition = VssIndexDefinition | FtsIndexDefinition;
+export type IndexCacheStrategy = "persist" | "rebuild";
+export declare function getIndexCacheStrategy(index: IndexDefinition): IndexCacheStrategy;
+//# sourceMappingURL=indexDefinitions.d.ts.map