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

package/src/helpers/prepareGraphTemporalSql.ts

@@ -0,0 +1,250 @@
+import foldIdentifier from "./foldIdentifier.ts";
+import type { TableSchema } from "./pendingOps.ts";
+import type { GraphDirection } from "./prepareGraphTraversal.ts";
+import quoteIdentifier from "./quoteIdentifier.ts";
+
+export type GraphTemporalOptions = {
+  endTimeColumn?: string;
+  minGapMs?: number;
+  startTimeColumn?: string;
+  strictOrdering?: boolean;
+};
+
+export type PreparedGraphTemporalOptions = {
+  endTimeColumn?: string;
+  gapMicroseconds: bigint;
+  startTimeColumn?: string;
+  strictOrdering: boolean;
+};
+
+export type PreparedGraphTemporalSql = {
+  endTimeColumn?: string;
+  eventSelections: (tableAlias?: string) => string[];
+  eventValidity: (tableAlias?: string) => string;
+  gapParameter: string;
+  gapUnit: "microsecond" | "nanosecond";
+  journeyAnchor: (alias: string, direction: Exclude<GraphDirection, "both">) => string;
+  journeyElapsed: (
+    alias: string,
+    anchor: string,
+    direction: Exclude<GraphDirection, "both">,
+  ) => string;
+  elapsedMilliseconds: (elapsed: string) => string;
+  startTimeColumn?: string;
+  transition: (
+    currentAlias: string,
+    candidateAlias: string,
+    direction: Exclude<GraphDirection, "both">,
+    gapExpression: string,
+  ) => string;
+};
+
+const temporalTypes = new Set([
+  "DATE",
+  "TIMESTAMP",
+  "TIMESTAMP_S",
+  "TIMESTAMP_MS",
+  "TIMESTAMP_NS",
+  "TIMESTAMP WITH TIME ZONE",
+]);
+
+/** Validates chronological options before a graph operation is queued. */
+export function prepareGraphTemporalOptions(
+  options: GraphTemporalOptions,
+  direction: GraphDirection | undefined,
+  method: string,
+): PreparedGraphTemporalOptions | undefined {
+  const startTimeColumn = options.startTimeColumn;
+  const endTimeColumn = options.endTimeColumn;
+  if (startTimeColumn !== undefined && typeof startTimeColumn !== "string") {
+    throw new TypeError(`${method} options.startTimeColumn must be a string.`);
+  }
+  if (endTimeColumn !== undefined && typeof endTimeColumn !== "string") {
+    throw new TypeError(`${method} options.endTimeColumn must be a string.`);
+  }
+  if (options.strictOrdering !== undefined && typeof options.strictOrdering !== "boolean") {
+    throw new TypeError(`${method} options.strictOrdering must be a boolean.`);
+  }
+  if (options.minGapMs !== undefined && typeof options.minGapMs !== "number") {
+    throw new TypeError(`${method} options.minGapMs must be a number.`);
+  }
+
+  const hasTimeColumn = startTimeColumn !== undefined || endTimeColumn !== undefined;
+  const hasTemporalSetting = options.minGapMs !== undefined || options.strictOrdering !== undefined;
+  if (!hasTimeColumn) {
+    if (hasTemporalSetting) {
+      throw new TypeError(
+        `${method} options.minGapMs and options.strictOrdering require options.startTimeColumn or options.endTimeColumn.`,
+      );
+    }
+    return undefined;
+  }
+  if (direction === "both") {
+    throw new TypeError(
+      `${method} options.direction cannot be "both" when chronological options are supplied.`,
+    );
+  }
+
+  const minGapMs = options.minGapMs ?? 0;
+  if (!Number.isFinite(minGapMs) || minGapMs < 0 || !Number.isInteger(minGapMs)) {
+    throw new TypeError(`${method} options.minGapMs must be a finite, non-negative integer.`);
+  }
+  if (minGapMs > Number.MAX_SAFE_INTEGER) {
+    throw new TypeError(`${method} options.minGapMs must not exceed Number.MAX_SAFE_INTEGER.`);
+  }
+  const gapMicroseconds = BigInt(minGapMs) * 1000n;
+
+  return {
+    endTimeColumn,
+    gapMicroseconds,
+    startTimeColumn,
+    strictOrdering: options.strictOrdering ?? true,
+  };
+}
+
+/** Prepares native-precision event and transition SQL from a queued schema. */
+export default function prepareGraphTemporalSql(
+  schema: TableSchema,
+  options: PreparedGraphTemporalOptions,
+  method: string,
+): PreparedGraphTemporalSql {
+  const start =
+    options.startTimeColumn === undefined
+      ? undefined
+      : getTemporalColumn(schema, options.startTimeColumn, method);
+  const end =
+    options.endTimeColumn === undefined
+      ? undefined
+      : getTemporalColumn(schema, options.endTimeColumn, method);
+  if (start?.zoned !== undefined && end?.zoned !== undefined) {
+    if (start.zoned !== end.zoned) {
+      throw new TypeError(
+        `${method} cannot mix time-zone-aware and time-zone-naive chronological columns. Convert both columns to the same timestamp domain first.`,
+      );
+    }
+  }
+
+  const startColumn = start?.column ?? end!.column;
+  const endColumn = end?.column ?? start!.column;
+  const startType = start?.type ?? end!.type;
+  const endType = end?.type ?? start!.type;
+  const gapUnit =
+    start?.type === "TIMESTAMP_NS" || end?.type === "TIMESTAMP_NS" ? "nanosecond" : "microsecond";
+  const gap = gapUnit === "nanosecond" ? options.gapMicroseconds * 1000n : options.gapMicroseconds;
+  const q = quoteIdentifier;
+  const reference = (alias: string | undefined, column: string) =>
+    `${alias === undefined ? "" : `${q(alias)}.`}${q(column)}`;
+  const eventReference = (alias: string | undefined, name: string) =>
+    `${alias === undefined ? "" : `${q(alias)}.`}${q(name)}`;
+
+  return {
+    startTimeColumn: start?.column,
+    endTimeColumn: end?.column,
+    gapParameter: gap.toString(),
+    gapUnit,
+    journeyAnchor: (alias, direction) =>
+      direction === "outgoing"
+        ? temporalUnits(eventReference(alias, "__event_start"), startType, gapUnit)
+        : temporalUnits(eventReference(alias, "__event_end"), endType, gapUnit),
+    journeyElapsed: (alias, anchor, direction) =>
+      direction === "outgoing"
+        ? `(${temporalUnits(eventReference(alias, "__event_end"), endType, gapUnit)} - (${anchor}))`
+        : `((${anchor}) - ${temporalUnits(
+            eventReference(alias, "__event_start"),
+            startType,
+            gapUnit,
+          )})`,
+    elapsedMilliseconds: (elapsed) =>
+      `(CAST(${elapsed} AS DOUBLE) / ${gapUnit === "nanosecond" ? 1000000 : 1000})`,
+    eventSelections: (alias) => [
+      `row_number() OVER () AS ${q("__event_id")}`,
+      `${reference(alias, startColumn)} AS ${q("__event_start")}`,
+      `${reference(alias, endColumn)} AS ${q("__event_end")}`,
+    ],
+    eventValidity: (alias) => {
+      const eventStart = eventReference(alias, "__event_start");
+      const eventEnd = eventReference(alias, "__event_end");
+      return `CASE
+        WHEN ${eventStart} IS NULL OR ${eventEnd} IS NULL THEN false
+        WHEN NOT isfinite(${eventStart}) OR NOT isfinite(${eventEnd}) THEN false
+        ELSE ${temporalUnits(eventEnd, endType, gapUnit)} >= ${temporalUnits(
+          eventStart,
+          startType,
+          gapUnit,
+        )}
+      END`;
+    },
+    transition: (currentAlias, candidateAlias, direction, gapExpression) => {
+      const currentStart = eventReference(currentAlias, "__event_start");
+      const currentEnd = eventReference(currentAlias, "__event_end");
+      const candidateStart = eventReference(candidateAlias, "__event_start");
+      const candidateEnd = eventReference(candidateAlias, "__event_end");
+      const earlierEnd = direction === "outgoing" ? currentEnd : candidateEnd;
+      const laterStart = direction === "outgoing" ? candidateStart : currentStart;
+      const elapsed = `${temporalUnits(laterStart, startType, gapUnit)} - ${temporalUnits(
+        earlierEnd,
+        endType,
+        gapUnit,
+      )}`;
+      const ordering = options.strictOrdering
+        ? `
+        AND ${elapsed} > 0`
+        : "";
+      return `${elapsed} >= ${gapExpression}${ordering}`;
+    },
+  };
+}
+
+function temporalUnits(
+  expression: string,
+  type: string,
+  unit: "microsecond" | "nanosecond",
+): string {
+  // Widen before scaling/subtraction to preserve precision and the DATE range.
+  const scale = unit === "nanosecond" ? 1000n : 1n;
+  if (type === "DATE") {
+    return `(CAST(date_diff('day', DATE '1970-01-01', ${expression}) AS HUGEINT) * ${
+      86_400_000_000n * scale
+    })`;
+  }
+  if (type === "TIMESTAMP_NS") {
+    return `CAST(epoch_ns(${expression}) AS HUGEINT)`;
+  }
+  return `(CAST(epoch_us(${expression}) AS HUGEINT) * ${scale})`;
+}
+
+function getTemporalColumn(
+  schema: TableSchema,
+  requested: string,
+  method: string,
+): { column: string; type: string; zoned: boolean } {
+  const folded = foldIdentifier(requested);
+  const column = Object.keys(schema).find((name) => foldIdentifier(name) === folded);
+  if (column === undefined) {
+    throw new Error(
+      `${method} the column ${quoteIdentifier(
+        requested,
+      )} does not exist. Check for typos, or load the data first.`,
+    );
+  }
+  const type = normalizeTemporalType(schema[column]);
+  if (!temporalTypes.has(type)) {
+    throw new TypeError(
+      `${method} requires DATE or TIMESTAMP chronological columns, but column ${quoteIdentifier(
+        column,
+      )} has type ${schema[column].toUpperCase()}.`,
+    );
+  }
+  return {
+    column,
+    type,
+    zoned: type === "TIMESTAMP WITH TIME ZONE",
+  };
+}
+
+function normalizeTemporalType(type: string): string {
+  const normalized = type.toUpperCase();
+  if (normalized === "TIMESTAMPTZ") return "TIMESTAMP WITH TIME ZONE";
+  if (normalized === "TIMESTAMP WITHOUT TIME ZONE") return "TIMESTAMP";
+  return normalized;
+}

