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

package/esm/helpers/quoteIdentifier.js

@@ -0,0 +1,17 @@
+/**
+ * Quotes one SQL identifier and escapes embedded double quotes.
+ * Use this for library-generated table, column, schema, database, and alias
+ * names. User-authored SQL expressions must remain unmodified.
+ *
+ * @param identifier - The identifier to quote.
+ * @returns The identifier wrapped in double quotes with embedded quotes doubled.
+ *
+ * @example
+ * ```ts
+ * quoteIdentifier('people "archive"');
+ * // '"people ""archive"""'
+ * ```
+ */
+export default function quoteIdentifier(identifier) {
+    return `"${identifier.replaceAll('"', '""')}"`;
+}

package/esm/helpers/quoteQualifiedIdentifier.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Quotes a SQL identifier together with the relation that owns it.
+ *
+ * Qualifying column references prevents DuckDB from resolving a relation name
+ * as its row struct when a missing column has the same name as the relation.
+ *
+ * @param relation - The table or relation containing the identifier.
+ * @param identifier - The identifier to qualify.
+ * @returns The separately quoted relation and identifier joined by a period.
+ *
+ * @example
+ * ```ts
+ * quoteQualifiedIdentifier("people", "full name");
+ * // '"people"."full name"'
+ * ```
+ */
+export default function quoteQualifiedIdentifier(relation: string, identifier: string): string;
+//# sourceMappingURL=quoteQualifiedIdentifier.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"quoteQualifiedIdentifier.d.ts","sourceRoot":"","sources":["../../src/helpers/quoteQualifiedIdentifier.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,OAAO,UAAU,wBAAwB,CAC9C,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,MAAM,CAER"}

package/esm/helpers/quoteQualifiedIdentifier.js

@@ -0,0 +1,20 @@
+import quoteIdentifier from "./quoteIdentifier.js";
+/**
+ * Quotes a SQL identifier together with the relation that owns it.
+ *
+ * Qualifying column references prevents DuckDB from resolving a relation name
+ * as its row struct when a missing column has the same name as the relation.
+ *
+ * @param relation - The table or relation containing the identifier.
+ * @param identifier - The identifier to qualify.
+ * @returns The separately quoted relation and identifier joined by a period.
+ *
+ * @example
+ * ```ts
+ * quoteQualifiedIdentifier("people", "full name");
+ * // '"people"."full name"'
+ * ```
+ */
+export default function quoteQualifiedIdentifier(relation, identifier) {
+    return `${quoteIdentifier(relation)}.${quoteIdentifier(identifier)}`;
+}

package/esm/helpers/readDbMetadata.d.ts

@@ -0,0 +1,5 @@
+import type SimpleDB from "../class/SimpleDB.js";
+import type { IndexDefinition } from "./indexDefinitions.js";
+/** Reads embedded SDA metadata when present. */
+export default function readDbMetadata(sdb: SimpleDB, database: string): Promise<Record<string, IndexDefinition[]>>;
+//# sourceMappingURL=readDbMetadata.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"readDbMetadata.d.ts","sourceRoot":"","sources":["../../src/helpers/readDbMetadata.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAI7D,gDAAgD;AAChD,wBAA8B,cAAc,CAC1C,GAAG,EAAE,QAAQ,EACb,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,EAAE,CAAC,CAAC,CA0B5C"}

package/esm/helpers/readDbMetadata.js

