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

package/esm/helpers/assertColumnsExist.d.ts

@@ -0,0 +1,16 @@
+import type { TableSchema } from "./pendingOps.js";
+/**
+ * Throws if any of the named columns is absent from the schema. The mirror of
+ * `assertNewColumns`: where that guard rejects a column that unexpectedly
+ * already exists, this one rejects a column that should exist but doesn't.
+ *
+ * It backs methods whose SQL silently tolerates a missing column instead of
+ * erroring — notably `SELECT * RENAME (...)`, which drops a rename whose
+ * source column is absent rather than failing, so a typo would pass unnoticed.
+ *
+ * @param schema - The schema of the operation's input.
+ * @param columns - The names of the columns the operation reads.
+ * @param method - The method name, for the error message (e.g. "renameColumns()").
+ */
+export default function assertColumnsExist(schema: TableSchema, columns: string[], method: string): void;
+//# sourceMappingURL=assertColumnsExist.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"assertColumnsExist.d.ts","sourceRoot":"","sources":["../../src/helpers/assertColumnsExist.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,OAAO,UAAU,kBAAkB,CACxC,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,MAAM,EAAE,EACjB,MAAM,EAAE,MAAM,GACb,IAAI,CAYN"}

package/esm/helpers/assertColumnsExist.js

@@ -0,0 +1,21 @@
+import quoteIdentifier from "./quoteIdentifier.js";
+/**
+ * Throws if any of the named columns is absent from the schema. The mirror of
+ * `assertNewColumns`: where that guard rejects a column that unexpectedly
+ * already exists, this one rejects a column that should exist but doesn't.
+ *
+ * It backs methods whose SQL silently tolerates a missing column instead of
+ * erroring — notably `SELECT * RENAME (...)`, which drops a rename whose
+ * source column is absent rather than failing, so a typo would pass unnoticed.
+ *
+ * @param schema - The schema of the operation's input.
+ * @param columns - The names of the columns the operation reads.
+ * @param method - The method name, for the error message (e.g. "renameColumns()").
+ */
+export default function assertColumnsExist(schema, columns, method) {
+    const missing = columns.filter((column) => schema[column] === undefined);
+    if (missing.length > 0) {
+        const plural = missing.length > 1;
+        throw new Error(`${method} the column${plural ? "s" : ""} ${missing.map((column) => `${quoteIdentifier(column)}`).join(", ")} ${plural ? "do" : "does"} not exist. Check for typos, or load the data first.`);
+    }
+}

package/esm/helpers/assertNewColumns.d.ts

@@ -0,0 +1,17 @@
+import type { TableSchema } from "./pendingOps.js";
+/**
+ * Throws if any of the target columns already exists in the schema, matching
+ * the behavior of the v1 methods that added columns with `ALTER TABLE ADD`
+ * (which errored on a duplicate). Without this guard, a `SELECT *, expr AS
+ * col` that collides with an existing column is silently renamed to `col_1`
+ * by DuckDB, so the operation would appear to succeed while leaving the
+ * original column untouched.
+ *
+ * @param schema - The schema of the operation's input.
+ * @param newColumns - The names of the columns the operation adds.
+ * @param method - The method name, for the error message (e.g. "cloneColumn()").
+ * @param allowInPlace - Columns whose name may already exist because the
+ *   operation overwrites them in place rather than adding a new column.
+ */
+export default function assertNewColumns(schema: TableSchema, newColumns: string[], method: string, allowInPlace?: string[]): void;
+//# sourceMappingURL=assertNewColumns.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"assertNewColumns.d.ts","sourceRoot":"","sources":["../../src/helpers/assertNewColumns.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,OAAO,UAAU,gBAAgB,CACtC,MAAM,EAAE,WAAW,EACnB,UAAU,EAAE,MAAM,EAAE,EACpB,MAAM,EAAE,MAAM,EACd,YAAY,GAAE,MAAM,EAAO,GAC1B,IAAI,CAUN"}

package/esm/helpers/assertNewColumns.js

