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

package/script/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/script/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/script/helpers/assertColumnsExist.js

@@ -0,0 +1,27 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = assertColumnsExist;
+const quoteIdentifier_js_1 = __importDefault(require("./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()").
+ */
+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) => `${(0, quoteIdentifier_js_1.default)(column)}`).join(", ")} ${plural ? "do" : "does"} not exist. Check for typos, or load the data first.`);
+    }
+}

package/script/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/script/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/script/helpers/assertNewColumns.js

@@ -0,0 +1,28 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = assertNewColumns;
+const quoteIdentifier_js_1 = __importDefault(require("./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.
+ */
+function assertNewColumns(schema, newColumns, method, allowInPlace = []) {
+    for (const column of newColumns) {
+        if (schema[column] !== undefined && !allowInPlace.includes(column)) {
+            throw new Error(`${method} the column ${(0, quoteIdentifier_js_1.default)(column)} already exists. Remove it first or choose a different name for the new column.`);
+        }
+    }
+}

package/script/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/script/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/script/helpers/assertSameDatabase.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = assertSameDatabase;
+/**
+ * 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.
+ */
+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/script/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/script/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/script/helpers/asyncOperationContext.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAsyncOperationFrame = getAsyncOperationFrame;
+exports.captureAsyncOperation = captureAsyncOperation;
+exports.runWithAsyncOperationFrame = runWithAsyncOperationFrame;
+exports.isDrainingAsyncOperationFrame = isDrainingAsyncOperationFrame;
+exports.runWhileDrainingAsyncOperationFrame = runWhileDrainingAsyncOperationFrame;
+const node_async_hooks_1 = require("node:async_hooks");
+const operationContext = new node_async_hooks_1.AsyncLocalStorage();
+const drainContext = new node_async_hooks_1.AsyncLocalStorage();
+function getAsyncOperationFrame(sdb) {
+    return operationContext.getStore()?.findLast((frame) => frame.sdb === sdb && frame.open);
+}
+function captureAsyncOperation(sdb, entry) {
+    const frame = getAsyncOperationFrame(sdb);
+    if (frame === undefined) {
+        return false;
+    }
+    frame.entries.push(entry);
+    return true;
+}
+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;
+    }
+}
+function isDrainingAsyncOperationFrame(frame) {
+    return drainContext.getStore()?.has(frame) ?? false;
+}
+function runWhileDrainingAsyncOperationFrame(frame, fn) {
+    const draining = new Set(drainContext.getStore());
+    draining.add(frame);
+    return drainContext.run(draining, fn);
+}

package/script/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/script/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/script/helpers/buildFuzzyMatchSql.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = buildFuzzyMatchSql;
+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/script/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/script/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/script/helpers/cacheDatabase.js

@@ -0,0 +1,117 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeCacheDatabase = writeCacheDatabase;
+exports.loadCacheDatabase = loadCacheDatabase;
+const node_fs_1 = require("node:fs");
+const indexDefinitions_js_1 = require("./indexDefinitions.js");
+const indexQueries_js_1 = __importDefault(require("./indexQueries.js"));
+const cleanPath_js_1 = __importDefault(require("./cleanPath.js"));
+const quoteIdentifier_js_1 = __importDefault(require("./quoteIdentifier.js"));
+const CACHE_DATABASE = "__sda_cache_entry";
+async function writeCacheDatabase(table, file, indexes) {
+    const temporaryFile = `${file}.${crypto.randomUUID()}.tmp.db`;
+    const cacheDatabase = (0, quoteIdentifier_js_1.default)(CACHE_DATABASE);
+    const currentDatabase = (0, quoteIdentifier_js_1.default)(await getCurrentDatabase(table));
+    const persistedIndexes = indexes.filter((index) => (0, indexDefinitions_js_1.getIndexCacheStrategy)(index) === "persist");
+    await loadIndexExtensions(table, persistedIndexes);
+    try {
+        await table.sdb.customQuery(`ATTACH '${(0, cleanPath_js_1.default)(temporaryFile)}' AS ${cacheDatabase};
+      CREATE TABLE ${cacheDatabase}.${(0, quoteIdentifier_js_1.default)(table.name)} AS
+        SELECT * FROM ${(0, quoteIdentifier_js_1.default)(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 {
+            (0, node_fs_1.renameSync)(temporaryFile, file);
+        }
+        catch (error) {
+            if (!isReplaceRenameError(error) || !(0, node_fs_1.existsSync)(file)) {
+                throw error;
+            }
+            (0, node_fs_1.rmSync)(file);
+            (0, node_fs_1.renameSync)(temporaryFile, file);
+        }
+    }
+    catch (error) {
+        await restoreDatabaseAfterFailure(table, currentDatabase, cacheDatabase);
+        if ((0, node_fs_1.existsSync)(temporaryFile)) {
+            (0, node_fs_1.rmSync)(temporaryFile);
+        }
+        throw error;
+    }
+}
+function isReplaceRenameError(error) {
+    if (!(error instanceof Error) || !("code" in error)) {
+        return false;
+    }
+    return error.code === "EEXIST" || error.code === "EPERM";
+}
+async function loadCacheDatabase(table, file, indexes, geo) {
+    const cacheDatabase = (0, quoteIdentifier_js_1.default)(CACHE_DATABASE);
+    const currentDatabase = (0, quoteIdentifier_js_1.default)(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 ${(0, quoteIdentifier_js_1.default)(`fts_main_${table.name}`)} CASCADE;`;
+    try {
+        await table.sdb.customQuery(`${dropFts}
+      DROP TABLE IF EXISTS ${(0, quoteIdentifier_js_1.default)(table.name)};
+      ATTACH '${(0, cleanPath_js_1.default)(file)}' AS ${cacheDatabase} (READ_ONLY);
+      COPY FROM DATABASE ${cacheDatabase} TO ${currentDatabase};
+      DETACH ${cacheDatabase};`);
+        const indexesToRebuild = indexes.filter((index) => (0, indexDefinitions_js_1.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"
+        : ""}${(0, indexQueries_js_1.default)(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/script/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/script/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/script/helpers/cacheDiagnostics.js

@@ -0,0 +1,29 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cacheEntryExpired = cacheEntryExpired;
+exports.cacheTtlMessage = cacheTtlMessage;
+exports.cacheLoadMessage = cacheLoadMessage;
+const formatDate_js_1 = __importDefault(require("./formatDate.js"));
+const prettyDuration_js_1 = __importDefault(require("./prettyDuration.js"));
+function cacheEntryExpired(creation, ttl, now) {
+    return ttl !== undefined && now - creation >= ttl * 1000;
+}
+function cacheTtlMessage(creation, ttl, now, expired) {
+    const creationDate = (0, formatDate_js_1.default)(new Date(creation), "Month DD, YYYY, at HH:MM period");
+    const ttlDuration = (0, prettyDuration_js_1.default)(0, { end: ttl * 1000 });
+    if (expired) {
+        return `TTL of ${ttlDuration} has expired.\nThe creation date is ${creationDate}.\nIt was created ${(0, prettyDuration_js_1.default)(creation, { end: now })} ago.`;
+    }
+    const ttlLimit = creation + ttl * 1000;
+    return `TTL of ${ttlDuration} has not expired.\nThe creation date is ${creationDate}.\nThere are ${(0, prettyDuration_js_1.default)(now, { end: ttlLimit })} left.`;
+}
+function cacheLoadMessage(start, end, cachedDuration) {
+    const loaded = `Data loaded in ${(0, prettyDuration_js_1.default)(start, { end })}.`;
+    if (cachedDuration === undefined) {
+        return loaded;
+    }
+    return `${loaded}\nRunning computations previously took ${(0, prettyDuration_js_1.default)(0, { end: cachedDuration })}.\nYou saved ${(0, prettyDuration_js_1.default)(end - start, { end: cachedDuration })}.`;
+}

package/script/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/script/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/script/helpers/cacheTableDependencies.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordCacheTableAccess = recordCacheTableAccess;
+exports.recordCacheTableReferences = recordCacheTableReferences;
+exports.captureCacheTableDependencies = captureCacheTableDependencies;
+exports.cacheTableDependenciesMatch = cacheTableDependenciesMatch;
+exports.changedCacheTableDependenciesMessage = changedCacheTableDependenciesMessage;
+exports.unchangedCacheTableDependenciesMessage = unchangedCacheTableDependenciesMessage;
+const node_async_hooks_1 = require("node:async_hooks");
+const tableRegistry_js_1 = require("./tableRegistry.js");
+const tableGeneration_js_1 = require("./tableGeneration.js");
+const dependencyContext = new node_async_hooks_1.AsyncLocalStorage();
+/** Records a table read when a cache computation is observing dependencies. */
+function recordCacheTableAccess(table) {
+    dependencyContext.getStore()?.add(table);
+}
+/** Records registered tables named in user-supplied SQL fragments. */
+function recordCacheTableReferences(table, sql) {
+    if (dependencyContext.getStore() === undefined) {
+        return;
+    }
+    for (const candidate of (0, tableRegistry_js_1.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. */
+async function captureCacheTableDependencies(cachedTable, compute) {
+    const availableBeforeCompute = new Map((0, tableRegistry_js_1.getRegisteredTables)(cachedTable.sdb).map((table) => [
+        table,
+        {
+            tableName: table.name,
+            generationId: (0, tableGeneration_js_1.peekTableGeneration)(table),
+        },
+    ]));
+    const accessed = new Set();
+    await dependencyContext.run(accessed, compute);
+    const changedTables = [...availableBeforeCompute]
+        .filter(([table, snapshot]) => table !== cachedTable &&
+        (0, tableGeneration_js_1.peekTableGeneration)(table) !== snapshot.generationId)
+        .map(([, snapshot]) => snapshot.tableName);
+    if (changedTables.length > 0) {
+        throw new Error(cacheTableMutationMessage(cachedTable, changedTables));
+    }
+    const createdTables = (0, tableRegistry_js_1.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 ?? (0, tableGeneration_js_1.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. */
+function cacheTableDependenciesMatch(cachedTable, dependencies) {
+    if (dependencies === undefined) {
+        return false;
+    }
+    const registered = (0, tableRegistry_js_1.getRegisteredTables)(cachedTable.sdb);
+    return dependencies.every((dependency) => {
+        const table = registered.find((candidate) => candidate.name === dependency.tableName);
+        return table !== undefined &&
+            (0, tableGeneration_js_1.getTableGeneration)(table) === dependency.generationId;
+    });
+}
+/** Describes changed or unavailable table dependencies for verbose logging. */
+function changedCacheTableDependenciesMessage(cachedTable, dependencies) {
+    const registered = (0, tableRegistry_js_1.getRegisteredTables)(cachedTable.sdb);
+    const changed = [];
+    const unchanged = [];
+    for (const dependency of dependencies) {
+        const table = registered.find((candidate) => candidate.name === dependency.tableName);
+        if (table === undefined ||
+            (0, tableGeneration_js_1.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. */
+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/script/helpers/cleanCache.js

@@ -8,7 +8,7 @@ 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}`);
                     (0, node_fs_1.unlinkSync)(cacheSources[cacheId].file);
                 }

package/script/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/script/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/script/helpers/createDirectory.js

@@ -2,6 +2,19 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = createDirectory;
 const node_fs_1 = require("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.
+ * ```
+ */
 function createDirectory(path) {
     path = path
         .split("/")

package/script/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/script/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"}