@nshiab/simple-data-analysis-core 2.1.12 → 2.1.13

package/src/helpers/parseTypes.ts

@@ -0,0 +1,57 @@
+export default function parseType(
+  type:
+    | "integer"
+    | "float"
+    | "number"
+    | "string"
+    | "date"
+    | "time"
+    | "datetime"
+    | "datetimeTz"
+    | "bigint"
+    | "double"
+    | "varchar"
+    | "timestamp"
+    | "timestamp with time zone"
+    | "boolean"
+    | "json"
+    | "JSON"
+    | `float[${number}]`
+    | `FLOAT[${number}]`
+    | `geometry('${string}')`
+    | `GEOMETRY('${string}')`,
+) {
+  const typeLowerCase = type.toLowerCase();
+  if (typeLowerCase === "integer") {
+    return "INTEGER";
+  } else if (typeLowerCase === "float" || typeLowerCase === "number") {
+    return "DOUBLE";
+  } else if (typeLowerCase === "string") {
+    return "VARCHAR";
+  } else if (typeLowerCase === "datetime") {
+    return "TIMESTAMP";
+  } else if (typeLowerCase === "datetimetz") {
+    return "TIMESTAMP WITH TIME ZONE";
+  } else if (
+    [
+      "date",
+      "time",
+      "bigint",
+      "hugeint",
+      "double",
+      "varchar",
+      "timestamp",
+      "timestamp with time zone",
+      "boolean",
+      "json",
+    ].includes(typeLowerCase)
+  ) {
+    return type.toUpperCase();
+  } else if (/^float\[[1-9]\d*\]$/.test(typeLowerCase)) {
+    return type.toUpperCase();
+  } else if (typeLowerCase.includes("geometry")) {
+    return type.toUpperCase();
+  } else {
+    throw new Error(`Unknown type ${type}`);
+  }
+}

package/src/helpers/parseValue.ts

@@ -0,0 +1,34 @@
+import stringifyUnknown from "./stringifyUnknown.ts";
+/**
+ * Converts a JavaScript value to a SQL literal. Strings are quoted with embedded
+ * quotes escaped, dates become quoted ISO strings, and null, undefined, or NaN
+ * become `"NULL"`. Numbers and booleans are returned unchanged.
+ *
+ * @example
+ * ```ts
+ * import { parseValue } from "@nshiab/simple-data-analysis-core/helpers";
+ * console.log(parseValue("O'Brien")); // "'O''Brien'"
+ * console.log(parseValue(null)); // "NULL"
+ * ```
+ *
+ * @param value - A string, number, boolean, Date, null, or undefined.
+ *
+ * @returns A SQL literal, or the original number or boolean.
+ *
+ * @throws If the value has an unsupported type.
+ */
+export default function parseValue(value: unknown): string | boolean | number {
+  if (Number.isNaN(value) || value === undefined || value === null) {
+    return "NULL";
+  } else if (value instanceof Date) {
+    return `'${value.toISOString()}'`;
+  } else if (typeof value === "string") {
+    return `'${value.replaceAll("'", "''")}'`;
+  } else if (typeof value === "boolean") {
+    return value;
+  } else if (typeof value === "number") {
+    return value;
+  } else {
+    throw new Error(`Unknown type ${typeof value} of ${stringifyUnknown(value, "template")}.`);
+  }
+}

package/src/helpers/pendingOps.ts