@@ -0,0 +1,22 @@
+import quoteIdentifier from "./quoteIdentifier.js";
+/**
+ * Throws if any of the target columns already exists in the schema, matching
+ * the behavior of the v1 methods that added columns with `ALTER TABLE ADD`
+ * (which errored on a duplicate). Without this guard, a `SELECT *, expr AS
+ * col` that collides with an existing column is silently renamed to `col_1`
+ * by DuckDB, so the operation would appear to succeed while leaving the
+ * original column untouched.
+ *
+ * @param schema - The schema of the operation's input.
+ * @param newColumns - The names of the columns the operation adds.
+ * @param method - The method name, for the error message (e.g. "cloneColumn()").
+ * @param allowInPlace - Columns whose name may already exist because the
+ *   operation overwrites them in place rather than adding a new column.
+ */
+export default function assertNewColumns(schema, newColumns, method, allowInPlace = []) {
+    for (const column of newColumns) {
+        if (schema[column] !== undefined && !allowInPlace.includes(column)) {
+            throw new Error(`${method} the column ${quoteIdentifier(column)} already exists. Remove it first or choose a different name for the new column.`);
+        }
+    }
+}

package/esm/helpers/assertSameDatabase.d.ts

@@ -0,0 +1,11 @@
+import type SimpleDB from "../class/SimpleDB.js";
+import type SimpleTable from "../class/SimpleTable.js";
+/**
+ * Throws when a method receives a table owned by another database connection.
+ *
+ * @param simpleDB - The database on which the method will execute.
+ * @param tables - The tables that must belong to `simpleDB`.
+ * @param method - The SDA method name used in the error message.
+ */
+export default function assertSameDatabase(simpleDB: SimpleDB, tables: SimpleTable[], method: string): void;
+//# sourceMappingURL=assertSameDatabase.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"assertSameDatabase.d.ts","sourceRoot":"","sources":["../../src/helpers/assertSameDatabase.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAC;AACjD,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAEvD;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,UAAU,kBAAkB,CACxC,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,WAAW,EAAE,EACrB,MAAM,EAAE,MAAM,GACb,IAAI,CAWN"}

package/esm/helpers/assertSameDatabase.js

@@ -0,0 +1,13 @@
+/**
+ * Throws when a method receives a table owned by another database connection.
+ *
+ * @param simpleDB - The database on which the method will execute.
+ * @param tables - The tables that must belong to `simpleDB`.
+ * @param method - The SDA method name used in the error message.
+ */
+export default function assertSameDatabase(simpleDB, tables, method) {
+    const foreignTables = tables.filter((table) => table.sdb !== simpleDB);
+    if (foreignTables.length > 0) {
+        throw new Error(`${method} all tables must belong to the same SimpleDB instance. The following table${foreignTables.length === 1 ? " belongs" : "s belong"} to another database: ${foreignTables.map((table) => JSON.stringify(table.name)).join(", ")}.`);
+    }
+}

package/esm/helpers/asyncOperationContext.d.ts