package/src/helpers/prepareGraphTraversal.ts

@@ -0,0 +1,133 @@
+import foldIdentifier from "./foldIdentifier.ts";
+import getGraphEndpointColumns, { type GraphEndpointColumns } from "./getGraphEndpointColumns.ts";
+import type { TableSchema } from "./pendingOps.ts";
+import type { PreparedGraphStarts } from "./prepareGraphStarts.ts";
+import quoteIdentifier from "./quoteIdentifier.ts";
+
+export type GraphDirection = "outgoing" | "incoming" | "both";
+
+export type PreparedGraphTraversal = {
+  edges: (direction: GraphDirection, selections?: string[]) => string;
+  endpoints: GraphEndpointColumns;
+  key: (expression: string) => string;
+  relationNames: (names: string[]) => Record<string, string>;
+  startValues: string;
+};
+
+export type PreparedGraphSql = Omit<PreparedGraphTraversal, "startValues">;
+
+/** Prepares exact-ID SQL shared by graph traversal methods. */
+export default function prepareGraphTraversal(
+  input: string,
+  schema: TableSchema,
+  source: string,
+  target: string,
+  starts: PreparedGraphStarts,
+  method: string,
+  argument = "start",
+): PreparedGraphTraversal {
+  const endpoints = validateGraphStarts(schema, source, target, starts, method, argument);
+  return {
+    ...prepareGraphSqlFromEndpoints(input, endpoints),
+    startValues: starts.values.map(() => `(TRY_CAST(? AS ${endpoints.idType}))`).join(", "),
+  };
+}
+
+/** Prepares exact-ID edge SQL for graph methods without starting nodes. */
+export function prepareGraphSql(
+  input: string,
+  schema: TableSchema,
+  source: string,
+  target: string,
+  method: string,
+): PreparedGraphSql {
+  return prepareGraphSqlFromEndpoints(
+    input,
+    getGraphEndpointColumns(schema, source, target, method),
+  );
+}
+
+function prepareGraphSqlFromEndpoints(
+  input: string,
+  endpoints: GraphEndpointColumns,
+): PreparedGraphSql {
+  const sourceColumn = quoteIdentifier(endpoints.source);
+  const targetColumn = quoteIdentifier(endpoints.target);
+  const idType = endpoints.idType;
+  const cast = (expression: string) => `CAST(${expression} AS ${idType})`;
+  const key =
+    endpoints.family === "string" ? (expression: string) => `ENCODE(${cast(expression)})` : cast;
+  const edge = (from: string, to: string, selections: string[]) =>
+    `SELECT ${cast(from)} AS ${quoteIdentifier("__from")},
+        ${cast(to)} AS ${quoteIdentifier("__to")},
+        ${key(from)} AS ${quoteIdentifier("__from_key")},
+        ${key(to)} AS ${quoteIdentifier("__to_key")}${
+          selections.length === 0 ? "" : `,\n        ${selections.join(",\n        ")}`
+        }
+      FROM ${input} AS ${quoteIdentifier("edges")}`;
+  const sourceReference = `${quoteIdentifier("edges")}.${sourceColumn}`;
+  const targetReference = `${quoteIdentifier("edges")}.${targetColumn}`;
+  return {
+    endpoints,
+    key,
+    edges: (direction, selections = []) =>
+      direction === "outgoing"
+        ? edge(sourceReference, targetReference, selections)
+        : direction === "incoming"
+          ? edge(targetReference, sourceReference, selections)
+          : `${edge(sourceReference, targetReference, selections)}\nUNION ALL\n${edge(
+              targetReference,
+              sourceReference,
+              selections,
+            )}`,
+    relationNames: (names) => uniqueRelationNames(input, names),
+  };
+}
+
+/** Validates supplied starts against resolved endpoint ID types. */
+export function validateGraphStarts(
+  schema: TableSchema,
+  source: string,
+  target: string,
+  starts: PreparedGraphStarts,
+  method: string,
+  argument = "start",
+): GraphEndpointColumns {
+  const endpoints = getGraphEndpointColumns(schema, source, target, method);
+  const verb = argument === "start" ? "contains" : "contain";
+  if (endpoints.family !== starts.family) {
+    throw new TypeError(
+      `${method} ${argument} ${verb} ${starts.family} IDs, but endpoint columns ${quoteIdentifier(
+        endpoints.source,
+      )} and ${quoteIdentifier(endpoints.target)} contain ${endpoints.family} IDs.`,
+    );
+  }
+  if (endpoints.floating) {
+    for (const value of starts.numericValues) {
+      const converted = endpoints.idType === "FLOAT" ? Math.fround(Number(value)) : Number(value);
+      if (!Number.isFinite(converted) || BigInt(converted) !== value) {
+        throw new TypeError(
+          `${method} ${argument} ${verb} ${value}n, which ${endpoints.idType} cannot represent exactly.`,
+        );
+      }
+    }
+  }
+  return endpoints;
+}
+
+function uniqueRelationNames(input: string, requestedNames: string[]): Record<string, string> {
+  const used = new Set([foldIdentifier(input)]);
+  const names: Record<string, string> = {};
+  for (const requested of requestedNames) {
+    let candidate = requested;
+    let suffix = 1;
+    while (used.has(foldIdentifier(quoteIdentifier(candidate)))) {
+      candidate = `${requested}_${suffix}`;
+      suffix++;
+    }
+    const quoted = quoteIdentifier(candidate);
+    used.add(foldIdentifier(quoted));
+    names[requested] = quoted;
+  }
+  return names;
+}