@@ -0,0 +1,154 @@
+import type { DuckDBValue } from "@duckdb/node-api";
+
+/**
+ * The types of a table's schema, as returned by DESCRIBE: column names mapped
+ * to DuckDB types (e.g., { name: "VARCHAR", salary: "BIGINT" }).
+ */
+export type TableSchema = { [column: string]: string };
+
+/**
+ * A queued operation that can be expressed as a single SELECT over its input.
+ * At flush time, consecutive fusable operations on the same table are
+ * composed as CTEs into one statement.
+ */
+export type FusableOp = {
+  kind: "fusable";
+  /** The SDA method that queued the operation (e.g., "filter()"). */
+  method: string;
+  /** The parameters passed to the method, for error reporting. */
+  parameters: { [key: string]: unknown } | null;
+  /**
+   * The operation's position in program order across all tables of the
+   * database, stamped by queueOp.
+   */
+  sequence: number;
+  /**
+   * Whether buildSelect needs the schema of its input relation. When `false`,
+   * the flush compiler skips the DESCRIBE round-trip and passes an empty
+   * schema.
+   */
+  needsSchema: boolean;
+  /**
+   * Whether the SELECT uses spatial functions. The flush compiler loads the
+   * spatial extension once per connection before executing such operations.
+   */
+  needsSpatial?: boolean;
+  /**
+   * The user-supplied SQL fragments embedded verbatim in the SELECT (e.g.,
+   * filter conditions, addColumn definitions). Such SQL can reference tables
+   * by name, and names don't follow a fused chain: a subquery on the
+   * operation's own table would read the pre-chain state instead of the
+   * previous step's output. The flush compiler scans these fragments and
+   * executes the operation against materialized tables when they reference
+   * one.
+   */
+  rawSQL?: string[];
+  /**
+   * Whether the operation's fused segment must be rooted in a materialized
+   * table rather than an external source. Used when DuckDB's source execution
+   * shape affects an observable result such as deterministic sampled-row
+   * order.
+   */
+  requiresMaterializedInput?: boolean;
+  /** Data values bound to placeholders in this operation's SELECT. */
+  values?: DuckDBValue[] | ((schema: TableSchema) => DuckDBValue[]);
+  /**
+   * Whether the SELECT returns exactly the schema of its input (same columns,
+   * same types), like `SELECT * REPLACE` with type-preserving expressions.
+   * The flush compiler reuses the schema across consecutive
+   * schema-preserving operations instead of running a DESCRIBE per step.
+   */
+  preservesSchema?: boolean;
+  /**
+   * Derives the output schema from a known input schema without another
+   * DESCRIBE query. Used by projections and explicit casts whose output types
+   * are fully determined by their arguments.
+   */
+  outputSchema?: (input: TableSchema) => TableSchema;
+  /**
+   * Returns a single SELECT statement over `input`, which is either the
+   * quoted table name or the alias of the previous CTE in the fused chain.
+   */
+  buildSelect: (input: string, schema: TableSchema) => string;
+};
+
+/**
+ * A queued operation that starts a fused segment from an external relational
+ * source instead of consuming the target table's current contents.
+ */
+export type SourceOp = {
+  kind: "source";
+  /** The SDA method that queued the source (e.g., "loadData()"). */
+  method: string;
+  /** The parameters passed to the method, for error reporting. */
+  parameters: { [key: string]: unknown } | null;
+  /** The operation's position in database-wide program order. */
+  sequence: number;
+  /**
+   * User-supplied SQL fragments or table names read by the source. They close
+   * pending segments for those tables before the source executes.
+   */
+  rawSQL?: string[];
+  /** A schema known from explicit source options, when inference is unnecessary. */
+  schema?: TableSchema;
+  /** Whether the source uses spatial functions. */
+  needsSpatial?: boolean;
+  /** Returns a composable SELECT, optionally inspecting materialized inputs. */
+  buildSelect: () => string | Promise<string>;
+};
+
+/** A relational operation that can participate in a fused segment. */
+export type RelationalOp = SourceOp | FusableOp;
+
+/**
+ * A queued operation that is multi-statement by nature (or otherwise cannot
+ * be expressed as a single SELECT). Barriers execute in order between fused
+ * segments.
+ */
+export type BarrierOp = {
+  kind: "barrier";
+  /** The SDA method that queued the operation (e.g., "loadData()"). */
+  method: string;
+  /** The parameters passed to the method, for error reporting. */
+  parameters: { [key: string]: unknown } | null;
+  /**
+   * The operation's position in program order across all tables of the
+   * database, stamped by queueOp.
+   */
+  sequence: number;
+  /** Executes the operation. */
+  execute: () => Promise<void>;
+};
+
+/**
+ * An asynchronous extension barrier whose callback can queue builder methods.
+ * Nested operations drain before the callback observes the database and before
+ * the original chain continues.
+ */
+export type AsyncBarrierOp = {
+  kind: "asyncBarrier";
+  /** The extension method that queued the operation. */
+  method: string;
+  /** The parameters passed to the extension method, for error reporting. */
+  parameters: { [key: string]: unknown } | null;
+  /** The operation's position in database-wide program order. */
+  sequence: number;
+  /** Executes the asynchronous extension operation. */
+  execute: () => Promise<void>;
+};
+
+/**
+ * An operation queued by a sync builder or extension method, executed when
+ * the pending chains are flushed at an observation point.
+ */
+export type PendingOp = RelationalOp | BarrierOp | AsyncBarrierOp;
+
+/**
+ * A pending operation as built by a sync builder or extension method, before
+ * queueOp stamps it with its program-order sequence.
+ */
+export type PendingOpInput =
+  | Omit<FusableOp, "sequence">
+  | Omit<SourceOp, "sequence">
+  | Omit<BarrierOp, "sequence">
+  | Omit<AsyncBarrierOp, "sequence">;