@@ -0,0 +1,19 @@
+import type SimpleDB from "../class/SimpleDB.js";
+import type SimpleTable from "../class/SimpleTable.js";
+import type { PendingOp } from "./pendingOps.js";
+export type PendingEntry = {
+    table: SimpleTable;
+    op: PendingOp;
+};
+export type AsyncOperationFrame = {
+    sdb: SimpleDB;
+    entries: PendingEntry[];
+    drainPromise: Promise<void> | null;
+    open: boolean;
+};
+export declare function getAsyncOperationFrame(sdb: SimpleDB): AsyncOperationFrame | undefined;
+export declare function captureAsyncOperation(sdb: SimpleDB, entry: PendingEntry): boolean;
+export declare function runWithAsyncOperationFrame<T>(sdb: SimpleDB, fn: (frame: AsyncOperationFrame) => Promise<T>): Promise<T>;
+export declare function isDrainingAsyncOperationFrame(frame: AsyncOperationFrame): boolean;
+export declare function runWhileDrainingAsyncOperationFrame<T>(frame: AsyncOperationFrame, fn: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=asyncOperationContext.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"asyncOperationContext.d.ts","sourceRoot":"","sources":["../../src/helpers/asyncOperationContext.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAC;AACjD,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,MAAM,MAAM,YAAY,GAAG;IACzB,KAAK,EAAE,WAAW,CAAC;IACnB,EAAE,EAAE,SAAS,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,EAAE,QAAQ,CAAC;IACd,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,YAAY,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACnC,IAAI,EAAE,OAAO,CAAC;CACf,CAAC;AAKF,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,QAAQ,GACZ,mBAAmB,GAAG,SAAS,CAIjC;AAED,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,QAAQ,EACb,KAAK,EAAE,YAAY,GAClB,OAAO,CAOT;AAED,wBAAsB,0BAA0B,CAAC,CAAC,EAChD,GAAG,EAAE,QAAQ,EACb,EAAE,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,OAAO,CAAC,CAAC,CAAC,GAC7C,OAAO,CAAC,CAAC,CAAC,CAcZ;AAED,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAET;AAED,wBAAgB,mCAAmC,CAAC,CAAC,EACnD,KAAK,EAAE,mBAAmB,EAC1B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAIZ"}

package/esm/helpers/asyncOperationContext.js

@@ -0,0 +1,38 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const operationContext = new AsyncLocalStorage();
+const drainContext = new AsyncLocalStorage();
+export function getAsyncOperationFrame(sdb) {
+    return operationContext.getStore()?.findLast((frame) => frame.sdb === sdb && frame.open);
+}
+export function captureAsyncOperation(sdb, entry) {
+    const frame = getAsyncOperationFrame(sdb);
+    if (frame === undefined) {
+        return false;
+    }
+    frame.entries.push(entry);
+    return true;
+}
+export async function runWithAsyncOperationFrame(sdb, fn) {
+    const frame = {
+        sdb,
+        entries: [],
+        drainPromise: null,
+        open: true,
+    };
+    const frames = [...(operationContext.getStore() ?? []), frame];
+    try {
+        return await operationContext.run(frames, () => fn(frame));
+    }
+    finally {
+        frame.open = false;
+        frame.entries.length = 0;
+    }
+}
+export function isDrainingAsyncOperationFrame(frame) {
+    return drainContext.getStore()?.has(frame) ?? false;
+}
+export function runWhileDrainingAsyncOperationFrame(frame, fn) {
+    const draining = new Set(drainContext.getStore());
+    draining.add(frame);
+    return drainContext.run(draining, fn);
+}

package/esm/helpers/buildFuzzyMatchSql.d.ts

@@ -0,0 +1,9 @@
+export type FuzzyMethod = "ratio" | "partial_ratio" | "token_sort_ratio" | "token_set_ratio";
+export default function buildFuzzyMatchSql(leftExpression: string, rightExpression: string, method: FuzzyMethod, threshold: number, options?: {
+    decimals?: number;
+    prefilterPrefixLength?: number;
+}): {
+    scoreExpression: string;
+    condition: string;
+};
+//# sourceMappingURL=buildFuzzyMatchSql.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"buildFuzzyMatchSql.d.ts","sourceRoot":"","sources":["../../src/helpers/buildFuzzyMatchSql.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GACnB,OAAO,GACP,eAAe,GACf,kBAAkB,GAClB,iBAAiB,CAAC;AAEtB,MAAM,CAAC,OAAO,UAAU,kBAAkB,CACxC,cAAc,EAAE,MAAM,EACtB,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,WAAW,EACnB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE;IACP,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAC3B,GACL;IAAE,eAAe,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAoBhD"}

package/esm/helpers/buildFuzzyMatchSql.js

@@ -0,0 +1,17 @@
+export default function buildFuzzyMatchSql(leftExpression, rightExpression, method, threshold, options = {}) {
+    const fuzzyExpression = `rapidfuzz_${method}(${leftExpression}, ${rightExpression})`;
+    const scoreExpression = options.decimals === undefined
+        ? fuzzyExpression
+        : `ROUND(${fuzzyExpression}, ${options.decimals})`;
+    let condition = `${scoreExpression} >= ${threshold}`;
+    if (method === "ratio") {
+        const maxDiffMultiplier = (200 - 2 * threshold) / (200 - threshold);
+        condition +=
+            ` AND ABS(LENGTH(${leftExpression}) - LENGTH(${rightExpression})) <= ${maxDiffMultiplier} * GREATEST(LENGTH(${leftExpression}), LENGTH(${rightExpression}))`;
+    }
+    if (options.prefilterPrefixLength !== undefined) {
+        condition +=
+            ` AND SUBSTR(${leftExpression}, 1, ${options.prefilterPrefixLength}) = SUBSTR(${rightExpression}, 1, ${options.prefilterPrefixLength})`;
+    }
+    return { scoreExpression, condition };
+}

package/esm/helpers/cacheDatabase.d.ts

@@ -0,0 +1,5 @@
+import type SimpleTable from "../class/SimpleTable.js";
+import type { IndexDefinition } from "./indexDefinitions.js";
+export declare function writeCacheDatabase(table: SimpleTable, file: string, indexes: IndexDefinition[]): Promise<void>;
+export declare function loadCacheDatabase(table: SimpleTable, file: string, indexes: IndexDefinition[], geo: boolean): Promise<void>;
+//# sourceMappingURL=cacheDatabase.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cacheDatabase.d.ts","sourceRoot":"","sources":["../../src/helpers/cacheDatabase.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAU7D,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,eAAe,EAAE,GACzB,OAAO,CAAC,IAAI,CAAC,CAyCf;AASD,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,eAAe,EAAE,EAC1B,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,IAAI,CAAC,CAiCf"}

package/esm/helpers/cacheDatabase.js

@@ -0,0 +1,110 @@
+import { existsSync, renameSync, rmSync } from "node:fs";
+import { getIndexCacheStrategy } from "./indexDefinitions.js";
+import buildCreateIndexQuery from "./indexQueries.js";
+import cleanPath from "./cleanPath.js";
+import quoteIdentifier from "./quoteIdentifier.js";
+const CACHE_DATABASE = "__sda_cache_entry";
+export async function writeCacheDatabase(table, file, indexes) {
+    const temporaryFile = `${file}.${crypto.randomUUID()}.tmp.db`;
+    const cacheDatabase = quoteIdentifier(CACHE_DATABASE);
+    const currentDatabase = quoteIdentifier(await getCurrentDatabase(table));
+    const persistedIndexes = indexes.filter((index) => getIndexCacheStrategy(index) === "persist");
+    await loadIndexExtensions(table, persistedIndexes);
+    try {
+        await table.sdb.customQuery(`ATTACH '${cleanPath(temporaryFile)}' AS ${cacheDatabase};
+      CREATE TABLE ${cacheDatabase}.${quoteIdentifier(table.name)} AS
+        SELECT * FROM ${quoteIdentifier(table.name)};`);
+        if (persistedIndexes.length > 0) {
+            await table.sdb.customQuery(`USE ${cacheDatabase};`);
+            await table.sdb.customQuery(buildIndexQueries(table.name, persistedIndexes));
+            await table.sdb.customQuery(`USE ${currentDatabase};`);
+        }
+        await table.sdb.customQuery(`CHECKPOINT ${cacheDatabase};
+      DETACH ${cacheDatabase};`);
+        try {
+            renameSync(temporaryFile, file);
+        }
+        catch (error) {
+            if (!isReplaceRenameError(error) || !existsSync(file)) {
+                throw error;
+            }
+            rmSync(file);
+            renameSync(temporaryFile, file);
+        }
+    }
+    catch (error) {
+        await restoreDatabaseAfterFailure(table, currentDatabase, cacheDatabase);
+        if (existsSync(temporaryFile)) {
+            rmSync(temporaryFile);
+        }
+        throw error;
+    }
+}
+function isReplaceRenameError(error) {
+    if (!(error instanceof Error) || !("code" in error)) {
+        return false;
+    }
+    return error.code === "EEXIST" || error.code === "EPERM";
+}
+export async function loadCacheDatabase(table, file, indexes, geo) {
+    const cacheDatabase = quoteIdentifier(CACHE_DATABASE);
+    const currentDatabase = quoteIdentifier(await getCurrentDatabase(table));
+    if (geo) {
+        await table.sdb.customQuery("INSTALL spatial; LOAD spatial;");
+    }
+    await loadIndexExtensions(table, indexes);
+    table.indexes = [];
+    const dropFts = `DROP SCHEMA IF EXISTS ${quoteIdentifier(`fts_main_${table.name}`)} CASCADE;`;
+    try {
+        await table.sdb.customQuery(`${dropFts}
+      DROP TABLE IF EXISTS ${quoteIdentifier(table.name)};
+      ATTACH '${cleanPath(file)}' AS ${cacheDatabase} (READ_ONLY);
+      COPY FROM DATABASE ${cacheDatabase} TO ${currentDatabase};
+      DETACH ${cacheDatabase};`);
+        const indexesToRebuild = indexes.filter((index) => getIndexCacheStrategy(index) === "rebuild");
+        const indexQueries = buildIndexQueries(table.name, indexesToRebuild);
+        if (indexQueries.length > 0) {
+            await table.sdb.customQuery(indexQueries);
+        }
+    }
+    catch (error) {
+        await restoreDatabaseAfterFailure(table, currentDatabase, cacheDatabase);
+        throw error;
+    }
+    table.indexes = structuredClone(indexes);
+}
+async function getCurrentDatabase(table) {
+    const rows = await table.sdb.customQuery("SELECT current_database() AS database_name;", { returnData: true });
+    return rows[0].database_name;
+}
+async function loadIndexExtensions(table, indexes) {
+    const queries = [];
+    if (indexes.some((index) => index.kind === "vss")) {
+        queries.push("INSTALL vss; LOAD vss;");
+    }
+    if (indexes.some((index) => index.kind === "fts")) {
+        queries.push("INSTALL fts; LOAD fts;");
+    }
+    if (queries.length > 0) {
+        await table.sdb.customQuery(queries.join("\n"));
+    }
+}
+function buildIndexQueries(table, indexes) {
+    return indexes.map((index) => `${index.kind === "vss"
+        ? "SET hnsw_enable_experimental_persistence = true;\n"
+        : ""}${buildCreateIndexQuery(table, index)}`).join("\n");
+}
+async function restoreDatabaseAfterFailure(table, currentDatabase, cacheDatabase) {
+    try {
+        await table.sdb.customQuery(`USE ${currentDatabase};`);
+    }
+    catch {
+        // Preserve the original cache error.
+    }
+    try {
+        await table.sdb.customQuery(`DETACH ${cacheDatabase};`);
+    }
+    catch {
+        // The cache database may not have been attached yet.
+    }
+}

package/esm/helpers/cacheDiagnostics.d.ts

@@ -0,0 +1,4 @@
+export declare function cacheEntryExpired(creation: number, ttl: number | undefined, now: number): boolean;
+export declare function cacheTtlMessage(creation: number, ttl: number, now: number, expired: boolean): string;
+export declare function cacheLoadMessage(start: number, end: number, cachedDuration: number | undefined): string;
+//# sourceMappingURL=cacheDiagnostics.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cacheDiagnostics.d.ts","sourceRoot":"","sources":["../../src/helpers/cacheDiagnostics.ts"],"names":[],"mappings":"AAGA,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,GAAG,EAAE,MAAM,GACV,OAAO,CAET;AAED,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,OAAO,GACf,MAAM,CAgBR;AAED,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,cAAc,EAAE,MAAM,GAAG,SAAS,GACjC,MAAM,CAQR"}

package/esm/helpers/cacheDiagnostics.js

@@ -0,0 +1,21 @@
+import formatDate from "./formatDate.js";
+import prettyDuration from "./prettyDuration.js";
+export function cacheEntryExpired(creation, ttl, now) {
+    return ttl !== undefined && now - creation >= ttl * 1000;
+}
+export function cacheTtlMessage(creation, ttl, now, expired) {
+    const creationDate = formatDate(new Date(creation), "Month DD, YYYY, at HH:MM period");
+    const ttlDuration = prettyDuration(0, { end: ttl * 1000 });
+    if (expired) {
+        return `TTL of ${ttlDuration} has expired.\nThe creation date is ${creationDate}.\nIt was created ${prettyDuration(creation, { end: now })} ago.`;
+    }
+    const ttlLimit = creation + ttl * 1000;
+    return `TTL of ${ttlDuration} has not expired.\nThe creation date is ${creationDate}.\nThere are ${prettyDuration(now, { end: ttlLimit })} left.`;
+}
+export function cacheLoadMessage(start, end, cachedDuration) {
+    const loaded = `Data loaded in ${prettyDuration(start, { end })}.`;
+    if (cachedDuration === undefined) {
+        return loaded;
+    }
+    return `${loaded}\nRunning computations previously took ${prettyDuration(0, { end: cachedDuration })}.\nYou saved ${prettyDuration(end - start, { end: cachedDuration })}.`;
+}

package/esm/helpers/cacheTableDependencies.d.ts

@@ -0,0 +1,19 @@
+import type SimpleTable from "../class/SimpleTable.js";
+import { type TableGenerationId } from "./tableGeneration.js";
+export type CacheTableDependency = {
+    tableName: string;
+    generationId: TableGenerationId;
+};
+/** Records a table read when a cache computation is observing dependencies. */
+export declare function recordCacheTableAccess(table: SimpleTable): void;
+/** Records registered tables named in user-supplied SQL fragments. */
+export declare function recordCacheTableReferences(table: SimpleTable, sql: readonly string[]): void;
+/** Runs a cache computation while collecting the tables it reads. */
+export declare function captureCacheTableDependencies(cachedTable: SimpleTable, compute: () => Promise<void>): Promise<CacheTableDependency[]>;
+/** Checks persisted dependencies against the current registered tables. */
+export declare function cacheTableDependenciesMatch(cachedTable: SimpleTable, dependencies: readonly CacheTableDependency[] | undefined): boolean;
+/** Describes changed or unavailable table dependencies for verbose logging. */
+export declare function changedCacheTableDependenciesMessage(cachedTable: SimpleTable, dependencies: readonly CacheTableDependency[]): string;
+/** Lists unchanged dependencies for cache-hit verbose logging. */
+export declare function unchangedCacheTableDependenciesMessage(dependencies: readonly CacheTableDependency[]): string;
+//# sourceMappingURL=cacheTableDependencies.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cacheTableDependencies.d.ts","sourceRoot":"","sources":["../../src/helpers/cacheTableDependencies.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAEvD,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,sBAAsB,CAAC;AAE9B,MAAM,MAAM,oBAAoB,GAAG;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,iBAAiB,CAAC;CACjC,CAAC;AASF,+EAA+E;AAC/E,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAE/D;AAED,sEAAsE;AACtE,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,SAAS,MAAM,EAAE,GACrB,IAAI,CAcN;AAED,qEAAqE;AACrE,wBAAsB,6BAA6B,CACjD,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAC3B,OAAO,CAAC,oBAAoB,EAAE,CAAC,CA6CjC;AAsBD,2EAA2E;AAC3E,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,WAAW,EACxB,YAAY,EAAE,SAAS,oBAAoB,EAAE,GAAG,SAAS,GACxD,OAAO,CAYT;AAED,+EAA+E;AAC/E,wBAAgB,oCAAoC,CAClD,WAAW,EAAE,WAAW,EACxB,YAAY,EAAE,SAAS,oBAAoB,EAAE,GAC5C,MAAM,CAsBR;AAED,kEAAkE;AAClE,wBAAgB,sCAAsC,CACpD,YAAY,EAAE,SAAS,oBAAoB,EAAE,GAC5C,MAAM,CAER"}

package/esm/helpers/cacheTableDependencies.js

@@ -0,0 +1,117 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { getRegisteredTables } from "./tableRegistry.js";
+import { getTableGeneration, peekTableGeneration, } from "./tableGeneration.js";
+const dependencyContext = new AsyncLocalStorage();
+/** Records a table read when a cache computation is observing dependencies. */
+export function recordCacheTableAccess(table) {
+    dependencyContext.getStore()?.add(table);
+}
+/** Records registered tables named in user-supplied SQL fragments. */
+export function recordCacheTableReferences(table, sql) {
+    if (dependencyContext.getStore() === undefined) {
+        return;
+    }
+    for (const candidate of getRegisteredTables(table.sdb)) {
+        const escaped = candidate.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const pattern = new RegExp(`(?<![\\w\"])\"?${escaped}\"?(?![\\w\"])`, "i");
+        if (sql.some((fragment) => pattern.test(fragment))) {
+            recordCacheTableAccess(candidate);
+        }
+    }
+}
+/** Runs a cache computation while collecting the tables it reads. */
+export async function captureCacheTableDependencies(cachedTable, compute) {
+    const availableBeforeCompute = new Map(getRegisteredTables(cachedTable.sdb).map((table) => [
+        table,
+        {
+            tableName: table.name,
+            generationId: peekTableGeneration(table),
+        },
+    ]));
+    const accessed = new Set();
+    await dependencyContext.run(accessed, compute);
+    const changedTables = [...availableBeforeCompute]
+        .filter(([table, snapshot]) => table !== cachedTable &&
+        peekTableGeneration(table) !== snapshot.generationId)
+        .map(([, snapshot]) => snapshot.tableName);
+    if (changedTables.length > 0) {
+        throw new Error(cacheTableMutationMessage(cachedTable, changedTables));
+    }
+    const createdTables = getRegisteredTables(cachedTable.sdb)
+        .filter((table) => !availableBeforeCompute.has(table))
+        .map((table) => table.name);
+    if (createdTables.length > 0) {
+        throw new Error(cacheTableCleanupMessage(createdTables));
+    }
+    return [...accessed]
+        .filter((table) => table !== cachedTable && availableBeforeCompute.has(table))
+        .map((table) => {
+        const snapshot = availableBeforeCompute.get(table);
+        if (snapshot === undefined) {
+            throw new Error("A cache table dependency snapshot is missing.");
+        }
+        return {
+            tableName: snapshot.tableName,
+            generationId: snapshot.generationId ?? getTableGeneration(table),
+        };
+    })
+        .sort((left, right) => left.tableName.localeCompare(right.tableName));
+}
+function cacheTableMutationMessage(cachedTable, changedTables) {
+    const tables = changedTables.map((name) => JSON.stringify(name)).join(", ");
+    const cachedTableName = JSON.stringify(cachedTable.name);
+    if (changedTables.length === 1) {
+        return `cache() called on ${cachedTableName} cannot modify pre-existing table ${tables}. Modify ${tables} outside this cache() call.`;
+    }
+    return `cache() called on ${cachedTableName} cannot modify pre-existing tables ${tables}. Modify these tables outside this cache() call.`;
+}
+function cacheTableCleanupMessage(createdTables) {
+    const tables = createdTables.map((name) => JSON.stringify(name)).join(", ");
+    if (createdTables.length === 1) {
+        return `cache() created table ${tables} but did not remove it. Call removeTable() on ${tables} before the callback finishes to avoid downstream errors when the cache is loaded and this table is not recreated.`;
+    }
+    return `cache() created tables ${tables} but did not remove them. Call removeTable() on these tables before the callback finishes to avoid downstream errors when the cache is loaded and these tables are not recreated.`;
+}
+/** Checks persisted dependencies against the current registered tables. */
+export function cacheTableDependenciesMatch(cachedTable, dependencies) {
+    if (dependencies === undefined) {
+        return false;
+    }
+    const registered = getRegisteredTables(cachedTable.sdb);
+    return dependencies.every((dependency) => {
+        const table = registered.find((candidate) => candidate.name === dependency.tableName);
+        return table !== undefined &&
+            getTableGeneration(table) === dependency.generationId;
+    });
+}
+/** Describes changed or unavailable table dependencies for verbose logging. */
+export function changedCacheTableDependenciesMessage(cachedTable, dependencies) {
+    const registered = getRegisteredTables(cachedTable.sdb);
+    const changed = [];
+    const unchanged = [];
+    for (const dependency of dependencies) {
+        const table = registered.find((candidate) => candidate.name === dependency.tableName);
+        if (table === undefined ||
+            getTableGeneration(table) !== dependency.generationId) {
+            changed.push(dependency);
+        }
+        else {
+            unchanged.push(dependency);
+        }
+    }
+    return [
+        cacheTableDependencyStatusMessage("changed", changed),
+        cacheTableDependencyStatusMessage("unchanged", unchanged),
+    ].filter((message) => message.length > 0).join("\n");
+}
+/** Lists unchanged dependencies for cache-hit verbose logging. */
+export function unchangedCacheTableDependenciesMessage(dependencies) {
+    return cacheTableDependencyStatusMessage("unchanged", dependencies);
+}
+function cacheTableDependencyStatusMessage(status, dependencies) {
+    if (dependencies.length === 0) {
+        return "";
+    }
+    return `Table dependencies ${status}: ${dependencies.map((dependency) => JSON.stringify(dependency.tableName))
+        .join(", ")}.`;
+}

package/esm/helpers/cleanCache.js

@@ -5,7 +5,7 @@ export default function cleanCache(sdb) {
         for (const cacheId of Object.keys(cacheSources)) {
             if (!sdb.cacheSourcesUsed.includes(cacheId)) {
                 if (cacheSources[cacheId].file !== null) {
-                    sdb.debug &&
+                    sdb.cacheVerbose &&
                         console.log(`Removing unused file from cache: ${cacheSources[cacheId].file}`);
                     unlinkSync(cacheSources[cacheId].file);
                 }

package/esm/helpers/createDirectory.d.ts

@@ -1,2 +1,15 @@
+/**
+ * Creates missing directories in an output path, including parent directories.
+ * Non-hidden path segments containing a dot are treated as filenames and omitted.
+ *
+ * @param path - An output file path or a directory path without dotted segments.
+ * @returns Nothing. Existing directories are left unchanged.
+ *
+ * @example
+ * ```ts
+ * import { createDirectory } from "@nshiab/simple-data-analysis-core/helpers";
+ * createDirectory("output/tables/results.csv"); // Creates output/tables.
+ * ```
+ */
 export default function createDirectory(path: string): void;
 //# sourceMappingURL=createDirectory.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"createDirectory.d.ts","sourceRoot":"","sources":["../../src/helpers/createDirectory.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,OAAO,UAAU,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAS1D"}
+{"version":3,"file":"createDirectory.d.ts","sourceRoot":"","sources":["../../src/helpers/createDirectory.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,OAAO,UAAU,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAS1D"}

package/esm/helpers/createDirectory.js

@@ -1,4 +1,17 @@
 import { existsSync, mkdirSync } from "node:fs";
+/**
+ * Creates missing directories in an output path, including parent directories.
+ * Non-hidden path segments containing a dot are treated as filenames and omitted.
+ *
+ * @param path - An output file path or a directory path without dotted segments.
+ * @returns Nothing. Existing directories are left unchanged.
+ *
+ * @example
+ * ```ts
+ * import { createDirectory } from "@nshiab/simple-data-analysis-core/helpers";
+ * createDirectory("output/tables/results.csv"); // Creates output/tables.
+ * ```
+ */
 export default function createDirectory(path) {
     path = path
         .split("/")

package/esm/helpers/ensureSpatial.d.ts

@@ -0,0 +1,7 @@
+import type SimpleTable from "../class/SimpleTable.js";
+/**
+ * Loads the spatial extension once per connection, so geospatial operations
+ * can fuse as plain SELECT fragments instead of each being multi-statement.
+ */
+export default function ensureSpatial(simpleTable: SimpleTable): Promise<void>;
+//# sourceMappingURL=ensureSpatial.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ensureSpatial.d.ts","sourceRoot":"","sources":["../../src/helpers/ensureSpatial.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAEvD;;;GAGG;AACH,wBAA8B,aAAa,CACzC,WAAW,EAAE,WAAW,GACvB,OAAO,CAAC,IAAI,CAAC,CAcf"}

package/esm/helpers/ensureSpatial.js

@@ -0,0 +1,17 @@
+import mergeOptions from "./mergeOptions.js";
+import queryDB from "./queryDB.js";
+/**
+ * Loads the spatial extension once per connection, so geospatial operations
+ * can fuse as plain SELECT fragments instead of each being multi-statement.
+ */
+export default async function ensureSpatial(simpleTable) {
+    if (simpleTable.sdb.spatialLoaded) {
+        return;
+    }
+    await queryDB(simpleTable, `INSTALL spatial; LOAD spatial; SET geometry_always_xy = true;`, mergeOptions(simpleTable, {
+        table: null,
+        method: null,
+        parameters: null,
+    }));
+    simpleTable.sdb.spatialLoaded = true;
+}

package/esm/helpers/extractTypes.d.ts

@@ -1,5 +1,5 @@
 export default function extractTypes(types: {
-    [key: string]: string | number | boolean | Date | null;
+    [key: string]: unknown;
 }[] | null): {
     [key: string]: string;
 };

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

@@ -1 +1 @@
-{"version":3,"file":"extractTypes.d.ts","sourceRoot":"","sources":["../../src/helpers/extractTypes.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,OAAO,UAAU,YAAY,CAClC,KAAK,EAAE;IACL,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,IAAI,CAAC;CACxD,EAAE,GAAG,IAAI;;EAaX"}
+{"version":3,"file":"extractTypes.d.ts","sourceRoot":"","sources":["../../src/helpers/extractTypes.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,OAAO,UAAU,YAAY,CAClC,KAAK,EAAE;IACL,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,EAAE,GAAG,IAAI;;EAaX"}

package/esm/helpers/extractZipEntryToFile.d.ts

@@ -0,0 +1,3 @@
+/** Extracts one entry from a non-ZIP64, single-disk ZIP without buffering it. */
+export default function extractZipEntryToFile(archive: string, wantedName: string, output: string): Promise<void>;
+//# sourceMappingURL=extractZipEntryToFile.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"extractZipEntryToFile.d.ts","sourceRoot":"","sources":["../../src/helpers/extractZipEntryToFile.ts"],"names":[],"mappings":"AAgDA,iFAAiF;AACjF,wBAA8B,qBAAqB,CACjD,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAyEf"}