@@ -0,0 +1,55 @@
+import queryDbFile from "./queryDbFile.js";
+import quoteIdentifier from "./quoteIdentifier.js";
+import parseValue from "./parseValue.js";
+/** Reads embedded SDA metadata when present. */
+export default async function readDbMetadata(sdb, database) {
+    const schemas = await queryDbFile(sdb, `SELECT schema_name FROM duckdb_schemas()
+     WHERE database_name = ${parseValue(database)} AND schema_name = '__sda';`, { returnData: true });
+    if (schemas.length > 0) {
+        const rows = await queryDbFile(sdb, `SELECT version, indexes FROM ${quoteIdentifier(database)}.__sda.metadata;`, { returnData: true });
+        if (rows.length !== 1 || rows[0].version !== 1 ||
+            typeof rows[0].indexes !== "string") {
+            throw new Error("Unsupported SDA database metadata in the reserved __sda schema.");
+        }
+        return validateIndexes(JSON.parse(rows[0].indexes));
+    }
+    return {};
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function validateIndexes(value) {
+    if (!isRecord(value))
+        throw new Error("Invalid SDA index metadata.");
+    for (const definitions of Object.values(value)) {
+        if (!Array.isArray(definitions)) {
+            throw new Error("Invalid SDA index metadata.");
+        }
+        for (const definition of definitions) {
+            if (!isRecord(definition) || typeof definition.name !== "string" ||
+                !isRecord(definition.options)) {
+                throw new Error("Invalid SDA index definition.");
+            }
+            const options = definition.options;
+            if (definition.kind === "fts") {
+                if (typeof definition.idColumn !== "string" ||
+                    typeof definition.textColumn !== "string" ||
+                    ["stemmer", "stopwords", "ignore"].some((key) => options[key] !== undefined && typeof options[key] !== "string") ||
+                    ["stripAccents", "lower"].some((key) => options[key] !== undefined && typeof options[key] !== "boolean")) {
+                    throw new Error("Invalid SDA FTS index definition.");
+                }
+            }
+            else if (definition.kind === "vss") {
+                if (typeof definition.column !== "string" ||
+                    ["efConstruction", "efSearch", "M"].some((key) => options[key] !== undefined &&
+                        (typeof options[key] !== "number" || !Number.isFinite(options[key])))) {
+                    throw new Error("Invalid SDA VSS index definition.");
+                }
+            }
+            else {
+                throw new Error("Unsupported SDA index definition.");
+            }
+        }
+    }
+    return value;
+}

package/esm/helpers/removeColumnsNow.d.ts

@@ -0,0 +1,8 @@
+import type SimpleTable from "../class/SimpleTable.js";
+/**
+ * Drops columns immediately, without queueing. For use inside a barrier's
+ * execute, which runs during a flush: a sync builder method called there
+ * would queue an operation for the next flush instead of running now.
+ */
+export default function removeColumnsNow(simpleTable: SimpleTable, columns: string[], method: string): Promise<void>;
+//# sourceMappingURL=removeColumnsNow.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"removeColumnsNow.d.ts","sourceRoot":"","sources":["../../src/helpers/removeColumnsNow.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAEvD;;;;GAIG;AACH,wBAA8B,gBAAgB,CAC5C,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,MAAM,EAAE,EACjB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAgBf"}

package/esm/helpers/removeColumnsNow.js

@@ -0,0 +1,15 @@
+import quoteIdentifier from "./quoteIdentifier.js";
+import mergeOptions from "./mergeOptions.js";
+import queryDB from "./queryDB.js";
+/**
+ * Drops columns immediately, without queueing. For use inside a barrier's
+ * execute, which runs during a flush: a sync builder method called there
+ * would queue an operation for the next flush instead of running now.
+ */
+export default async function removeColumnsNow(simpleTable, columns, method) {
+    await queryDB(simpleTable, columns.map((d) => `ALTER TABLE ${quoteIdentifier(simpleTable.name)} DROP ${quoteIdentifier(d)};`).join("\n"), mergeOptions(simpleTable, {
+        table: simpleTable.name,
+        method,
+        parameters: { columns },
+    }));
+}

package/esm/helpers/resolveOutputTable.d.ts

@@ -0,0 +1,9 @@
+import type SimpleTable from "../class/SimpleTable.js";
+/**
+ * Resolves `outputTable: true` into an auto-generated table name
+ * ("table0", "table1", ...), incrementing the database's shared counter so
+ * concurrent auto-named tables never collide. A string, `false`, or
+ * `undefined` value passes through unchanged.
+ */
+export default function resolveOutputTable(simpleTable: SimpleTable, outputTable: string | boolean | undefined): string | boolean | undefined;
+//# sourceMappingURL=resolveOutputTable.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resolveOutputTable.d.ts","sourceRoot":"","sources":["../../src/helpers/resolveOutputTable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,CAAC,OAAO,UAAU,kBAAkB,CACxC,WAAW,EAAE,WAAW,EACxB,WAAW,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,GACxC,MAAM,GAAG,OAAO,GAAG,SAAS,CAO9B"}

package/esm/helpers/resolveOutputTable.js

@@ -0,0 +1,14 @@
+/**
+ * Resolves `outputTable: true` into an auto-generated table name
+ * ("table0", "table1", ...), incrementing the database's shared counter so
+ * concurrent auto-named tables never collide. A string, `false`, or
+ * `undefined` value passes through unchanged.
+ */
+export default function resolveOutputTable(simpleTable, outputTable) {
+    if (outputTable === true) {
+        const name = `table${simpleTable.sdb.tableIncrement}`;
+        simpleTable.sdb.tableIncrement += 1;
+        return name;
+    }
+    return outputTable;
+}

package/esm/helpers/runQuery.d.ts

@@ -1,14 +1,17 @@
-import type { DuckDBConnection } from "@duckdb/node-api";
-export default function runQuery(query: string, connection: DuckDBConnection, returnDataFromQuery: boolean, options: {
-    debug: boolean;
+import { type DuckDBConnection, type DuckDBType, type DuckDBValue } from "@duckdb/node-api";
+type RunQueryOptions = {
     method: string | null;
     parameters: {
         [key: string]: unknown;
     } | null;
-    types?: {
-        [key: string]: string;
-    };
-}): Promise<{
-    [key: string]: number | string | Date | boolean | null;
+    table?: string | null;
+    values?: DuckDBValue[];
+    logSQL: boolean;
+    explainSQL: boolean;
+};
+export declare function makeConverter(type: DuckDBType, columnName: string, tableName?: string | null): (value: DuckDBValue) => unknown;
+export default function runQuery(query: string, connection: DuckDBConnection, returnData: boolean, options: RunQueryOptions): Promise<{
+    [key: string]: unknown;
 }[] | null>;
+export {};
 //# sourceMappingURL=runQuery.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"runQuery.d.ts","sourceRoot":"","sources":["../../src/helpers/runQuery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGzD,wBAA8B,QAAQ,CACpC,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,gBAAgB,EAC5B,mBAAmB,EAAE,OAAO,EAC5B,OAAO,EAAE;IACP,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9C,KAAK,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;CACnC,GACA,OAAO,CACN;IACA,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,OAAO,GAAG,IAAI,CAAC;CACxD,EAAE,GACD,IAAI,CACP,CA4BA"}
+{"version":3,"file":"runQuery.d.ts","sourceRoot":"","sources":["../../src/helpers/runQuery.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,gBAAgB,EAIrB,KAAK,UAAU,EAEf,KAAK,WAAW,EAIjB,MAAM,kBAAkB,CAAC;AAI1B,KAAK,eAAe,GAAG;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9C,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;CACrB,CAAC;AAqDF,wBAAgB,aAAa,CAC3B,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,MAAM,GAAG,IAAW,GAC9B,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAsCjC;AAED,wBAA8B,QAAQ,CACpC,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,gBAAgB,EAC5B,UAAU,EAAE,OAAO,EACnB,OAAO,EAAE,eAAe,GACvB,OAAO,CACN;IACA,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,EAAE,GACD,IAAI,CACP,CA6DA"}

package/esm/helpers/runQuery.js

@@ -1,26 +1,129 @@
-import convertForJS from "./convertForJS.js";
-export default async function runQuery(query, connection, returnDataFromQuery, options) {
+import quoteIdentifier from "./quoteIdentifier.js";
+import { DuckDBTimestampValue, DuckDBTypeId, JsonDuckDBValueConverter, } from "@duckdb/node-api";
+import SDAError from "../class/SDAError.js";
+import observeQuery from "./observeQuery.js";
+const msPerDay = 24 * 60 * 60 * 1000;
+const maxSafeInteger = BigInt(Number.MAX_SAFE_INTEGER);
+const minSafeInteger = BigInt(Number.MIN_SAFE_INTEGER);
+// Columns already warned about for precision loss (keyed by table and
+// column), so each column warns only once.
+const warnedUnsafeIntegerColumns = new Set();
+function makeIntegerConverter(columnName, tableName) {
+    const warnKey = `${tableName ?? ""}\0${columnName}`;
+    return (value) => {
+        if (value === null) {
+            return null;
+        }
+        const bigintValue = value;
+        if ((bigintValue > maxSafeInteger || bigintValue < minSafeInteger) &&
+            !warnedUnsafeIntegerColumns.has(warnKey)) {
+            warnedUnsafeIntegerColumns.add(warnKey);
+            console.warn(`SDA: Column ${quoteIdentifier(columnName)}${tableName === null ? "" : ` of table ${quoteIdentifier(tableName)}`} has at least one value exceeding Number.MAX_SAFE_INTEGER. Converted numbers may lose precision.`);
+        }
+        return Number(bigintValue);
+    };
+}
+function utcTimestampTzValue(value) {
+    if (value === null) {
+        return null;
+    }
+    const timestamp = new DuckDBTimestampValue(value.micros).toString();
+    return timestamp === "infinity" || timestamp === "-infinity"
+        ? timestamp
+        : `${timestamp}+00`;
+}
+const utcJsonValueConverter = (value, type, _converter) => type.typeId === DuckDBTypeId.TIMESTAMP_TZ
+    ? utcTimestampTzValue(value)
+    : JsonDuckDBValueConverter(value, type, utcJsonValueConverter);
+export function makeConverter(type, columnName, tableName = null) {
+    const typeString = type.toString();
+    if (typeString.toLowerCase().includes("geometry")) {
+        const placeholder = `GEOM(${typeString.replace("GEOMETRY('", "").replace("')", "")})`;
+        return (value) => (value === null ? null : placeholder);
+    }
+    if (typeString.includes("FLOAT[")) {
+        const placeholder = `<${typeString}>`;
+        return (value) => (value === null ? null : placeholder);
+    }
+    switch (type.typeId) {
+        case DuckDBTypeId.DATE:
+            return (value) => value === null
+                ? null
+                : new Date(value.days * msPerDay);
+        case DuckDBTypeId.TIMESTAMP:
+            return (value) => {
+                if (value === null) {
+                    return null;
+                }
+                const micros = value.micros;
+                // Floor division, so sub-millisecond precision truncates toward
+                // the past for dates before the epoch too.
+                const ms = micros >= 0n ? micros / 1000n : (micros - 999n) / 1000n;
+                return new Date(Number(ms));
+            };
+        case DuckDBTypeId.TIMESTAMP_TZ:
+            return utcTimestampTzValue;
+        case DuckDBTypeId.BIGINT:
+        case DuckDBTypeId.HUGEINT:
+            return makeIntegerConverter(columnName, tableName);
+        default:
+            return (value) => utcJsonValueConverter(value, type, utcJsonValueConverter);
+    }
+}
+export default async function runQuery(query, connection, returnData, options) {
+    const values = options.values ?? [];
     try {
-        if (returnDataFromQuery) {
-            const reader = await connection.runAndReadAll(query);
-            const rows = reader.getRowObjectsJson();
-            if (options.types) {
-                convertForJS(rows, options.types);
+        await observeQuery(connection, query, values, options);
+        if (returnData) {
+            const result = values.length === 0
+                ? await connection.run(query)
+                : await connection.run(query, values);
+            const columnNames = result.deduplicatedColumnNames();
+            const columnTypes = result.columnTypes();
+            if (options.method === "getData()" &&
+                columnTypes.some((type) => type.toString().toLowerCase().includes("geometry"))) {
+                throw new Error("The query returns geometry columns. Use getGeoData() instead.");
+            }
+            const converters = columnTypes.map((type, i) => makeConverter(type, columnNames[i], options.table ?? null));
+            const columnCount = columnNames.length;
+            // The result is converted chunk by chunk, so no intermediate row-major
+            // copy of the whole result is materialized.
+            const rows = [];
+            while (true) {
+                const chunk = await result.fetchChunk();
+                if (chunk === null || chunk === undefined || chunk.rowCount === 0) {
+                    break;
+                }
+                const base = rows.length;
+                for (let i = 0; i < chunk.rowCount; i++) {
+                    rows.push({});
+                }
+                for (let j = 0; j < columnCount; j++) {
+                    const columnName = columnNames[j];
+                    const converter = converters[j];
+                    chunk.visitColumnValues(j, (value, rowIndex) => {
+                        rows[base + rowIndex][columnName] = converter(value);
+                    });
+                }
             }
             return rows;
         }
         else {
-            await connection.run(query);
+            if (values.length === 0) {
+                await connection.run(query);
+            }
+            else {
+                await connection.run(query, values);
+            }
             return null;
         }
     }
     catch (error) {
-        console.warn(error);
-        if (options.debug === false) {
-            console.log("SDA: method causing error =>", options.method);
-            console.log("parameters:", options.parameters);
-            console.log("query:", query);
-        }
-        throw error;
+        throw new SDAError({
+            method: options.method,
+            parameters: options.parameters,
+            query,
+            cause: error,
+        });
     }
 }

package/esm/helpers/serializeCacheInputs.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Converts cache inputs to a deterministic, type-tagged representation.
+ * SimpleTable values are represented by their name and current generation.
+ */
+export default function serializeCacheInputs(inputs: readonly unknown[]): string;
+/** Returns a user-facing cache diagnostic label for supported input values. */
+export declare function getCacheInputLabel(value: unknown): string | undefined;
+//# sourceMappingURL=serializeCacheInputs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"serializeCacheInputs.d.ts","sourceRoot":"","sources":["../../src/helpers/serializeCacheInputs.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,MAAM,CAAC,OAAO,UAAU,oBAAoB,CAC1C,MAAM,EAAE,SAAS,OAAO,EAAE,GACzB,MAAM,CASR;AAED,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAIrE"}

package/esm/helpers/serializeCacheInputs.js

@@ -0,0 +1,113 @@
+import SimpleTable from "../class/SimpleTable.js";
+import { getTableGeneration } from "./tableGeneration.js";
+/**
+ * Converts cache inputs to a deterministic, type-tagged representation.
+ * SimpleTable values are represented by their name and current generation.
+ */
+export default function serializeCacheInputs(inputs) {
+    if (!Array.isArray(inputs)) {
+        throw new TypeError("cache() options.inputs must be an array.");
+    }
+    return serializeValue(inputs, "inputs", new Set());
+}
+/** Returns a user-facing cache diagnostic label for supported input values. */
+export function getCacheInputLabel(value) {
+    return value instanceof SimpleTable
+        ? `table ${JSON.stringify(value.name)}`
+        : undefined;
+}
+function serializeValue(value, path, ancestors) {
+    if (value === null) {
+        return JSON.stringify(["null"]);
+    }
+    switch (typeof value) {
+        case "undefined":
+            return JSON.stringify(["undefined"]);
+        case "boolean":
+            return JSON.stringify(["boolean", value]);
+        case "string":
+            return JSON.stringify(["string", value]);
+        case "number":
+            return serializeNumber(value);
+        case "bigint":
+            return JSON.stringify(["bigint", value.toString()]);
+        case "function":
+            return JSON.stringify([
+                "function",
+                Function.prototype.toString.call(value),
+            ]);
+        case "symbol":
+            throw new TypeError(`cache() ${path} cannot be a symbol.`);
+    }
+    if (value instanceof SimpleTable) {
+        return JSON.stringify([
+            "SimpleTable",
+            value.name,
+            getTableGeneration(value),
+        ]);
+    }
+    if (value instanceof Date) {
+        if (Number.isNaN(value.getTime())) {
+            throw new TypeError(`cache() ${path} is an invalid Date.`);
+        }
+        return JSON.stringify(["Date", value.toISOString()]);
+    }
+    if (ancestors.has(value)) {
+        throw new TypeError(`cache() ${path} is cyclic.`);
+    }
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            const serializedItems = [];
+            for (let i = 0; i < value.length; i++) {
+                serializedItems.push(serializeValue(value[i], `${path}[${i}]`, ancestors));
+            }
+            return JSON.stringify(["array", serializedItems]);
+        }
+        if (!isPlainObject(value)) {
+            const name = value.constructor?.name || "unknown";
+            throw new TypeError(`cache() ${path} is an unsupported ${name} instance. Pass its deterministic state instead.`);
+        }
+        if (Object.getOwnPropertySymbols(value).length > 0) {
+            throw new TypeError(`cache() ${path} cannot have symbol properties.`);
+        }
+        const serializedEntries = [];
+        for (const key of Object.keys(value).sort()) {
+            serializedEntries.push([
+                key,
+                serializeValue(value[key], propertyPath(path, key), ancestors),
+            ]);
+        }
+        return JSON.stringify(["object", serializedEntries]);
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+function serializeNumber(value) {
+    if (Number.isNaN(value)) {
+        return JSON.stringify(["number", "NaN"]);
+    }
+    if (value === Infinity) {
+        return JSON.stringify(["number", "Infinity"]);
+    }
+    if (value === -Infinity) {
+        return JSON.stringify(["number", "-Infinity"]);
+    }
+    if (Object.is(value, -0)) {
+        return JSON.stringify(["number", "-0"]);
+    }
+    return JSON.stringify(["number", value.toString()]);
+}
+function isPlainObject(value) {
+    if (value === null || typeof value !== "object") {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function propertyPath(path, key) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key)
+        ? `${path}.${key}`
+        : `${path}[${JSON.stringify(key)}]`;
+}

package/esm/helpers/setDbProps.d.ts

@@ -1,3 +1,6 @@
 import type SimpleDB from "../class/SimpleDB.js";
-export default function setDbProps(simpleDB: SimpleDB, allIndexesFile: string): Promise<void>;
+import type { IndexDefinition } from "./indexDefinitions.js";
+export default function setDbProps(simpleDB: SimpleDB, indexes: {
+    [table: string]: IndexDefinition[];
+}): Promise<void>;
 //# sourceMappingURL=setDbProps.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"setDbProps.d.ts","sourceRoot":"","sources":["../../src/helpers/setDbProps.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAC;AAEjD,wBAA8B,UAAU,CACtC,QAAQ,EAAE,QAAQ,EAClB,cAAc,EAAE,MAAM,iBA2BvB"}
+{"version":3,"file":"setDbProps.d.ts","sourceRoot":"","sources":["../../src/helpers/setDbProps.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAI7D,wBAA8B,UAAU,CACtC,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE;IAAE,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,EAAE,CAAA;CAAE,iBA2BhD"}

package/esm/helpers/setDbProps.js

@@ -1,21 +1,23 @@
-import { existsSync, readFileSync } from "node:fs";
-export default async function setDbProps(simpleDB, allIndexesFile) {
+import { markTableChanged } from "./tableGeneration.js";
+import { registerTable } from "./tableRegistry.js";
+export default 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,
+            });
+            registerTable(simpleDB, instance);
+            markTableChanged(instance);
         }
     }
-    if (existsSync(allIndexesFile)) {
-        const indexes = JSON.parse(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/esm/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/esm/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/esm/helpers/statCanCache.js

@@ -0,0 +1,38 @@
+import fileCache, { createFileCacheId } from "./fileCache.js";
+import mergeOptions from "./mergeOptions.js";
+import parseValue from "./parseValue.js";
+import queryDB from "./queryDB.js";
+import quoteIdentifier from "./quoteIdentifier.js";
+const CACHE_DIRECTORY = ".sda-cache/statcan";
+const CACHE_FORMAT_VERSION = "statcan-parquet-v1";
+export function createStatCanCacheId(pid, lang) {
+    return createFileCacheId("statcan", [CACHE_FORMAT_VERSION, pid, lang]);
+}
+export async function useStatCanCache(table, id, enabled, ttl, parameters, compute) {
+    await fileCache(table, {
+        directory: CACHE_DIRECTORY,
+        enabled,
+        extension: "parquet",
+        formatVersion: CACHE_FORMAT_VERSION,
+        id,
+        method: "loadStatCanData()",
+        ttl,
+        load: async (file) => {
+            await queryDB(table, `CREATE OR REPLACE TABLE ${quoteIdentifier(table.name)} AS
+        SELECT * FROM read_parquet(${parseValue(file)});`, mergeOptions(table, {
+                table: table.name,
+                method: "loadStatCanData()",
+                parameters,
+            }));
+        },
+        compute,
+        write: async (file) => {
+            await queryDB(table, `COPY ${quoteIdentifier(table.name)} TO ${parseValue(file)}
+        WITH (FORMAT PARQUET);`, mergeOptions(table, {
+                table: table.name,
+                method: "loadStatCanData()",
+                parameters,
+            }));
+        },
+    });
+}

package/esm/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/esm/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/esm/helpers/stringToArray.js

@@ -1,6 +1,20 @@
+/**
+ * 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) {
     if (Array.isArray(argument)) {
-        return argument;
+        return [...argument];
     }
     else if (typeof argument === "string") {
         return [argument];