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

package/script/helpers/setDbProps.js

@@ -1,24 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = setDbProps;
-const node_fs_1 = require("node:fs");
-async function setDbProps(simpleDB, allIndexesFile) {
+const tableGeneration_js_1 = require("./tableGeneration.js");
+const tableRegistry_js_1 = require("./tableRegistry.js");
+async function setDbProps(simpleDB, indexes) {
     for (const table of await simpleDB.getTableNames()) {
-        simpleDB.newTable(table);
-    }
-    for (const table of await simpleDB.getTables()) {
-        const types = await table.getTypes();
-        if (Object.values(types).some((type) => type.toLowerCase().includes("geometry"))) {
-            await simpleDB.customQuery(`INSTALL SPATIAL; LOAD SPATIAL;`);
+        if (!simpleDB.getTables().some((registered) => registered.name === table)) {
+            const instance = new simpleDB.tableClass(table, simpleDB, {
+                rowsToLog: simpleDB.rowsToLog,
+                charsToLog: simpleDB.charsToLog,
+                typesToLog: simpleDB.typesToLog,
+            });
+            (0, tableRegistry_js_1.registerTable)(simpleDB, instance);
+            (0, tableGeneration_js_1.markTableChanged)(instance);
         }
     }
-    if ((0, node_fs_1.existsSync)(allIndexesFile)) {
-        const indexes = JSON.parse((0, node_fs_1.readFileSync)(allIndexesFile, "utf-8"));
-        for (const table of simpleDB.tables) {
-            if (indexes[table.name]) {
-                table.indexes = indexes[table.name];
-            }
+    for (const table of simpleDB.getTables()) {
+        if (indexes[table.name]) {
+            table.indexes = structuredClone(indexes[table.name]);
         }
     }
-    simpleDB.tableIncrement = Math.round(Math.random() * 1000000);
+    while (simpleDB.getTables().some((table) => table.name === `table${simpleDB.tableIncrement}`)) {
+        simpleDB.tableIncrement++;
+    }
 }

package/script/helpers/statCanCache.d.ts

@@ -0,0 +1,6 @@
+import type SimpleTable from "../class/SimpleTable.js";
+export declare function createStatCanCacheId(pid: string, lang: "en" | "fr"): string;
+export declare function useStatCanCache(table: SimpleTable, id: string, enabled: boolean, ttl: number | undefined, parameters: {
+    [key: string]: unknown;
+}, compute: () => Promise<void>): Promise<void>;
+//# sourceMappingURL=statCanCache.d.ts.map

package/script/helpers/statCanCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"statCanCache.d.ts","sourceRoot":"","sources":["../../src/helpers/statCanCache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAUvD,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,CAE3E;AAED,wBAAsB,eAAe,CACnC,KAAK,EAAE,WAAW,EAClB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,UAAU,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,EACtC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAC3B,OAAO,CAAC,IAAI,CAAC,CAmCf"}

package/script/helpers/statCanCache.js

@@ -0,0 +1,78 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createStatCanCacheId = createStatCanCacheId;
+exports.useStatCanCache = useStatCanCache;
+const fileCache_js_1 = __importStar(require("./fileCache.js"));
+const mergeOptions_js_1 = __importDefault(require("./mergeOptions.js"));
+const parseValue_js_1 = __importDefault(require("./parseValue.js"));
+const queryDB_js_1 = __importDefault(require("./queryDB.js"));
+const quoteIdentifier_js_1 = __importDefault(require("./quoteIdentifier.js"));
+const CACHE_DIRECTORY = ".sda-cache/statcan";
+const CACHE_FORMAT_VERSION = "statcan-parquet-v1";
+function createStatCanCacheId(pid, lang) {
+    return (0, fileCache_js_1.createFileCacheId)("statcan", [CACHE_FORMAT_VERSION, pid, lang]);
+}
+async function useStatCanCache(table, id, enabled, ttl, parameters, compute) {
+    await (0, fileCache_js_1.default)(table, {
+        directory: CACHE_DIRECTORY,
+        enabled,
+        extension: "parquet",
+        formatVersion: CACHE_FORMAT_VERSION,
+        id,
+        method: "loadStatCanData()",
+        ttl,
+        load: async (file) => {
+            await (0, queryDB_js_1.default)(table, `CREATE OR REPLACE TABLE ${(0, quoteIdentifier_js_1.default)(table.name)} AS
+        SELECT * FROM read_parquet(${(0, parseValue_js_1.default)(file)});`, (0, mergeOptions_js_1.default)(table, {
+                table: table.name,
+                method: "loadStatCanData()",
+                parameters,
+            }));
+        },
+        compute,
+        write: async (file) => {
+            await (0, queryDB_js_1.default)(table, `COPY ${(0, quoteIdentifier_js_1.default)(table.name)} TO ${(0, parseValue_js_1.default)(file)}
+        WITH (FORMAT PARQUET);`, (0, mergeOptions_js_1.default)(table, {
+                table: table.name,
+                method: "loadStatCanData()",
+                parameters,
+            }));
+        },
+    });
+}

package/script/helpers/stringToArray.d.ts

@@ -1,2 +1,16 @@
+/**
+ * Normalizes a string or array of strings to a new array.
+ * Existing arrays are copied so callers can change the result independently.
+ *
+ * @param argument - One string or an array of strings.
+ * @returns A new array containing the supplied strings.
+ *
+ * @example
+ * ```ts
+ * import { stringToArray } from "@nshiab/simple-data-analysis-core/helpers";
+ * console.log(stringToArray("name")); // ["name"]
+ * console.log(stringToArray(["name", "age"])); // ["name", "age"]
+ * ```
+ */
 export default function stringToArray(argument: string | string[]): string[];
 //# sourceMappingURL=stringToArray.d.ts.map

package/script/helpers/stringToArray.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stringToArray.d.ts","sourceRoot":"","sources":["../../src/helpers/stringToArray.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,OAAO,UAAU,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,CAQ3E"}
+{"version":3,"file":"stringToArray.d.ts","sourceRoot":"","sources":["../../src/helpers/stringToArray.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,OAAO,UAAU,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,CAQ3E"}

package/script/helpers/stringToArray.js

@@ -1,9 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = stringToArray;
+/**
+ * Normalizes a string or array of strings to a new array.
+ * Existing arrays are copied so callers can change the result independently.
+ *
+ * @param argument - One string or an array of strings.
+ * @returns A new array containing the supplied strings.
+ *
+ * @example
+ * ```ts
+ * import { stringToArray } from "@nshiab/simple-data-analysis-core/helpers";
+ * console.log(stringToArray("name")); // ["name"]
+ * console.log(stringToArray(["name", "age"])); // ["name", "age"]
+ * ```
+ */
 function stringToArray(argument) {
     if (Array.isArray(argument)) {
-        return argument;
+        return [...argument];
     }
     else if (typeof argument === "string") {
         return [argument];

package/script/helpers/tableGeneration.d.ts

@@ -0,0 +1,18 @@
+import type SimpleTable from "../class/SimpleTable.js";
+declare const tableGenerationIdBrand: unique symbol;
+/** An opaque identifier for one in-process or cached table generation. */
+export type TableGenerationId = string & {
+    readonly [tableGenerationIdBrand]: true;
+};
+/** Returns an established generation without creating one for a new table. */
+export declare function peekTableGeneration(table: SimpleTable): TableGenerationId | undefined;
+/** Creates a new table generation identifier. */
+export declare function createTableGenerationId(): TableGenerationId;
+/** Returns the current in-process generation identifier for a table. */
+export declare function getTableGeneration(table: SimpleTable): TableGenerationId;
+/** Gives a table a new generation after it may have changed. */
+export declare function markTableChanged(table: SimpleTable): TableGenerationId;
+/** Restores the generation persisted with a cached table artifact. */
+export declare function restoreTableGeneration(table: SimpleTable, generation: TableGenerationId): void;
+export {};
+//# sourceMappingURL=tableGeneration.d.ts.map

package/script/helpers/tableGeneration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tableGeneration.d.ts","sourceRoot":"","sources":["../../src/helpers/tableGeneration.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAEvD,OAAO,CAAC,MAAM,sBAAsB,EAAE,OAAO,MAAM,CAAC;AAEpD,0EAA0E;AAC1E,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG;IACvC,QAAQ,CAAC,CAAC,sBAAsB,CAAC,EAAE,IAAI,CAAC;CACzC,CAAC;AAIF,8EAA8E;AAC9E,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,WAAW,GACjB,iBAAiB,GAAG,SAAS,CAE/B;AAED,iDAAiD;AACjD,wBAAgB,uBAAuB,IAAI,iBAAiB,CAE3D;AAED,wEAAwE;AACxE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,WAAW,GAAG,iBAAiB,CAOxE;AAED,gEAAgE;AAChE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,iBAAiB,CAItE;AAED,sEAAsE;AACtE,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,WAAW,EAClB,UAAU,EAAE,iBAAiB,GAC5B,IAAI,CAEN"}

package/script/helpers/tableGeneration.js

@@ -0,0 +1,39 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.peekTableGeneration = peekTableGeneration;
+exports.createTableGenerationId = createTableGenerationId;
+exports.getTableGeneration = getTableGeneration;
+exports.markTableChanged = markTableChanged;
+exports.restoreTableGeneration = restoreTableGeneration;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const generations = new WeakMap();
+/** Returns an established generation without creating one for a new table. */
+function peekTableGeneration(table) {
+    return generations.get(table);
+}
+/** Creates a new table generation identifier. */
+function createTableGenerationId() {
+    return node_crypto_1.default.randomUUID();
+}
+/** Returns the current in-process generation identifier for a table. */
+function getTableGeneration(table) {
+    let generation = generations.get(table);
+    if (generation === undefined) {
+        generation = createTableGenerationId();
+        generations.set(table, generation);
+    }
+    return generation;
+}
+/** Gives a table a new generation after it may have changed. */
+function markTableChanged(table) {
+    const generation = createTableGenerationId();
+    generations.set(table, generation);
+    return generation;
+}
+/** Restores the generation persisted with a cached table artifact. */
+function restoreTableGeneration(table, generation) {
+    generations.set(table, generation);
+}

package/script/helpers/tableRegistry.d.ts

@@ -0,0 +1,9 @@
+import type SimpleDB from "../class/SimpleDB.js";
+import type SimpleTable from "../class/SimpleTable.js";
+export declare function initializeTableRegistry<Table extends SimpleTable>(simpleDB: SimpleDB<Table>): void;
+export declare function getRegisteredTables<Table extends SimpleTable>(simpleDB: SimpleDB<Table>): readonly Table[];
+export declare function listRegisteredTables<Table extends SimpleTable>(simpleDB: SimpleDB<Table>): readonly Table[];
+export declare function registerTable<Table extends SimpleTable>(simpleDB: SimpleDB<Table>, table: Table): void;
+export declare function ensureTableRegistered<Table extends SimpleTable>(simpleDB: SimpleDB<Table>, table: Table): void;
+export declare function retainRegisteredTables<Table extends SimpleTable>(simpleDB: SimpleDB<Table>, predicate: (table: Table) => boolean): void;
+//# sourceMappingURL=tableRegistry.d.ts.map

package/script/helpers/tableRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tableRegistry.d.ts","sourceRoot":"","sources":["../../src/helpers/tableRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAC;AACjD,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAevD,wBAAgB,uBAAuB,CAAC,KAAK,SAAS,WAAW,EAC/D,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,GACxB,IAAI,CAEN;AAED,wBAAgB,mBAAmB,CAAC,KAAK,SAAS,WAAW,EAC3D,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,GACxB,SAAS,KAAK,EAAE,CAElB;AAED,wBAAgB,oBAAoB,CAAC,KAAK,SAAS,WAAW,EAC5D,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,GACxB,SAAS,KAAK,EAAE,CAElB;AAED,wBAAgB,aAAa,CAAC,KAAK,SAAS,WAAW,EACrD,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,EACzB,KAAK,EAAE,KAAK,GACX,IAAI,CAaN;AAED,wBAAgB,qBAAqB,CAAC,KAAK,SAAS,WAAW,EAC7D,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,EACzB,KAAK,EAAE,KAAK,GACX,IAAI,CAKN;AAED,wBAAgB,sBAAsB,CAAC,KAAK,SAAS,WAAW,EAC9D,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,EACzB,SAAS,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,GACnC,IAAI,CAUN"}

package/script/helpers/tableRegistry.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initializeTableRegistry = initializeTableRegistry;
+exports.getRegisteredTables = getRegisteredTables;
+exports.listRegisteredTables = listRegisteredTables;
+exports.registerTable = registerTable;
+exports.ensureTableRegistered = ensureTableRegistered;
+exports.retainRegisteredTables = retainRegisteredTables;
+const tableGeneration_js_1 = require("./tableGeneration.js");
+const registries = new WeakMap();
+function getMutableTables(simpleDB) {
+    const tables = registries.get(simpleDB);
+    if (tables === undefined) {
+        throw new Error("The table registry has not been initialized.");
+    }
+    return tables;
+}
+function initializeTableRegistry(simpleDB) {
+    registries.set(simpleDB, []);
+}
+function getRegisteredTables(simpleDB) {
+    return getMutableTables(simpleDB);
+}
+function listRegisteredTables(simpleDB) {
+    return [...getMutableTables(simpleDB)];
+}
+function registerTable(simpleDB, table) {
+    const TableClass = simpleDB.tableClass;
+    if (!(table instanceof TableClass)) {
+        throw new Error(`The table must be an instance of ${TableClass.name}.`);
+    }
+    const tables = getMutableTables(simpleDB);
+    if (tables.some((registeredTable) => registeredTable.name === table.name)) {
+        throw new Error(`Table ${table.name} already exists.`);
+    }
+    tables.push(table);
+}
+function ensureTableRegistered(simpleDB, table) {
+    const tables = getMutableTables(simpleDB);
+    if (!tables.includes(table)) {
+        tables.push(table);
+    }
+}
+function retainRegisteredTables(simpleDB, predicate) {
+    const tables = getMutableTables(simpleDB);
+    const retained = tables.filter(predicate);
+    const retainedSet = new Set(retained);
+    for (const table of tables) {
+        if (!retainedSet.has(table)) {
+            (0, tableGeneration_js_1.markTableChanged)(table);
+        }
+    }
+    tables.splice(0, tables.length, ...retained);
+}

package/script/helpers/toDuckDBValue.d.ts

@@ -0,0 +1,4 @@
+import { type DuckDBValue } from "@duckdb/node-api";
+/** Converts a supported JavaScript data value to its DuckDB binding value. */
+export default function toDuckDBValue(value: unknown): DuckDBValue;
+//# sourceMappingURL=toDuckDBValue.d.ts.map

package/script/helpers/toDuckDBValue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toDuckDBValue.d.ts","sourceRoot":"","sources":["../../src/helpers/toDuckDBValue.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE1E,8EAA8E;AAC9E,MAAM,CAAC,OAAO,UAAU,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAgBjE"}

package/script/helpers/toDuckDBValue.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = toDuckDBValue;
+const node_api_1 = require("@duckdb/node-api");
+/** Converts a supported JavaScript data value to its DuckDB binding value. */
+function toDuckDBValue(value) {
+    if (value === null || value === undefined || Number.isNaN(value)) {
+        return null;
+    }
+    if (value instanceof Date) {
+        return new node_api_1.DuckDBTimestampValue(BigInt(value.getTime() * 1000));
+    }
+    if (typeof value === "string" || typeof value === "number" ||
+        typeof value === "boolean" || typeof value === "bigint") {
+        return value;
+    }
+    throw new Error(`Unknown bind value type ${typeof value} of ${String(value)}`);
+}

package/script/helpers/unifyColumns.d.ts

@@ -1,4 +1,9 @@
 import type SimpleTable from "../class/SimpleTable.js";
+/**
+ * Adds the columns missing from each table (filled with NULL) so all tables
+ * share the same columns. Runs immediately, without queueing, so it's safe
+ * inside a barrier's execute, which runs during a flush.
+ */
 export default function unifyColumns(allTables: SimpleTable[], allTypes: {
     [key: string]: string;
 }): Promise<{

package/script/helpers/unifyColumns.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"unifyColumns.d.ts","sourceRoot":"","sources":["../../src/helpers/unifyColumns.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAEvD,wBAA8B,YAAY,CACxC,SAAS,EAAE,WAAW,EAAE,EACxB,QAAQ,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE;;GAwCpC"}
+{"version":3,"file":"unifyColumns.d.ts","sourceRoot":"","sources":["../../src/helpers/unifyColumns.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAEvD;;;;GAIG;AACH,wBAA8B,YAAY,CACxC,SAAS,EAAE,WAAW,EAAE,EACxB,QAAQ,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE;;GAoCpC"}

package/script/helpers/unifyColumns.js

@@ -1,14 +1,33 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = unifyColumns;
+const quoteIdentifier_js_1 = __importDefault(require("./quoteIdentifier.js"));
+const mergeOptions_js_1 = __importDefault(require("./mergeOptions.js"));
+const queryDB_js_1 = __importDefault(require("./queryDB.js"));
+/**
+ * Adds the columns missing from each table (filled with NULL) so all tables
+ * share the same columns. Runs immediately, without queueing, so it's safe
+ * inside a barrier's execute, which runs during a flush.
+ */
 async function unifyColumns(allTables, allTypes) {
     const columnsAdded = {};
+    // Each table's columns are fetched once, instead of one hasColumn
+    // round-trip per column and table.
+    const existingColumns = new Map();
+    for (const table of allTables) {
+        existingColumns.set(table, new Set(await table.getColumns()));
+    }
     for (const column in allTypes) {
         for (const table of allTables) {
-            if (!(await table.hasColumn(column))) {
-                await table.addColumn(column, 
-                // Could be improved
-                allTypes[column].toLowerCase(), `null`);
+            if (!existingColumns.get(table).has(column)) {
+                await (0, queryDB_js_1.default)(table, `ALTER TABLE ${(0, quoteIdentifier_js_1.default)(table.name)} ADD ${(0, quoteIdentifier_js_1.default)(column)} ${allTypes[column]};`, (0, mergeOptions_js_1.default)(table, {
+                    table: table.name,
+                    method: "insertTables()",
+                    parameters: { column, type: allTypes[column] },
+                }));
                 if (!columnsAdded[table.name]) {
                     columnsAdded[table.name] = [];
                 }

package/script/helpers/validateNumericalAnalysis.d.ts

@@ -0,0 +1,25 @@
+import type { TableSchema } from "./pendingOps.js";
+/**
+ * Validates the column options shared by numerical pair analyses.
+ *
+ * @param types - The schema of the table being analyzed.
+ * @param options - The optional x and y columns selected by the caller.
+ * @param method - The SDA method performing the analysis.
+ * @param tableName - The name of the table being analyzed.
+ * @returns All numeric columns in the table schema.
+ *
+ * @example
+ * ```ts
+ * const columns = validateNumericalAnalysis(
+ *   { x: "DOUBLE", y: "BIGINT" },
+ *   { x: "x" },
+ *   "correlations()",
+ *   "measurements",
+ * );
+ * ```
+ */
+export default function validateNumericalAnalysis(types: TableSchema, options: {
+    x?: string;
+    y?: string;
+}, method: string, tableName: string): string[];
+//# sourceMappingURL=validateNumericalAnalysis.d.ts.map

package/script/helpers/validateNumericalAnalysis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateNumericalAnalysis.d.ts","sourceRoot":"","sources":["../../src/helpers/validateNumericalAnalysis.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,OAAO,UAAU,yBAAyB,CAC/C,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE;IAAE,CAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EACnC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAChB,MAAM,EAAE,CAoDV"}

package/script/helpers/validateNumericalAnalysis.js

@@ -0,0 +1,55 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = validateNumericalAnalysis;
+const quoteIdentifier_js_1 = __importDefault(require("./quoteIdentifier.js"));
+const keepNumericalColumns_js_1 = __importDefault(require("./keepNumericalColumns.js"));
+/**
+ * Validates the column options shared by numerical pair analyses.
+ *
+ * @param types - The schema of the table being analyzed.
+ * @param options - The optional x and y columns selected by the caller.
+ * @param method - The SDA method performing the analysis.
+ * @param tableName - The name of the table being analyzed.
+ * @returns All numeric columns in the table schema.
+ *
+ * @example
+ * ```ts
+ * const columns = validateNumericalAnalysis(
+ *   { x: "DOUBLE", y: "BIGINT" },
+ *   { x: "x" },
+ *   "correlations()",
+ *   "measurements",
+ * );
+ * ```
+ */
+function validateNumericalAnalysis(types, options, method, tableName) {
+    if (options.x === undefined && options.y !== undefined) {
+        throw new Error(`${method} options.y cannot be used without options.x. Provide options.x, or omit options.y to analyze every numeric column pair.`);
+    }
+    const numericalColumns = (0, keepNumericalColumns_js_1.default)(types);
+    const requestedColumns = [options.x, options.y].filter((column) => column !== undefined);
+    for (const column of requestedColumns) {
+        const type = types[column];
+        if (type === undefined) {
+            const availableColumns = Object.keys(types).sort();
+            throw new Error(`${method} could not find column ${(0, quoteIdentifier_js_1.default)(column)} in table ${(0, quoteIdentifier_js_1.default)(tableName)}. Available columns: ${availableColumns.map(quoteIdentifier_js_1.default).join(", ")}.`);
+        }
+        if (!numericalColumns.includes(column)) {
+            throw new Error(`${method} requires numeric columns, but column ${(0, quoteIdentifier_js_1.default)(column)} in table ${(0, quoteIdentifier_js_1.default)(tableName)} has type ${type}. Convert ${(0, quoteIdentifier_js_1.default)(column)} to a numeric type first.`);
+        }
+    }
+    if (options.y === undefined && numericalColumns.length < 2) {
+        const found = numericalColumns.length === 0
+            ? ""
+            : `: ${numericalColumns.map(quoteIdentifier_js_1.default).join(", ")}`;
+        const missingCount = 2 - numericalColumns.length;
+        const columnsToConvert = numericalColumns.length === 0
+            ? `${missingCount} columns`
+            : `${missingCount} more column${missingCount === 1 ? "" : "s"}`;
+        throw new Error(`${method} requires at least 2 numeric columns in table ${(0, quoteIdentifier_js_1.default)(tableName)}, but found ${numericalColumns.length}${found}. Convert at least ${columnsToConvert} to ${missingCount === 1 ? "a numeric type" : "numeric types"} first.`);
+    }
+    return numericalColumns;
+}

package/script/helpers/writeDbMetadata.d.ts

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

package/script/helpers/writeDbMetadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writeDbMetadata.d.ts","sourceRoot":"","sources":["../../src/helpers/writeDbMetadata.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAI7D,wBAA8B,eAAe,CAC3C,GAAG,EAAE,QAAQ,EACb,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,EAAE,CAAC,GACzC,OAAO,CAAC,IAAI,CAAC,CAUf"}

package/script/helpers/writeDbMetadata.js

@@ -0,0 +1,15 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = writeDbMetadata;
+const queryDbFile_js_1 = __importDefault(require("./queryDbFile.js"));
+const quoteIdentifier_js_1 = __importDefault(require("./quoteIdentifier.js"));
+const parseValue_js_1 = __importDefault(require("./parseValue.js"));
+async function writeDbMetadata(sdb, database, indexes) {
+    const catalog = (0, quoteIdentifier_js_1.default)(database);
+    await (0, queryDbFile_js_1.default)(sdb, `CREATE SCHEMA IF NOT EXISTS ${catalog}.__sda;
+     CREATE OR REPLACE TABLE ${catalog}.__sda.metadata AS
+     SELECT 1 AS version, ${(0, parseValue_js_1.default)(JSON.stringify(indexes))}::VARCHAR AS indexes;`);
+}

package/script/helpers/writeGeoData.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"writeGeoData.d.ts","sourceRoot":"","sources":["../../src/helpers/writeGeoData.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAEvD,wBAA8B,YAAY,CACxC,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IACP,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;CAClB,GACL,OAAO,CAAC,IAAI,CAAC,CAmGf"}
+{"version":3,"file":"writeGeoData.d.ts","sourceRoot":"","sources":["../../src/helpers/writeGeoData.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAGvD,wBAA8B,YAAY,CACxC,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IACP,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;CAClB,GACL,OAAO,CAAC,IAAI,CAAC,CAqFf"}