package/src/helpers/prepareDbExtensions.ts

@@ -0,0 +1,48 @@
+import queryDbFile from "./queryDbFile.ts";
+import type SimpleDB from "../class/SimpleDB.ts";
+import type { IndexDefinition } from "./indexDefinitions.ts";
+import parseValue from "./parseValue.ts";
+
+export default async function prepareDbExtensions(
+  sdb: SimpleDB,
+  database: string,
+  indexes: Record<string, IndexDefinition[]>,
+): Promise<void> {
+  const definitions = Object.values(indexes).flat();
+  const physicalIndexes = await queryDbFile(
+    sdb,
+    `SELECT sql FROM duckdb_indexes() WHERE database_name = ${parseValue(database)};`,
+    { returnData: true },
+  );
+  if (
+    definitions.some((index) => index.kind === "vss") ||
+    physicalIndexes!.some((index) => /\bUSING\s+HNSW\b/i.test(String(index.sql)))
+  ) {
+    await queryDbFile(
+      sdb,
+      "INSTALL vss; LOAD vss; SET hnsw_enable_experimental_persistence = true;",
+    );
+  }
+  const ftsSchemas = await queryDbFile(
+    sdb,
+    `SELECT schema_name FROM duckdb_schemas() WHERE database_name = ${parseValue(
+      database,
+    )} AND starts_with(schema_name, 'fts_');`,
+    { returnData: true },
+  );
+  if (definitions.some((index) => index.kind === "fts") || ftsSchemas!.length > 0) {
+    await queryDbFile(sdb, "INSTALL fts; LOAD fts;");
+  }
+  if (!sdb.spatialLoaded) {
+    const geometryColumns = await queryDbFile(
+      sdb,
+      `SELECT column_name FROM duckdb_columns()
+       WHERE database_name = ${parseValue(database)} AND data_type ILIKE '%GEOMETRY%' LIMIT 1;`,
+      { returnData: true },
+    );
+    if (geometryColumns!.length > 0) {
+      await queryDbFile(sdb, "INSTALL spatial; LOAD spatial; SET geometry_always_xy = true;");
+      sdb.spatialLoaded = true;
+    }
+  }
+}

package/src/helpers/prepareGeometry.ts

