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

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

package/script/helpers/validateNumericalAnalysis.js

@@ -9,12 +9,6 @@ const keepNumericalColumns_js_1 = __importDefault(require("./keepNumericalColumn
 /**
  * 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(
@@ -24,6 +18,16 @@ const keepNumericalColumns_js_1 = __importDefault(require("./keepNumericalColumn
  *   "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.
  */
 function validateNumericalAnalysis(types, options, method, tableName) {
     if (options.x === undefined && options.y !== undefined) {

package/script/helpers/validateVectorRowIds.d.ts

@@ -0,0 +1,4 @@
+import type { DuckDBConnection } from "@duckdb/node-api";
+/** Validate the positional identity contract before bounded vector scans. */
+export default function validateVectorRowIds(connection: DuckDBConnection, rows: string, count: number): Promise<void>;
+//# sourceMappingURL=validateVectorRowIds.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validateVectorRowIds.d.ts","sourceRoot":"","sources":["../../src/helpers/validateVectorRowIds.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,6EAA6E;AAC7E,wBAA8B,oBAAoB,CAChD,UAAU,EAAE,gBAAgB,EAC5B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CAuBf"}

package/script/helpers/validateVectorRowIds.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = validateVectorRowIds;
+/** Validate the positional identity contract before bounded vector scans. */
+async function validateVectorRowIds(connection, rows, count) {
+    // Graph state and DuckDB scratch schemas use signed INTEGER vertex ids.
+    if (!Number.isSafeInteger(count) || count < 1 || count > 2147483647) {
+        throw new Error("Vector row count must fit a positive INTEGER vertex count.");
+    }
+    const [actual, distinct, minimum, maximum, invalid] = (await connection.runAndReadAll(`SELECT count(*),count(DISTINCT vertex),
+      min(vertex),max(vertex),count(*) FILTER (
+        WHERE vertex IS NULL OR vertex!=trunc(vertex)) FROM ${rows}`))
+        .getRowsJS()[0];
+    if (Number(actual) !== count || Number(distinct) !== count ||
+        Number(minimum) !== 0 || Number(maximum) !== count - 1 ||
+        Number(invalid) !== 0) {
+        throw new Error(`Vector rows must contain exactly ${count} unique integer vertex ids from 0 to ${count - 1}.`);
+    }
+}

package/script/helpers/vectorDistanceExpression.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Build a DOUBLE-precision distance expression for prepared vector aliases.
+ * Cosine callers first stabilize their private rows with stabilizeCosineVectors.
+ */
+export default function vectorDistanceExpression(left: string, right: string, metric: "euclidean" | "cosine"): string;
+//# sourceMappingURL=vectorDistanceExpression.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vectorDistanceExpression.d.ts","sourceRoot":"","sources":["../../src/helpers/vectorDistanceExpression.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,OAAO,UAAU,wBAAwB,CAC9C,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,WAAW,GAAG,QAAQ,GAC7B,MAAM,CAKR"}

package/script/helpers/vectorDistanceExpression.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = vectorDistanceExpression;
+/**
+ * Build a DOUBLE-precision distance expression for prepared vector aliases.
+ * Cosine callers first stabilize their private rows with stabilizeCosineVectors.
+ */
+function vectorDistanceExpression(left, right, metric) {
+    if (metric === "euclidean")
+        return `array_distance(${left},${right})`;
+    // DuckDB can return tiny positive or negative errors for equal/cosine-aligned
+    // vectors. Exact equality also makes duplicate behavior deterministic.
+    return `CASE WHEN ${left}=${right} THEN 0 ELSE greatest(0,array_cosine_distance(${left},${right})) END`;
+}

package/script/helpers/wrapString.d.ts

@@ -4,13 +4,6 @@
  * will be broken at the character boundary. This function is primarily used
  * for preparing text to be displayed in console tables.
  *
- * @param str - The string to wrap.
- * @param maxWidth - The maximum width of each line.
- * @param wordWrap - If true, attempts to break at word boundaries. If false,
- *   breaks at character boundaries. Defaults to `true`.
- * @returns The wrapped string with newline characters inserted at appropriate
- *   positions.
- *
  * @example
  * ```typescript
  * const text = "This is a very long sentence that needs to be wrapped";
@@ -30,6 +23,16 @@
  * // Output: Thisisaver
  * //         ylongword
  * ```
+ *
+ * @param str - The string to wrap.
+ *
+ * @param maxWidth - The maximum width of each line.
+ *
+ * @param wordWrap - If true, attempts to break at word boundaries. If false,
+ *   breaks at character boundaries. Defaults to `true`.
+ *
+ * @returns The wrapped string with newline characters inserted at appropriate
+ *   positions.
  */
 export default function wrapString(str: string, maxWidth: number, wordWrap?: boolean): string;
 //# sourceMappingURL=wrapString.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"wrapString.d.ts","sourceRoot":"","sources":["../../src/helpers/wrapString.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,CAAC,OAAO,UAAU,UAAU,CAChC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,QAAQ,UAAO,GACd,MAAM,CAqDR"}
+{"version":3,"file":"wrapString.d.ts","sourceRoot":"","sources":["../../src/helpers/wrapString.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,CAAC,OAAO,UAAU,UAAU,CAChC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,QAAQ,UAAO,GACd,MAAM,CAqDR"}

package/script/helpers/wrapString.js

@@ -7,13 +7,6 @@ exports.default = wrapString;
  * will be broken at the character boundary. This function is primarily used
  * for preparing text to be displayed in console tables.
  *
- * @param str - The string to wrap.
- * @param maxWidth - The maximum width of each line.
- * @param wordWrap - If true, attempts to break at word boundaries. If false,
- *   breaks at character boundaries. Defaults to `true`.
- * @returns The wrapped string with newline characters inserted at appropriate
- *   positions.
- *
  * @example
  * ```typescript
  * const text = "This is a very long sentence that needs to be wrapped";
@@ -33,6 +26,16 @@ exports.default = wrapString;
  * // Output: Thisisaver
  * //         ylongword
  * ```
+ *
+ * @param str - The string to wrap.
+ *
+ * @param maxWidth - The maximum width of each line.
+ *
+ * @param wordWrap - If true, attempts to break at word boundaries. If false,
+ *   breaks at character boundaries. Defaults to `true`.
+ *
+ * @returns The wrapped string with newline characters inserted at appropriate
+ *   positions.
  */
 function wrapString(str, maxWidth, wordWrap = true) {
     if (str.length <= maxWidth) {

package/script/methods/addId.d.ts

@@ -0,0 +1,5 @@
+import type SimpleTable from "../class/SimpleTable.js";
+export default function addId(simpleTable: SimpleTable, newColumn: string, options?: {
+    prefix?: string;
+}): void;
+//# sourceMappingURL=addId.d.ts.map

package/script/methods/addId.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addId.d.ts","sourceRoot":"","sources":["../../src/methods/addId.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAEvD,MAAM,CAAC,OAAO,UAAU,KAAK,CAC3B,WAAW,EAAE,WAAW,EACxB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,QAgDlC"}