@nshiab/simple-data-analysis-core 2.0.8 → 2.1.0

package/script/helpers/quoteIdentifier.d.ts

@@ -3,14 +3,15 @@
  * 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"""'
  * ```
+ *
+ * @param identifier - The identifier to quote.
+ *
+ * @returns The identifier wrapped in double quotes with embedded quotes doubled.
  */
 export default function quoteIdentifier(identifier: string): string;
 //# sourceMappingURL=quoteIdentifier.d.ts.map

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

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

package/script/helpers/quoteIdentifier.js

@@ -6,14 +6,15 @@ exports.default = quoteIdentifier;
  * 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"""'
  * ```
+ *
+ * @param identifier - The identifier to quote.
+ *
+ * @returns The identifier wrapped in double quotes with embedded quotes doubled.
  */
 function quoteIdentifier(identifier) {
     return `"${identifier.replaceAll('"', '""')}"`;

package/script/helpers/quoteQualifiedIdentifier.d.ts

@@ -4,15 +4,17 @@
  * 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"'
  * ```
+ *
+ * @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.
  */
 export default function quoteQualifiedIdentifier(relation: string, identifier: string): string;
 //# sourceMappingURL=quoteQualifiedIdentifier.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"quoteQualifiedIdentifier.d.ts","sourceRoot":"","sources":["../../src/helpers/quoteQualifiedIdentifier.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,OAAO,UAAU,wBAAwB,CAC9C,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,MAAM,CAER"}

package/script/helpers/quoteQualifiedIdentifier.js

@@ -11,15 +11,17 @@ const quoteIdentifier_js_1 = __importDefault(require("./quoteIdentifier.js"));
  * 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"'
  * ```
+ *
+ * @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.
  */
 function quoteQualifiedIdentifier(relation, identifier) {
     return `${(0, quoteIdentifier_js_1.default)(relation)}.${(0, quoteIdentifier_js_1.default)(identifier)}`;

package/script/helpers/readScalarNumber.d.ts

@@ -0,0 +1,3 @@
+import type { DuckDBConnection } from "@duckdb/node-api";
+export default function readScalarNumber(connection: DuckDBConnection, sql: string): Promise<number>;
+//# sourceMappingURL=readScalarNumber.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"readScalarNumber.d.ts","sourceRoot":"","sources":["../../src/helpers/readScalarNumber.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGzD,wBAA8B,gBAAgB,CAC5C,UAAU,EAAE,gBAAgB,EAC5B,GAAG,EAAE,MAAM,mBAGZ"}

package/script/helpers/readScalarNumber.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = readScalarNumber;
+// For internal queries returning a single numeric value, such as row counts.
+async function readScalarNumber(connection, sql) {
+    return Number((await connection.runAndReadAll(sql)).getRowsJS()[0][0]);
+}

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

@@ -1 +1 @@
-{"version":3,"file":"runQuery.d.ts","sourceRoot":"","sources":["../../src/helpers/runQuery.ts"],"names":[],"mappings":"AAEA,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;AA8CF,wBAAgB,aAAa,CAC3B,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,MAAM,GAAG,IAAW,GAC9B,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAoCjC;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,CAoEA"}
+{"version":3,"file":"runQuery.d.ts","sourceRoot":"","sources":["../../src/helpers/runQuery.ts"],"names":[],"mappings":"AAEA,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;AA8CF,wBAAgB,aAAa,CAC3B,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,MAAM,GAAG,IAAW,GAC9B,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAoCjC;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,CAiFA"}

package/script/helpers/runQuery.js

@@ -106,9 +106,23 @@ async function runQuery(query, connection, returnData, options) {
                 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);
-                    });
+                    if (columnName === "__proto__") {
+                        // This valid SQL identifier must define data, not invoke Node's
+                        // legacy Object.prototype setter. Keep ordinary columns fast.
+                        chunk.visitColumnValues(j, (value, rowIndex) => {
+                            Object.defineProperty(rows[base + rowIndex], columnName, {
+                                value: converter(value),
+                                enumerable: true,
+                                configurable: true,
+                                writable: true,
+                            });
+                        });
+                    }
+                    else {
+                        chunk.visitColumnValues(j, (value, rowIndex) => {
+                            rows[base + rowIndex][columnName] = converter(value);
+                        });
+                    }
                 }
             }
             return rows;