@@ -0,0 +1,114 @@
+/** Validates and snapshots a two-dimensional WGS84 GeoJSON geometry cell. */
+export default function prepareGeometry(
+  value: unknown,
+  column: string,
+  row: number,
+): string | null {
+  if (value === null) return null;
+  const fail = (message: string): never => {
+    throw new Error(`Column ${JSON.stringify(column)}, row ${row}: ${message}`);
+  };
+  const active = new Set<object>();
+  let hasSignedZero = false;
+  function position(value: unknown): number[] {
+    if (
+      !Array.isArray(value) ||
+      value.length !== 2 ||
+      !Array.from(value).every((n) => typeof n === "number" && Number.isFinite(n))
+    ) {
+      fail(
+        "Expected a finite two-dimensional [longitude, latitude] position; Z/M coordinates are unsupported.",
+      );
+    }
+    const point = value as number[];
+    if (Math.abs(point[0]) > 180 || Math.abs(point[1]) > 90) {
+      fail(
+        "Expected WGS84 longitude [-180, 180] and latitude [-90, 90]; reproject the input first.",
+      );
+    }
+    hasSignedZero ||= Object.is(point[0], -0) || Object.is(point[1], -0);
+    return [...point];
+  }
+  function list(value: unknown, convert: (v: unknown) => unknown): unknown[] {
+    if (!Array.isArray(value)) fail("Expected a coordinate array.");
+    return Array.from(value as unknown[], convert);
+  }
+  function line(value: unknown): unknown[] {
+    const points = list(value, position);
+    if (points.length < 2) {
+      fail("A LineString must contain at least two positions.");
+    }
+    return points;
+  }
+  function ring(value: unknown): unknown[] {
+    const points = list(value, position) as number[][];
+    if (
+      points.length < 4 ||
+      points[0][0] !== points.at(-1)![0] ||
+      points[0][1] !== points.at(-1)![1]
+    ) {
+      fail("A polygon ring must contain at least four positions and be closed.");
+    }
+    return points;
+  }
+  function geometry(value: unknown): object {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+      fail("Expected a GeoJSON geometry object or null.");
+    }
+    const object = value as Record<string, unknown>;
+    if (active.has(object)) fail("Cyclic GeometryCollections are unsupported.");
+    if (active.size >= 100) {
+      fail("GeometryCollections may nest at most 100 levels.");
+    }
+    active.add(object);
+    try {
+      const type = object.type;
+      if (type === "Feature" || type === "FeatureCollection") {
+        fail(
+          "Expected a GeoJSON geometry object, not a Feature or FeatureCollection; extract each feature's geometry first.",
+        );
+      }
+      if ("crs" in object) {
+        fail(
+          "Geometry crs members are unsupported; supply WGS84 coordinates and declare GEOMETRY('EPSG:4326').",
+        );
+      }
+      let coordinates: unknown;
+      switch (type) {
+        case "Point":
+          coordinates = position(object.coordinates);
+          break;
+        case "MultiPoint":
+          coordinates = list(object.coordinates, position);
+          break;
+        case "LineString":
+          coordinates = line(object.coordinates);
+          break;
+        case "MultiLineString":
+          coordinates = list(object.coordinates, line);
+          break;
+        case "Polygon":
+          coordinates = list(object.coordinates, ring);
+          break;
+        case "MultiPolygon":
+          coordinates = list(object.coordinates, (v) => list(v, ring));
+          break;
+        case "GeometryCollection":
+          return { type, geometries: list(object.geometries, geometry) };
+        default:
+          fail("Expected a supported GeoJSON geometry type.");
+      }
+      return { type, coordinates };
+    } finally {
+      active.delete(object);
+    }
+  }
+  const prepared = geometry(value);
+  if (!hasSignedZero) return JSON.stringify(prepared);
+  // JSON.stringify normalizes -0. Only supported geometry type names survive
+  // validation as strings, so the "-0" marker cannot collide with input text.
+  // Emit a decimal literal so DuckDB also preserves its sign when parsing JSON.
+  return JSON.stringify(prepared, (_key, cell: unknown) =>
+    Object.is(cell, -0) ? "-0" : cell,
+  ).replaceAll('"-0"', "-0.0");
+}

package/src/helpers/prepareGraphMetricOptions.ts

@@ -0,0 +1,67 @@
+export type GraphMetricOptions = {
+  elapsedTime?: boolean;
+  minimize?: "steps" | "weight" | "elapsedTime";
+  weight?: string;
+  startTimeColumn?: string;
+  endTimeColumn?: string;
+};
+
+export type PreparedGraphMetricOptions = {
+  elapsedTime: boolean;
+  minimize: "steps" | "weight" | "elapsedTime";
+};
+
+/** Resolves graph cost selection separately from optional elapsed-time reporting. */
+export default function prepareGraphMetricOptions(
+  options: GraphMetricOptions,
+  method: string,
+  optimize: boolean,
+): PreparedGraphMetricOptions {
+  if (options.elapsedTime !== undefined && typeof options.elapsedTime !== "boolean") {
+    throw new TypeError(`${method} options.elapsedTime must be a boolean.`);
+  }
+  const elapsedTime = options.elapsedTime === true;
+  if (
+    elapsedTime &&
+    (options.startTimeColumn === undefined || options.endTimeColumn === undefined)
+  ) {
+    throw new TypeError(
+      `${method} options.elapsedTime requires both options.startTimeColumn and options.endTimeColumn.`,
+    );
+  }
+  if (options.minimize !== undefined) {
+    if (!optimize) {
+      throw new TypeError(
+        `${method} options.minimize is not supported because this method returns all routes.`,
+      );
+    }
+    if (
+      options.minimize !== "steps" &&
+      options.minimize !== "weight" &&
+      options.minimize !== "elapsedTime"
+    ) {
+      throw new TypeError(
+        `${method} options.minimize must be "steps", "weight", or "elapsedTime".`,
+      );
+    }
+    if (options.minimize === "weight" && options.weight === undefined) {
+      throw new TypeError(`${method} options.minimize: "weight" requires options.weight.`);
+    }
+    if (options.minimize === "elapsedTime" && !elapsedTime) {
+      throw new TypeError(
+        `${method} options.minimize: "elapsedTime" requires options.elapsedTime: true.`,
+      );
+    }
+  }
+  if (optimize && elapsedTime && options.weight !== undefined && options.minimize === undefined) {
+    throw new TypeError(
+      `${method} when weight and elapsedTime are both enabled, specify options.minimize: "steps", "weight", or "elapsedTime".`,
+    );
+  }
+  return {
+    elapsedTime,
+    minimize:
+      options.minimize ??
+      (options.weight !== undefined ? "weight" : elapsedTime ? "elapsedTime" : "steps"),
+  };
+}