package/src/helpers/prepareJSON.ts

@@ -0,0 +1,63 @@
+/** Validates and snapshots a JavaScript JSON value without dropping information. */
+export default function prepareJSON(value: unknown, column: string, row: number): string | null {
+  if (value === null || value === undefined) return null;
+  const active = new Set<object>();
+  const fail = (path: string, message: string): never => {
+    throw new Error(`Column ${JSON.stringify(column)}, row ${row}, ${path}: ${message}`);
+  };
+  function serialize(value: unknown, path: string): string {
+    if (value === null) return "null";
+    if (typeof value === "string" || typeof value === "boolean") {
+      return JSON.stringify(value);
+    }
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return Object.is(value, -0) ? "-0.0" : JSON.stringify(value);
+    }
+    if (typeof value !== "object") {
+      return fail(
+        path,
+        "Expected a JSON value: finite numbers, strings, booleans, null, arrays, or plain objects.",
+      );
+    }
+    if (active.has(value)) {
+      return fail(path, "Cyclic JSON values are unsupported.");
+    }
+    if (active.size >= 100) {
+      return fail(path, "JSON values may nest at most 100 levels.");
+    }
+    const array = Array.isArray(value);
+    if (
+      !array &&
+      Object.getPrototypeOf(value) !== Object.prototype &&
+      Object.getPrototypeOf(value) !== null
+    ) {
+      return fail(
+        path,
+        "Expected a plain JSON object; convert class instances to JSON values first.",
+      );
+    }
+    if (Object.getOwnPropertySymbols(value).length) {
+      return fail(path, "JSON cannot represent symbol keys.");
+    }
+    active.add(value);
+    try {
+      if (array) {
+        if (Object.keys(value).length !== value.length) {
+          return fail(path, "JSON arrays must be dense and have no extra properties.");
+        }
+        return `[${Array.from(value, (item: unknown, i) => serialize(item, `${path}[${i}]`)).join(
+          ",",
+        )}]`;
+      }
+      return `{${Object.entries(value)
+        .map(
+          ([key, item]: [string, unknown]) =>
+            `${JSON.stringify(key)}:${serialize(item, `${path}[${JSON.stringify(key)}]`)}`,
+        )
+        .join(",")}}`;
+    } finally {
+      active.delete(value);
+    }
+  }
+  return serialize(value, "$");
+}