package/script/helpers/selectFuzzyReplacements.d.ts

@@ -0,0 +1,11 @@
+export type FuzzyPair = {
+    left_value: string;
+    right_value: string;
+    left_cnt: number;
+    right_cnt: number;
+    score: number;
+};
+export type FuzzyStrategy = "mostCommon" | "longestString" | "shortestString" | "mostCentral" | "maxScore";
+/** Groups matching values transitively and chooses each component's canonical value. */
+export default function selectFuzzyReplacements(pairs: FuzzyPair[], strategy: FuzzyStrategy): Map<string, string>;
+//# sourceMappingURL=selectFuzzyReplacements.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"selectFuzzyReplacements.d.ts","sourceRoot":"","sources":["../../src/helpers/selectFuzzyReplacements.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,aAAa,GACrB,YAAY,GACZ,eAAe,GACf,gBAAgB,GAChB,aAAa,GACb,UAAU,CAAC;AAEf,wFAAwF;AACxF,MAAM,CAAC,OAAO,UAAU,uBAAuB,CAC7C,KAAK,EAAE,SAAS,EAAE,EAClB,QAAQ,EAAE,aAAa,GACtB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CA8HrB"}

package/script/helpers/selectFuzzyReplacements.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = selectFuzzyReplacements;
+/** Groups matching values transitively and chooses each component's canonical value. */
+function selectFuzzyReplacements(pairs, strategy) {
+    // Build count map from the pairs — no separate query needed.
+    const countMap = new Map();
+    for (const { left_value, left_cnt, right_value, right_cnt } of pairs) {
+        countMap.set(left_value, Number(left_cnt));
+        countMap.set(right_value, Number(right_cnt));
+    }
+    // Union-Find — only over values that actually participate in a pair.
+    const parent = new Map();
+    const find = (x) => {
+        if (!parent.has(x))
+            parent.set(x, x);
+        if (parent.get(x) !== x)
+            parent.set(x, find(parent.get(x)));
+        return parent.get(x);
+    };
+    const union = (a, b) => {
+        const ra = find(a);
+        const rb = find(b);
+        if (ra !== rb)
+            parent.set(ra, rb);
+    };
+    for (const v of countMap.keys())
+        find(v);
+    for (const { left_value, right_value } of pairs) {
+        union(left_value, right_value);
+    }
+    // Group values by their cluster root.
+    const clusters = new Map();
+    for (const v of countMap.keys()) {
+        const root = find(v);
+        if (!clusters.has(root))
+            clusters.set(root, []);
+        clusters.get(root).push(v);
+    }
+    // Pick the canonical value for each cluster.
+    const replacement = new Map();
+    // Every pair belongs to exactly one component. Accumulate scores globally,
+    // at most once, instead of scanning all pairs separately for each cluster.
+    // Keep this lazy: distinct counts/lengths can choose a winner without scores.
+    // Iterating in the original pair order also preserves floating-point ties.
+    let scoreSum = null;
+    const getScoreSum = () => {
+        if (scoreSum === null) {
+            scoreSum = new Map();
+            for (const { left_value, right_value, score } of pairs) {
+                scoreSum.set(left_value, (scoreSum.get(left_value) ?? 0) + score);
+                scoreSum.set(right_value, (scoreSum.get(right_value) ?? 0) + score);
+            }
+        }
+        return scoreSum;
+    };
+    let scoreMax = null;
+    const getScoreMax = () => {
+        if (scoreMax === null) {
+            scoreMax = new Map();
+            for (const { left_value, right_value, score } of pairs) {
+                scoreMax.set(left_value, Math.max(scoreMax.get(left_value) ?? 0, score));
+                scoreMax.set(right_value, Math.max(scoreMax.get(right_value) ?? 0, score));
+            }
+        }
+        return scoreMax;
+    };
+    for (const members of clusters.values()) {
+        if (members.length === 1)
+            continue;
+        // Sum-based comparator: highest total similarity, then alphabetical.
+        const byScore = (a, b) => {
+            const sum = getScoreSum();
+            const sa = sum.get(a) ?? 0;
+            const sb = sum.get(b) ?? 0;
+            if (sa !== sb)
+                return sa > sb ? a : b;
+            return a <= b ? a : b; // alphabetical tie-break
+        };
+        // Max-based comparator: highest single-pair score, then sum, then alphabetical.
+        const byMaxScore = (a, b) => {
+            const mx = getScoreMax();
+            const ma = mx.get(a) ?? 0;
+            const mb = mx.get(b) ?? 0;
+            if (ma !== mb)
+                return ma > mb ? a : b;
+            return byScore(a, b); // sum then alphabetical tie-break
+        };
+        let canonical;
+        if (strategy === "longestString") {
+            canonical = members.reduce((a, b) => {
+                if (a.length !== b.length)
+                    return a.length > b.length ? a : b;
+                return byScore(a, b);
+            });
+        }
+        else if (strategy === "shortestString") {
+            canonical = members.reduce((a, b) => {
+                if (a.length !== b.length)
+                    return a.length < b.length ? a : b;
+                return byScore(a, b);
+            });
+        }
+        else if (strategy === "mostCommon") {
+            canonical = members.reduce((a, b) => {
+                const ca = countMap.get(a) ?? 0;
+                const cb = countMap.get(b) ?? 0;
+                if (ca !== cb)
+                    return ca > cb ? a : b;
+                return byScore(a, b);
+            });
+        }
+        else if (strategy === "mostCentral") {
+            // Most central string — highest total similarity to all other cluster members.
+            canonical = members.reduce((a, b) => byScore(a, b));
+        }
+        else {
+            // "maxScore": the string participating in the single highest-scoring pair.
+            canonical = members.reduce((a, b) => byMaxScore(a, b));
+        }
+        for (const m of members) {
+            if (m !== canonical)
+                replacement.set(m, canonical);
+        }
+    }
+    return replacement;
+}