package/src/helpers/prepareGraphRouteSql.ts

@@ -0,0 +1,123 @@
+import getGraphEdgeIdColumn from "./getGraphEdgeIdColumn.ts";
+import getGraphWeightColumn from "./getGraphWeightColumn.ts";
+import type { TableSchema } from "./pendingOps.ts";
+import validateGraphRouteResultSchema from "./validateGraphRouteResultSchema.ts";
+import prepareGraphStarts, {
+  type GraphId,
+  type PreparedGraphStarts,
+} from "./prepareGraphStarts.ts";
+import prepareGraphTraversal, { validateGraphStarts } from "./prepareGraphTraversal.ts";
+import quoteIdentifier from "./quoteIdentifier.ts";
+
+export type PreparedGraphRouteEndpoints = {
+  end: PreparedGraphStarts;
+  start: PreparedGraphStarts;
+  values: PreparedGraphStarts;
+};
+
+/** Prepares and validates the two scalar endpoints shared by route methods. */
+export function prepareGraphRouteEndpoints(
+  start: GraphId,
+  end: GraphId,
+  method: string,
+): PreparedGraphRouteEndpoints {
+  if (Array.isArray(start)) {
+    throw new TypeError(`${method} start must be one node ID.`);
+  }
+  if (Array.isArray(end)) {
+    throw new TypeError(`${method} end must be one node ID.`);
+  }
+  const preparedStart = prepareGraphStarts(start, method);
+  const preparedEnd = prepareGraphStarts(end, method);
+  if (preparedStart.family !== preparedEnd.family) {
+    throw new TypeError(`${method} start and end must both be string IDs or both be numeric IDs.`);
+  }
+  if (preparedStart.values[0] === preparedEnd.values[0]) {
+    throw new TypeError(
+      `${method} start and end must be different. Use distances() to measure return routes or findCycles() to find loops.`,
+    );
+  }
+  return {
+    start: preparedStart,
+    end: preparedEnd,
+    values: {
+      family: preparedStart.family,
+      numericValues: [...preparedStart.numericValues, ...preparedEnd.numericValues],
+      values: [preparedStart.values[0], preparedEnd.values[0]],
+    },
+  };
+}
+
+/** Validates the columns shared by edge-route methods from queued schema data. */
+export function validateGraphRouteInputs(
+  schema: TableSchema,
+  source: string,
+  target: string,
+  edgeId: string,
+  endpoints: PreparedGraphRouteEndpoints,
+  weight: string | undefined,
+  method: string,
+  includeTotal = true,
+) {
+  const nodes = validateGraphStarts(schema, source, target, endpoints.values, method);
+  const edges = getGraphEdgeIdColumn(schema, edgeId, method);
+  const weightColumn =
+    weight === undefined ? undefined : getGraphWeightColumn(schema, weight, method);
+  validateGraphRouteResultSchema(schema, method, [], includeTotal);
+  return {
+    distanceType: weightColumn?.distanceType ?? "BIGINT",
+    edgeIdType: edges.idType,
+    nodeIdType: nodes.idType,
+  };
+}
+
+/** Prepares the typed SQL expressions shared by edge-route enumeration. */
+export function prepareGraphRouteSql(
+  input: string,
+  schema: TableSchema,
+  source: string,
+  target: string,
+  edgeId: string,
+  endpoints: PreparedGraphRouteEndpoints,
+  weight: string | undefined,
+  method: string,
+  includeTotal = true,
+) {
+  validateGraphRouteResultSchema(schema, method, [], includeTotal);
+  const traversal = prepareGraphTraversal(input, schema, source, target, endpoints.values, method);
+  const edgeIdColumn = getGraphEdgeIdColumn(schema, edgeId, method);
+  const weightColumn =
+    weight === undefined ? undefined : getGraphWeightColumn(schema, weight, method);
+  const distanceType = weightColumn?.distanceType ?? "BIGINT";
+  const q = quoteIdentifier;
+  const edgeIdReference = `${q("edges")}.${q(edgeIdColumn.column)}`;
+  const typedEdgeId = `CAST(${edgeIdReference} AS ${edgeIdColumn.idType})`;
+  const edgeKey = edgeIdColumn.family === "string" ? `ENCODE(${typedEdgeId})` : typedEdgeId;
+  const edgeWeight =
+    weightColumn === undefined
+      ? `CAST(1 AS ${distanceType})`
+      : `CAST(${q("edges")}.${q(weightColumn.column)} AS ${distanceType})`;
+  const keyType = edgeIdColumn.family === "string" ? "BLOB" : edgeIdColumn.idType;
+  const stepType = `STRUCT(${q("edgeId")} ${edgeIdColumn.idType}, ${q(
+    "source",
+  )} ${traversal.endpoints.idType}, ${q(
+    "target",
+  )} ${traversal.endpoints.idType}, ${q("weight")} ${distanceType}, ${q(
+    "distance",
+  )} ${distanceType})`;
+
+  return {
+    distanceType,
+    edgeIdColumn,
+    edgeKey,
+    edgeWeight,
+    endpointValue: `TRY_CAST(? AS ${traversal.endpoints.idType})`,
+    keyType,
+    stepType,
+    input,
+    schema,
+    traversal,
+    typedEdgeId,
+    weightType: weightColumn?.type,
+  };
+}

