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

package/esm/helpers/stabilizeCosineVectors.js

@@ -0,0 +1,34 @@
+import readScalarNumber from "./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.
+ */
+export default async function stabilizeCosineVectors(connection, rows) {
+    if (await readScalarNumber(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/esm/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/esm/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/esm/helpers/stringToArray.js

@@ -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) {
     if (Array.isArray(argument)) {

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

@@ -21,12 +21,6 @@ import { executePreparedArray, prepareArray } from "../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, {
@@ -38,6 +32,18 @@ import { executePreparedArray, prepareArray } from "../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.
  */
 export default async function updateColumnsWithJS(table, inputColumns, outputColumns, generate, options = {}) {
     const batchSize = options.batchSize ?? 1000;

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

@@ -0,0 +1,13 @@
+import foldIdentifier from "./foldIdentifier.js";
+import quoteIdentifier from "./quoteIdentifier.js";
+const resultColumns = ["pathId", "step", "weight", "total"];
+/** Validates that route result columns do not replace original input columns. */
+export default function validateGraphRouteResultSchema(schema, method, additionalResultColumns = []) {
+    for (const resultColumn of [...resultColumns, ...additionalResultColumns]) {
+        const folded = foldIdentifier(resultColumn);
+        const inputColumn = Object.keys(schema).find((column) => foldIdentifier(column) === folded);
+        if (inputColumn !== undefined) {
+            throw new Error(`${method} cannot add ${quoteIdentifier(resultColumn)} because input column ${quoteIdentifier(inputColumn)} conflicts with that result column. Rename ${quoteIdentifier(inputColumn)} with renameColumns() before calculating the graph.`);
+        }
+    }
+}

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

@@ -0,0 +1,47 @@
+import mergeOptions from "./mergeOptions.js";
+import prepareGraphTemporalSql from "./prepareGraphTemporalSql.js";
+import queryDB from "./queryDB.js";
+import quoteIdentifier from "./quoteIdentifier.js";
+/** Rejects invalid selected timestamps before a chronological graph runs. */
+export default async function validateGraphTemporalEvents(simpleTable, options, method, parameters) {
+    const schema = await simpleTable.getTypes();
+    const temporal = prepareGraphTemporalSql(schema, options, method);
+    const q = quoteIdentifier;
+    const eventsName = "__graph_temporal_events";
+    const events = q(eventsName);
+    const eventStart = `${events}.${q("__event_start")}`;
+    const eventEnd = `${events}.${q("__event_end")}`;
+    const rows = await queryDB(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`, mergeOptions(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/esm/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/esm/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/esm/helpers/validateNumericalAnalysis.js

@@ -3,12 +3,6 @@ import keepNumericalColumns from "./keepNumericalColumns.js";
 /**
  * Validates the column options shared by numerical pair analyses.
  *
- * @param types - The schema of the table being analyzed.
- * @param options - The optional x and y columns selected by the caller.
- * @param method - The SDA method performing the analysis.
- * @param tableName - The name of the table being analyzed.
- * @returns All numeric columns in the table schema.
- *
  * @example
  * ```ts
  * const columns = validateNumericalAnalysis(
@@ -18,6 +12,16 @@ import keepNumericalColumns from "./keepNumericalColumns.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, options, method, tableName) {
     if (options.x === undefined && options.y !== undefined) {

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

@@ -0,0 +1,16 @@
+/** Validate the positional identity contract before bounded vector scans. */
+export default 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/esm/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/esm/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/esm/helpers/vectorDistanceExpression.js

@@ -0,0 +1,11 @@
+/**
+ * Build a DOUBLE-precision distance expression for prepared vector aliases.
+ * Cosine callers first stabilize their private rows with stabilizeCosineVectors.
+ */
+export default 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/esm/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/esm/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/esm/helpers/wrapString.js

@@ -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, maxWidth, wordWrap = true) {
     if (str.length <= maxWidth) {

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

package/esm/methods/addId.js

@@ -0,0 +1,38 @@
+import assertNewColumns from "../helpers/assertNewColumns.js";
+import foldIdentifier from "../helpers/foldIdentifier.js";
+import mergeOptions from "../helpers/mergeOptions.js";
+import queryDB from "../helpers/queryDB.js";
+import queueOp from "../helpers/queueOp.js";
+import quoteIdentifier from "../helpers/quoteIdentifier.js";
+export default function addId(simpleTable, newColumn, options = {}) {
+    if (typeof newColumn !== "string") {
+        throw new TypeError("addId() newColumn must be a string.");
+    }
+    if (options.prefix !== undefined && typeof options.prefix !== "string") {
+        throw new TypeError("addId() options.prefix must be a string.");
+    }
+    // Materialize preceding operations so IDs follow their resulting row order.
+    options = structuredClone(options);
+    queueOp(simpleTable, {
+        kind: "barrier",
+        method: "addId()",
+        parameters: { newColumn, options },
+        execute: async () => {
+            const types = await simpleTable.getTypes();
+            const existingColumn = Object.keys(types).find((column) => foldIdentifier(column) === foldIdentifier(newColumn));
+            assertNewColumns(types, [existingColumn ?? newColumn], "addId()");
+            // An empty window preserves scan order without referencing rowid, which
+            // may be shadowed by a user column.
+            const rowNumber = "(ROW_NUMBER() OVER () - 1)";
+            const id = options.prefix === undefined
+                ? rowNumber
+                : `CONCAT(?, CAST(${rowNumber} AS VARCHAR))`;
+            await queryDB(simpleTable, `CREATE OR REPLACE TABLE ${quoteIdentifier(simpleTable.name)} AS SELECT *, ${id} AS ${quoteIdentifier(newColumn)} FROM ${quoteIdentifier(simpleTable.name)}`, mergeOptions(simpleTable, {
+                table: simpleTable.name,
+                method: "addId()",
+                parameters: { newColumn, options },
+                values: options.prefix === undefined ? undefined : [options.prefix],
+            }));
+        },
+    });
+}

package/esm/methods/commonNeighbors.d.ts

@@ -0,0 +1,10 @@
+import type SimpleTable from "../class/SimpleTable.js";
+import { type GraphId } from "../helpers/prepareGraphStarts.js";
+import { type GraphDirection } from "../helpers/prepareGraphTraversal.js";
+type CommonNeighborsOptions = {
+    direction?: GraphDirection;
+    outputTable?: string | boolean;
+};
+export default function commonNeighbors(simpleTable: SimpleTable, sourceColumn: string, targetColumn: string, nodeA: GraphId, nodeB: GraphId, options?: CommonNeighborsOptions): SimpleTable;
+export {};
+//# sourceMappingURL=commonNeighbors.d.ts.map

package/esm/methods/commonNeighbors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commonNeighbors.d.ts","sourceRoot":"","sources":["../../src/methods/commonNeighbors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAEvD,OAA2B,EACzB,KAAK,OAAO,EAEb,MAAM,kCAAkC,CAAC;AAC1C,OAA8B,EAC5B,KAAK,cAAc,EAEpB,MAAM,qCAAqC,CAAC;AAI7C,KAAK,sBAAsB,GAAG;IAC5B,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAChC,CAAC;AAEF,MAAM,CAAC,OAAO,UAAU,eAAe,CACrC,WAAW,EAAE,WAAW,EACxB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,sBAA2B,GACnC,WAAW,CAwDb"}

package/esm/methods/commonNeighbors.js

@@ -0,0 +1,101 @@
+import prepareGraphStarts from "../helpers/prepareGraphStarts.js";
+import prepareGraphTraversal, { validateGraphStarts, } from "../helpers/prepareGraphTraversal.js";
+import queueGraphResult from "../helpers/queueGraphResult.js";
+import quoteIdentifier from "../helpers/quoteIdentifier.js";
+export default function commonNeighbors(simpleTable, sourceColumn, targetColumn, nodeA, nodeB, options = {}) {
+    if (typeof sourceColumn !== "string") {
+        throw new TypeError("commonNeighbors() sourceColumn must be a string.");
+    }
+    if (typeof targetColumn !== "string") {
+        throw new TypeError("commonNeighbors() targetColumn must be a string.");
+    }
+    if (options === null || typeof options !== "object" || Array.isArray(options)) {
+        throw new TypeError("commonNeighbors() options must be an object.");
+    }
+    if (options.direction !== undefined &&
+        !["outgoing", "incoming", "both"].includes(options.direction)) {
+        throw new TypeError('commonNeighbors() options.direction must be "outgoing", "incoming", or "both".');
+    }
+    if (options.outputTable !== undefined &&
+        typeof options.outputTable !== "string" &&
+        typeof options.outputTable !== "boolean") {
+        throw new TypeError("commonNeighbors() options.outputTable must be a string or boolean.");
+    }
+    const nodes = prepareNodes(nodeA, nodeB);
+    options = structuredClone(options);
+    const direction = options.direction ?? "outgoing";
+    const parameters = { sourceColumn, targetColumn, nodeA, nodeB, options };
+    return queueGraphResult(simpleTable, {
+        method: "commonNeighbors()",
+        parameters,
+        outputTable: options.outputTable,
+        values: (schema) => {
+            validateNodes(schema, sourceColumn, targetColumn, nodes);
+            return nodes.values;
+        },
+        buildSelect: (input, schema) => commonNeighborsSelect(input, schema, sourceColumn, targetColumn, nodes, direction),
+        outputSchema: (schema) => ({
+            node: validateNodes(schema, sourceColumn, targetColumn, nodes).idType,
+        }),
+    });
+}
+function prepareNodes(nodeA, nodeB) {
+    if (Array.isArray(nodeA)) {
+        throw new TypeError("commonNeighbors() nodeA must be one node ID.");
+    }
+    if (Array.isArray(nodeB)) {
+        throw new TypeError("commonNeighbors() nodeB must be one node ID.");
+    }
+    const first = prepareGraphStarts(nodeA, "commonNeighbors()", "nodeA", true);
+    const second = prepareGraphStarts(nodeB, "commonNeighbors()", "nodeB", true);
+    if (first.family !== second.family) {
+        throw new TypeError("commonNeighbors() nodeA and nodeB must both be string IDs or both be numeric IDs.");
+    }
+    if (first.values[0] === second.values[0]) {
+        throw new TypeError("commonNeighbors() nodeA and nodeB must be different.");
+    }
+    return {
+        family: first.family,
+        numericValues: [...first.numericValues, ...second.numericValues],
+        values: [first.values[0], second.values[0]],
+    };
+}
+function validateNodes(schema, source, target, nodes) {
+    return validateGraphStarts(schema, source, target, nodes, "commonNeighbors()", "nodeA and nodeB");
+}
+function commonNeighborsSelect(input, schema, source, target, nodes, direction) {
+    const prepared = prepareGraphTraversal(input, schema, source, target, nodes, "commonNeighbors()", "nodeA and nodeB");
+    const relations = prepared.relationNames([
+        "graph_requested_nodes",
+        "graph_edges",
+        "graph_neighbor_memberships",
+        "graph_common_neighbors",
+    ]);
+    const requested = relations.graph_requested_nodes;
+    const edges = relations.graph_edges;
+    const memberships = relations.graph_neighbor_memberships;
+    const common = relations.graph_common_neighbors;
+    const q = quoteIdentifier;
+    return `WITH ${requested}(${q("node")}) AS (
+      VALUES ${prepared.startValues}
+    ), ${edges} AS (
+      ${prepared.edges(direction)}
+    ), ${memberships} AS (
+      SELECT ${q("requested")}.${q("node")} AS ${q("requested_node")},
+        ${q("edges")}.${q("__from_key")} AS ${q("__requested_key")},
+        ${q("edges")}.${q("__to")} AS ${q("node")},
+        ${q("edges")}.${q("__to_key")} AS ${q("__node_key")}
+      FROM ${edges} AS ${q("edges")}
+      INNER JOIN ${requested} AS ${q("requested")}
+        ON ${q("edges")}.${q("__from_key")} =
+          ${prepared.key(`${q("requested")}.${q("node")}`)}
+    ), ${common} AS (
+      SELECT MIN(${q("node")}) AS ${q("node")}, ${q("__node_key")}
+      FROM ${memberships}
+      GROUP BY ${q("__node_key")}
+      HAVING COUNT(DISTINCT ${q("__requested_key")}) = 2
+    )
+    SELECT ${q("node")}
+    FROM ${common}
+    ORDER BY ${q("__node_key")}`;
+}

package/esm/methods/connectedComponents.d.ts

@@ -0,0 +1,9 @@
+import type SimpleTable from "../class/SimpleTable.js";
+import { type GraphTemporalOptions } from "../helpers/prepareGraphTemporalSql.js";
+type ConnectedComponentsOptions = GraphTemporalOptions & {
+    mode?: "weak" | "strong";
+    outputTable?: string | boolean;
+};
+export default function connectedComponents(simpleTable: SimpleTable, sourceColumn: string, targetColumn: string, options?: ConnectedComponentsOptions): SimpleTable;
+export {};
+//# sourceMappingURL=connectedComponents.d.ts.map

package/esm/methods/connectedComponents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connectedComponents.d.ts","sourceRoot":"","sources":["../../src/methods/connectedComponents.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAGvD,OAAgC,EAC9B,KAAK,oBAAoB,EAG1B,MAAM,uCAAuC,CAAC;AAM/C,KAAK,0BAA0B,GAAG,oBAAoB,GAAG;IACvD,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAChC,CAAC;AAEF,MAAM,CAAC,OAAO,UAAU,mBAAmB,CACzC,WAAW,EAAE,WAAW,EACxB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,0BAA+B,GACvC,WAAW,CAqFb"}