package/script/helpers/stabilizeCosineVectors.d.ts

@@ -0,0 +1,14 @@
+import type { DuckDBConnection } from "@duckdb/node-api";
+/**
+ * Stabilizes cosine arithmetic in a caller-owned private vector relation.
+ * The already-quoted relation has unique vertex ids and a fixed-size DOUBLE
+ * vec column. Source data must be retained separately by the caller.
+ *
+ * Safe vectors keep their existing arithmetic and tie behavior. Outside the
+ * safe range, divide by the largest absolute component, then by the resulting
+ * length. This preserves direction without overflowing or underflowing norms.
+ * The bounds keep squared-norm products between 1e-300 and 1e300, with room
+ * for rounding. Only the private vec column changes; no scratch tables remain.
+ */
+export default function stabilizeCosineVectors(connection: DuckDBConnection, rows: string): Promise<void>;
+//# sourceMappingURL=stabilizeCosineVectors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stabilizeCosineVectors.d.ts","sourceRoot":"","sources":["../../src/helpers/stabilizeCosineVectors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGzD;;;;;;;;;;GAUG;AACH,wBAA8B,sBAAsB,CAClD,UAAU,EAAE,gBAAgB,EAC5B,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CA4Bf"}

package/script/helpers/stabilizeCosineVectors.js

@@ -0,0 +1,40 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = stabilizeCosineVectors;
+const readScalarNumber_js_1 = __importDefault(require("./readScalarNumber.js"));
+/**
+ * Stabilizes cosine arithmetic in a caller-owned private vector relation.
+ * The already-quoted relation has unique vertex ids and a fixed-size DOUBLE
+ * vec column. Source data must be retained separately by the caller.
+ *
+ * Safe vectors keep their existing arithmetic and tie behavior. Outside the
+ * safe range, divide by the largest absolute component, then by the resulting
+ * length. This preserves direction without overflowing or underflowing norms.
+ * The bounds keep squared-norm products between 1e-300 and 1e300, with room
+ * for rounding. Only the private vec column changes; no scratch tables remain.
+ */
+async function stabilizeCosineVectors(connection, rows) {
+    if (await (0, readScalarNumber_js_1.default)(connection, `SELECT count(*) FROM ${rows} WHERE vec IS NULL
+        OR len(vec)=0 OR list_count(vec)!=len(vec)
+        OR NOT list_bool_and(list_transform(vec, value -> isfinite(value)))
+        OR list_max(list_transform(vec, value -> abs(value)))=0`)) {
+        throw new Error("Cosine distance requires finite, non-null values and nonzero vectors.");
+    }
+    await connection.run(`WITH magnitudes AS MATERIALIZED (
+      SELECT vertex,vec,list_max(list_transform(vec, value -> abs(value))) AS magnitude
+      FROM ${rows}
+    ), scaled AS MATERIALIZED (
+      SELECT vertex,list_transform(vec, value -> value / magnitude) AS vec
+      FROM magnitudes
+      WHERE magnitude < 1e-75 OR magnitude > 1e75 / sqrt(len(vec))
+    ), lengths AS MATERIALIZED (
+      SELECT vertex,vec,sqrt(list_sum(list_transform(vec, value -> value * value))) AS norm
+      FROM scaled
+    )
+    UPDATE ${rows} AS target SET vec=cast_to_type(
+      list_transform(lengths.vec, value -> value / lengths.norm),target.vec)
+    FROM lengths WHERE target.vertex=lengths.vertex`);
+}