package/src/helpers/prepareGraphStarts.ts

@@ -0,0 +1,92 @@
+export type GraphId = string | number | bigint;
+
+export type PreparedGraphStarts = {
+  family: "string" | "numeric";
+  numericValues: bigint[];
+  values: string[];
+};
+
+/** Validates and snapshots scalar-or-array graph starting IDs. */
+export default function prepareGraphStarts(
+  start: GraphId | GraphId[],
+  method: string,
+  argument = "start",
+  scalar = false,
+): PreparedGraphStarts {
+  const starts = Array.isArray(start) ? [...start] : [start];
+  if (starts.length === 0) {
+    throw new TypeError(`${method} ${argument} must not be an empty array.`);
+  }
+
+  let family: "string" | "numeric" | undefined;
+  const values: string[] = [];
+  const numericValues: bigint[] = [];
+  const seen = new Set<string>();
+  const duplicates: GraphId[] = [];
+
+  for (const value of starts) {
+    const valueFamily =
+      typeof value === "string"
+        ? "string"
+        : typeof value === "number" || typeof value === "bigint"
+          ? "numeric"
+          : undefined;
+    if (valueFamily === undefined) {
+      throw new TypeError(
+        scalar
+          ? `${method} ${argument} must be a string or a whole number.`
+          : `${method} ${argument} must be a string, a whole number, or an array of those values.`,
+      );
+    }
+    if (family !== undefined && family !== valueFamily) {
+      throw new TypeError(`${method} ${argument} must not mix string and numeric IDs.`);
+    }
+    family = valueFamily;
+
+    let encoded: string;
+    if (typeof value === "number") {
+      if (!Number.isSafeInteger(value)) {
+        throw new TypeError(
+          `${method} ${argument} contains ${value}, which is not a safe whole number. Use a bigint for exact integer IDs outside JavaScript's safe integer range.`,
+        );
+      }
+      encoded = BigInt(value).toString();
+      numericValues.push(BigInt(value));
+    } else if (typeof value === "bigint") {
+      encoded = value.toString();
+      numericValues.push(value);
+    } else {
+      encoded = value;
+    }
+
+    const key = `${valueFamily}:${encoded}`;
+    if (seen.has(key)) {
+      if (!duplicates.some((duplicate) => graphIdsEqual(duplicate, value))) {
+        duplicates.push(value);
+      }
+    } else {
+      seen.add(key);
+      values.push(encoded);
+    }
+  }
+
+  if (duplicates.length > 0) {
+    throw new TypeError(
+      `${method} ${argument} contains duplicate IDs: ${duplicates.map(formatGraphId).join(", ")}.`,
+    );
+  }
+
+  return { family: family!, numericValues, values };
+}
+
+function graphIdsEqual(left: GraphId, right: GraphId): boolean {
+  if (typeof left === "string" || typeof right === "string") {
+    return left === right;
+  }
+  return BigInt(left) === BigInt(right);
+}
+
+function formatGraphId(value: GraphId): string {
+  if (typeof value === "string") return JSON.stringify(value);
+  return typeof value === "bigint" ? `${value}n` : String(value);
+}