package/script/helpers/stringToArray.d.ts

@@ -2,15 +2,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"]
  * ```
+ *
+ * @param argument - One string or an array of strings.
+ *
+ * @returns A new array containing the supplied strings.
  */
 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;;;;;;;;;;;;;GAaG;AACH,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;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,OAAO,UAAU,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,CAQ3E"}

package/script/helpers/stringToArray.js

@@ -5,15 +5,16 @@ 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"]
  * ```
+ *
+ * @param argument - One string or an array of strings.
+ *
+ * @returns A new array containing the supplied strings.
  */
 function stringToArray(argument) {
     if (Array.isArray(argument)) {

package/script/helpers/umapRandom.d.ts

@@ -0,0 +1,2 @@
+export default function umapRandom(seed: number): () => number;
+//# sourceMappingURL=umapRandom.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"umapRandom.d.ts","sourceRoot":"","sources":["../../src/helpers/umapRandom.ts"],"names":[],"mappings":"AACA,MAAM,CAAC,OAAO,UAAU,UAAU,CAAC,IAAI,EAAE,MAAM,gBAQ9C"}

package/script/helpers/umapRandom.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = umapRandom;
+// Mulberry32: separate initialization and sampling streams, stable per seed.
+function umapRandom(seed) {
+    let state = seed >>> 0;
+    return () => {
+        state = (state + 0x6D2B79F5) | 0;
+        let value = Math.imul(state ^ state >>> 15, 1 | state);
+        value ^= value + Math.imul(value ^ value >>> 7, 61 | value);
+        return ((value ^ value >>> 14) >>> 0) / 4294967296;
+    };
+}

package/script/helpers/updateColumnsWithJS.d.ts

@@ -18,12 +18,6 @@ import type SimpleTable from "../class/SimpleTable.js";
  * inputs or overwritten as outputs; use updateWithJS() for editable GeoJSON.
  * This SQL-only preservation path accepts any source CRS.
  *
- * @param table - Table to enrich.
- * @param inputColumns - Columns available to the callback.
- * @param outputColumns - Generated columns to add or replace.
- * @param generate - Produces one result per input row, in input order.
- * @param options - Controls the maximum rows read, generated, and staged at once.
- * @returns Resolves after merging the generated columns into the table.
  * @example
  * ```ts
  * queueAsyncBarrier(table, {
@@ -35,6 +29,18 @@ import type SimpleTable from "../class/SimpleTable.js";
  * });
  * await table.log();
  * ```
+ *
+ * @param table - Table to enrich.
+ *
+ * @param inputColumns - Columns available to the callback.
+ *
+ * @param outputColumns - Generated columns to add or replace.
+ *
+ * @param generate - Produces one result per input row, in input order.
+ *
+ * @param options - Controls the maximum rows read, generated, and staged at once.
+ *
+ * @returns Resolves after merging the generated columns into the table.
  */
 export default function updateColumnsWithJS(table: SimpleTable, inputColumns: string[], outputColumns: string[], generate: (rows: {
     [key: string]: unknown;

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

@@ -1 +1 @@
-{"version":3,"file":"updateColumnsWithJS.d.ts","sourceRoot":"","sources":["../../src/helpers/updateColumnsWithJS.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAMvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAA8B,mBAAmB,CAC/C,KAAK,EAAE,WAAW,EAClB,YAAY,EAAE,MAAM,EAAE,EACtB,aAAa,EAAE,MAAM,EAAE,EACvB,QAAQ,EAAE,CACR,IAAI,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,EAAE,KAC/B,OAAO,CAAC;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,EAAE,CAAC,EAC1C,OAAO,GAAE;IACP;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACf,GACL,OAAO,CAAC,IAAI,CAAC,CAoJf"}
+{"version":3,"file":"updateColumnsWithJS.d.ts","sourceRoot":"","sources":["../../src/helpers/updateColumnsWithJS.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAMvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAA8B,mBAAmB,CAC/C,KAAK,EAAE,WAAW,EAClB,YAAY,EAAE,MAAM,EAAE,EACtB,aAAa,EAAE,MAAM,EAAE,EACvB,QAAQ,EAAE,CACR,IAAI,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,EAAE,KAC/B,OAAO,CAAC;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,EAAE,CAAC,EAC1C,OAAO,GAAE;IACP;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACf,GACL,OAAO,CAAC,IAAI,CAAC,CAoJf"}

package/script/helpers/updateColumnsWithJS.js

@@ -27,12 +27,6 @@ const loadArray_js_1 = require("../methods/loadArray.js");
  * inputs or overwritten as outputs; use updateWithJS() for editable GeoJSON.
  * This SQL-only preservation path accepts any source CRS.
  *
- * @param table - Table to enrich.
- * @param inputColumns - Columns available to the callback.
- * @param outputColumns - Generated columns to add or replace.
- * @param generate - Produces one result per input row, in input order.
- * @param options - Controls the maximum rows read, generated, and staged at once.
- * @returns Resolves after merging the generated columns into the table.
  * @example
  * ```ts
  * queueAsyncBarrier(table, {
@@ -44,6 +38,18 @@ const loadArray_js_1 = require("../methods/loadArray.js");
  * });
  * await table.log();
  * ```
+ *
+ * @param table - Table to enrich.
+ *
+ * @param inputColumns - Columns available to the callback.
+ *
+ * @param outputColumns - Generated columns to add or replace.
+ *
+ * @param generate - Produces one result per input row, in input order.
+ *
+ * @param options - Controls the maximum rows read, generated, and staged at once.
+ *
+ * @returns Resolves after merging the generated columns into the table.
  */
 async function updateColumnsWithJS(table, inputColumns, outputColumns, generate, options = {}) {
     const batchSize = options.batchSize ?? 1000;

package/script/helpers/validateGraphRouteResultSchema.d.ts

@@ -0,0 +1,4 @@
+import type { TableSchema } from "./pendingOps.js";
+/** Validates that route result columns do not replace original input columns. */
+export default function validateGraphRouteResultSchema(schema: TableSchema, method: string, additionalResultColumns?: readonly string[]): void;
+//# sourceMappingURL=validateGraphRouteResultSchema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validateGraphRouteResultSchema.d.ts","sourceRoot":"","sources":["../../src/helpers/validateGraphRouteResultSchema.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAKnD,iFAAiF;AACjF,MAAM,CAAC,OAAO,UAAU,8BAA8B,CACpD,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,EACd,uBAAuB,GAAE,SAAS,MAAM,EAAO,GAC9C,IAAI,CAkBN"}

package/script/helpers/validateGraphRouteResultSchema.js

@@ -0,0 +1,19 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = validateGraphRouteResultSchema;
+const foldIdentifier_js_1 = __importDefault(require("./foldIdentifier.js"));
+const quoteIdentifier_js_1 = __importDefault(require("./quoteIdentifier.js"));
+const resultColumns = ["pathId", "step", "weight", "total"];
+/** Validates that route result columns do not replace original input columns. */
+function validateGraphRouteResultSchema(schema, method, additionalResultColumns = []) {
+    for (const resultColumn of [...resultColumns, ...additionalResultColumns]) {
+        const folded = (0, foldIdentifier_js_1.default)(resultColumn);
+        const inputColumn = Object.keys(schema).find((column) => (0, foldIdentifier_js_1.default)(column) === folded);
+        if (inputColumn !== undefined) {
+            throw new Error(`${method} cannot add ${(0, quoteIdentifier_js_1.default)(resultColumn)} because input column ${(0, quoteIdentifier_js_1.default)(inputColumn)} conflicts with that result column. Rename ${(0, quoteIdentifier_js_1.default)(inputColumn)} with renameColumns() before calculating the graph.`);
+        }
+    }
+}

package/script/helpers/validateGraphTemporalEvents.d.ts

@@ -0,0 +1,7 @@
+import type SimpleTable from "../class/SimpleTable.js";
+import { type PreparedGraphTemporalOptions } from "./prepareGraphTemporalSql.js";
+/** Rejects invalid selected timestamps before a chronological graph runs. */
+export default function validateGraphTemporalEvents(simpleTable: SimpleTable, options: PreparedGraphTemporalOptions, method: string, parameters: {
+    [key: string]: unknown;
+}): Promise<void>;
+//# sourceMappingURL=validateGraphTemporalEvents.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validateGraphTemporalEvents.d.ts","sourceRoot":"","sources":["../../src/helpers/validateGraphTemporalEvents.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAEvD,OAAgC,EAC9B,KAAK,4BAA4B,EAClC,MAAM,8BAA8B,CAAC;AAItC,6EAA6E;AAC7E,wBAA8B,2BAA2B,CACvD,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,4BAA4B,EACrC,MAAM,EAAE,MAAM,EACd,UAAU,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,GACrC,OAAO,CAAC,IAAI,CAAC,CAiDf"}

package/script/helpers/validateGraphTemporalEvents.js

@@ -0,0 +1,53 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = validateGraphTemporalEvents;
+const mergeOptions_js_1 = __importDefault(require("./mergeOptions.js"));
+const prepareGraphTemporalSql_js_1 = __importDefault(require("./prepareGraphTemporalSql.js"));
+const queryDB_js_1 = __importDefault(require("./queryDB.js"));
+const quoteIdentifier_js_1 = __importDefault(require("./quoteIdentifier.js"));
+/** Rejects invalid selected timestamps before a chronological graph runs. */
+async function validateGraphTemporalEvents(simpleTable, options, method, parameters) {
+    const schema = await simpleTable.getTypes();
+    const temporal = (0, prepareGraphTemporalSql_js_1.default)(schema, options, method);
+    const q = quoteIdentifier_js_1.default;
+    const eventsName = "__graph_temporal_events";
+    const events = q(eventsName);
+    const eventStart = `${events}.${q("__event_start")}`;
+    const eventEnd = `${events}.${q("__event_end")}`;
+    const rows = await (0, queryDB_js_1.default)(simpleTable, `SELECT CASE
+      WHEN ${eventStart} IS NULL THEN 1
+      WHEN ${eventEnd} IS NULL THEN 2
+      WHEN NOT isfinite(${eventStart}) THEN 3
+      WHEN NOT isfinite(${eventEnd}) THEN 4
+      ELSE 5
+    END AS ${q("reason")}
+    FROM (
+      SELECT ${temporal.eventSelections().join(", ")}
+      FROM ${q(simpleTable.name)}
+    ) AS ${events}
+    WHERE (${temporal.eventValidity(eventsName)}) IS NOT TRUE
+    LIMIT 1`, (0, mergeOptions_js_1.default)(simpleTable, {
+        table: simpleTable.name,
+        method,
+        parameters,
+        returnData: true,
+    }));
+    const reason = rows?.[0]?.reason;
+    if (reason === undefined)
+        return;
+    const startColumn = temporal.startTimeColumn ?? temporal.endTimeColumn;
+    const endColumn = temporal.endTimeColumn ?? temporal.startTimeColumn;
+    const message = reason === 1
+        ? `selected start-time column ${q(startColumn)} contains a null timestamp.`
+        : reason === 2
+            ? `selected end-time column ${q(endColumn)} contains a null timestamp.`
+            : reason === 3
+                ? `selected start-time column ${q(startColumn)} contains an infinite timestamp.`
+                : reason === 4
+                    ? `selected end-time column ${q(endColumn)} contains an infinite timestamp.`
+                    : `selected end-time column ${q(endColumn)} contains a timestamp before its start in ${q(startColumn)}.`;
+    throw new TypeError(`${method} ${message}`);
+}

package/script/helpers/validateNumericalAnalysis.d.ts

@@ -2,12 +2,6 @@ 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(
@@ -17,6 +11,16 @@ import type { TableSchema } from "./pendingOps.js";
  *   "measurements",
  * );
  * ```
+ *
+ * @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.
  */
 export default function validateNumericalAnalysis(types: TableSchema, options: {
     x?: string;

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

@@ -1 +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"}
+{"version":3,"file":"validateNumericalAnalysis.d.ts","sourceRoot":"","sources":["../../src/helpers/validateNumericalAnalysis.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;GAsBG;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"}