@elabs-ai/components-process 4.1.0

package/src/core/adapters/csv.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, it } from "vitest";
+
+import { normalizeLog } from "../event-log";
+import { fromCsv, parseDelimited } from "./csv";
+
+const mapping = { caseId: "case", activity: "activity", timestamp: "timestamp" };
+
+describe("parseDelimited", () => {
+  it("parses a plain comma-separated table", () => {
+    expect(parseDelimited("a,b,c\n1,2,3")).toEqual([
+      ["a", "b", "c"],
+      ["1", "2", "3"],
+    ]);
+  });
+
+  it("does not emit a phantom record for a trailing newline", () => {
+    expect(parseDelimited("a,b\n1,2\n")).toHaveLength(2);
+    expect(parseDelimited("a,b\r\n1,2\r\n")).toHaveLength(2);
+  });
+
+  it("keeps a delimiter, a newline and a CRLF inside a quoted field", () => {
+    expect(parseDelimited('a,b\n"x,y","line1\nline2"')[1]).toEqual(["x,y", "line1\nline2"]);
+    expect(parseDelimited('a\n"line1\r\nline2"')[1]).toEqual(["line1\r\nline2"]);
+  });
+
+  it("reads a doubled quote inside a quoted field as one literal quote", () => {
+    expect(parseDelimited('a\n"say ""hi"""')[1]).toEqual(['say "hi"']);
+  });
+
+  it("strips a UTF-8 BOM from the first field", () => {
+    expect(parseDelimited("case,activity\n1,Ship")[0]).toEqual(["case", "activity"]);
+  });
+
+  it("preserves empty fields, including a trailing one", () => {
+    expect(parseDelimited("a,b,c\n1,,3")[1]).toEqual(["1", "", "3"]);
+    expect(parseDelimited("a,b\n1,")[1]).toEqual(["1", ""]);
+  });
+
+  it("does not trim field values — trimming is the mapping's decision", () => {
+    expect(parseDelimited("a\n  spaced  ")[1]).toEqual(["  spaced  "]);
+  });
+
+  it("tolerates an unterminated quote by running the field to the end", () => {
+    expect(parseDelimited('a\n"never closed')[1]).toEqual(["never closed"]);
+  });
+
+  it("honours a non-comma delimiter", () => {
+    expect(parseDelimited("a\tb\n1\t2", "\t")[1]).toEqual(["1", "2"]);
+    expect(parseDelimited("a;b\n1;2", ";")[1]).toEqual(["1", "2"]);
+  });
+
+  it("answers empty text with no records", () => {
+    expect(parseDelimited("")).toEqual([]);
+  });
+});
+
+describe("fromCsv", () => {
+  const text = [
+    "case,activity,timestamp,resource",
+    "1,Create Order,2026-01-05T09:00:00Z,A. Novak",
+    "1,Check Credit,2026-01-05T10:00:00Z,Credit Service",
+    "2,Create Order,2026-01-06T09:00:00Z,A. Novak",
+    "",
+  ].join("\n");
+
+  it("reads the header row and maps the columns", () => {
+    const log = fromCsv(text, { ...mapping, resource: "resource" });
+    expect(log.events).toHaveLength(3);
+    expect(log.events[0]).toEqual({
+      caseId: "1",
+      activity: "Create Order",
+      timestamp: "2026-01-05T09:00:00Z",
+      resource: "A. Novak",
+    });
+  });
+
+  it("trims header names so a hand-edited export still matches", () => {
+    const log = fromCsv("case , activity ,timestamp\n1,Ship,2026-01-05T09:00:00Z", mapping);
+    expect(log.events).toHaveLength(1);
+  });
+
+  it("accepts a headerless source when the caller names the columns", () => {
+    const log = fromCsv("1,Ship,2026-01-05T09:00:00Z", {
+      ...mapping,
+      header: ["case", "activity", "timestamp"],
+    });
+    expect(log.events[0]?.activity).toBe("Ship");
+  });
+
+  it("handles a quoted activity name containing the delimiter", () => {
+    const log = fromCsv(
+      'case,activity,timestamp\n1,"Approve, then ship",2026-01-05T09:00:00Z',
+      mapping,
+    );
+    expect(log.events[0]?.activity).toBe("Approve, then ship");
+  });
+
+  it("reads a semicolon-delimited European export", () => {
+    const log = fromCsv("case;activity;timestamp\n1;Ship;2026-01-05T09:00:00Z", {
+      ...mapping,
+      delimiter: ";",
+    });
+    expect(log.events[0]?.caseId).toBe("1");
+  });
+
+  it("answers empty text with an empty log rather than throwing", () => {
+    expect(fromCsv("", mapping)).toEqual({ events: [] });
+  });
+
+  it("delegates skipping to fromFlatRows — a short row does not become an event", () => {
+    const log = fromCsv("case,activity,timestamp\n1,Ship\n2,Pay,2026-01-05T09:00:00Z", mapping);
+    expect(log.events).toHaveLength(1);
+    expect(log.events[0]?.caseId).toBe("2");
+  });
+
+  it("feeds normalizeLog end to end, lifecycle pairing included", () => {
+    const csv = [
+      "case,activity,timestamp,phase",
+      "1,Pick,2026-01-05T09:00:00Z,start",
+      "1,Pack,2026-01-05T10:00:00Z,start",
+      "1,Pick,2026-01-05T11:00:00Z,complete",
+      "1,Pack,2026-01-05T12:00:00Z,complete",
+    ].join("\n");
+    const normalized = normalizeLog(fromCsv(csv, { ...mapping, lifecycle: "phase" }));
+    expect(normalized.totals).toEqual({ cases: 1, events: 2 });
+    expect(normalized.cases[0]?.events.map((e) => [e.activity, e.duration])).toEqual([
+      ["Pick", 7_200_000],
+      ["Pack", 7_200_000],
+    ]);
+  });
+});

package/src/core/adapters/csv.ts

@@ -0,0 +1,146 @@
+/**
+ * CSV adapter — RM-049.
+ *
+ * A minimal RFC 4180 reader plus a thin front end onto {@link fromFlatRows}. It is written
+ * here rather than pulled from npm on purpose: `/core` is the framework-free,
+ * worker-safe leaf, and a parser this small (quoted fields, escaped quotes, embedded
+ * newlines, CRLF, a BOM) does not justify a runtime dependency in a package a consumer
+ * imports into a web worker.
+ *
+ * What it deliberately does NOT do: type inference, header de-duplication, streaming, or
+ * dialect sniffing. A source that needs any of those parses itself and calls
+ * {@link fromFlatRows} with the rows.
+ */
+import type { EventLog } from "../types";
+import { fromFlatRows, type FlatRow, type FlatRowMapping } from "./flat";
+
+/** Options for {@link parseDelimited} and {@link fromCsv}. */
+export interface CsvOptions {
+  /** Field separator. Defaults to `","`; pass `"\t"` for TSV, `";"` for a European export. */
+  delimiter?: string;
+  /**
+   * Column names, when the text has NO header row. Omit for the usual case, where the
+   * first record is the header.
+   */
+  header?: readonly string[];
+}
+
+/** Everything `fromCsv` needs: the column mapping plus the dialect. */
+export type CsvMapping = FlatRowMapping & CsvOptions;
+
+const QUOTE = '"';
+const CR = "\r";
+const LF = "\n";
+
+/**
+ * Parse RFC 4180 delimited text into records of raw string fields.
+ *
+ * Handles: quoted fields; a doubled `""` inside a quoted field as one literal quote;
+ * delimiters, `CR`, `LF` and `CRLF` inside a quoted field; `CRLF` or bare `LF` record
+ * separators; a leading UTF-8 BOM; and a trailing newline (which does NOT produce a
+ * phantom empty record).
+ *
+ * A field is returned exactly as written, without trimming — trimming is a MAPPING
+ * decision, and `fromFlatRows` makes it. Unterminated quotes are tolerated: the field runs
+ * to the end of the text rather than throwing, so a truncated download yields the rows it
+ * did contain.
+ */
+export function parseDelimited(text: string, delimiter = ","): string[][] {
+  const source = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+  const records: string[][] = [];
+  let record: string[] = [];
+  let field = "";
+  let quoted = false;
+  let dirty = false; // has anything been read into the current record at all?
+  const delimiterChar = delimiter.length > 0 ? delimiter[0] : ",";
+
+  const endField = (): void => {
+    record.push(field);
+    field = "";
+    dirty = true;
+  };
+  const endRecord = (): void => {
+    endField();
+    records.push(record);
+    record = [];
+    dirty = false;
+  };
+
+  for (let i = 0; i < source.length; i += 1) {
+    const char = source[i] as string;
+
+    if (quoted) {
+      if (char === QUOTE) {
+        if (source[i + 1] === QUOTE) {
+          field += QUOTE;
+          i += 1;
+        } else {
+          quoted = false;
+        }
+      } else {
+        field += char;
+      }
+      continue;
+    }
+
+    if (char === QUOTE && field === "") {
+      quoted = true;
+      dirty = true;
+      continue;
+    }
+    if (char === delimiterChar) {
+      endField();
+      continue;
+    }
+    if (char === CR) {
+      if (source[i + 1] === LF) i += 1;
+      endRecord();
+      continue;
+    }
+    if (char === LF) {
+      endRecord();
+      continue;
+    }
+    field += char;
+    dirty = true;
+  }
+
+  if (field !== "" || dirty) endRecord();
+  return records;
+}
+
+/** Turn parsed records into objects keyed by `header`. Missing trailing cells read as `""`. */
+export function toObjects(records: readonly string[][], header: readonly string[]): FlatRow[] {
+  const rows: FlatRow[] = [];
+  for (const record of records) {
+    const row: FlatRow = {};
+    for (let i = 0; i < header.length; i += 1) {
+      row[header[i] as string] = record[i] ?? "";
+    }
+    rows.push(row);
+  }
+  return rows;
+}
+
+/**
+ * Read delimited text into an {@link EventLog}.
+ *
+ * The first record is the header unless `mapping.header` supplies one. Column names in
+ * the header are trimmed (a `", activity"` from a hand-edited export still matches
+ * `activity`); field VALUES are not, so `fromFlatRows` stays the only place that decides
+ * what an empty cell means.
+ *
+ * Empty text yields an empty log rather than throwing.
+ */
+export function fromCsv(text: string, mapping: CsvMapping): EventLog {
+  const records = parseDelimited(text, mapping.delimiter ?? ",");
+  let header = mapping.header;
+  let body = records;
+  if (header === undefined) {
+    const first = records[0];
+    if (first === undefined) return { events: [] };
+    header = first.map((name) => name.trim());
+    body = records.slice(1);
+  }
+  return fromFlatRows(toObjects(body, header), mapping);
+}

package/src/core/adapters/flat.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, it } from "vitest";
+
+import { normalizeLog } from "../event-log";
+import { DEFAULT_LIFECYCLE_VALUES, fromFlatRows, normalizeLifecycle } from "./flat";
+import type { FlatRow } from "./flat";
+
+const rows: FlatRow[] = [
+  {
+    case: "1",
+    step: "Create Order",
+    when: "2026-01-05T09:00:00Z",
+    who: "A. Novak",
+    region: "North",
+  },
+  {
+    case: "1",
+    step: "Check Credit",
+    when: "2026-01-05T10:00:00Z",
+    who: "Credit Service",
+    region: "North",
+  },
+  {
+    case: "2",
+    step: "Create Order",
+    when: "2026-01-06T09:00:00Z",
+    who: "A. Novak",
+    region: "South",
+  },
+];
+
+const mapping = { caseId: "case", activity: "step", timestamp: "when", resource: "who" };
+
+describe("fromFlatRows", () => {
+  it("maps the three required columns onto EventRows", () => {
+    const log = fromFlatRows(rows, mapping);
+    expect(log.events).toHaveLength(3);
+    expect(log.events[0]).toEqual({
+      caseId: "1",
+      activity: "Create Order",
+      timestamp: "2026-01-05T09:00:00Z",
+      resource: "A. Novak",
+    });
+  });
+
+  it("skips rows missing a case id, an activity or a timestamp rather than throwing", () => {
+    const log = fromFlatRows(
+      [
+        ...rows,
+        { case: "", step: "Ship", when: "2026-01-05T09:00:00Z" },
+        { case: "3", step: "", when: "2026-01-05T09:00:00Z" },
+        { case: "3", step: "Ship", when: "" },
+        { case: "3", step: "Ship", when: null },
+        {},
+      ],
+      mapping,
+    );
+    expect(log.events).toHaveLength(3);
+  });
+
+  it("trims cell values and treats a blank cell as absent", () => {
+    const log = fromFlatRows(
+      [{ case: "  1  ", step: " Ship ", when: " 2026-01-05T09:00:00Z " }],
+      mapping,
+    );
+    expect(log.events[0]).toMatchObject({ caseId: "1", activity: "Ship" });
+    expect(log.events[0]?.resource).toBeUndefined();
+  });
+
+  it("passes a Date or an epoch number through without pre-converting it", () => {
+    const date = new Date("2026-01-05T09:00:00Z");
+    const log = fromFlatRows(
+      [
+        { case: "1", step: "Ship", when: date },
+        { case: "1", step: "Pay", when: 1_767_600_000_000 },
+      ],
+      mapping,
+    );
+    expect(log.events[0]?.timestamp).toBe(date);
+    expect(log.events[1]?.timestamp).toBe(1_767_600_000_000);
+  });
+
+  it("copies the named columns into event attributes", () => {
+    const log = fromFlatRows(rows, { ...mapping, attributes: ["region"] });
+    expect(log.events[0]?.attributes).toEqual({ region: "North" });
+  });
+
+  it("takes the FIRST non-empty value per case for case attributes", () => {
+    const log = fromFlatRows(
+      [
+        { case: "1", step: "A", when: "2026-01-05T09:00:00Z", region: "North" },
+        { case: "1", step: "B", when: "2026-01-05T10:00:00Z", region: "Elsewhere" },
+      ],
+      { ...mapping, caseAttributes: ["region"] },
+    );
+    expect(log.caseAttributes).toEqual({ "1": { region: "North" } });
+  });
+
+  it("omits caseAttributes entirely when none were requested", () => {
+    expect(fromFlatRows(rows, mapping).caseAttributes).toBeUndefined();
+  });
+
+  it("feeds normalizeLog directly — the adapter's whole reason to exist", () => {
+    const normalized = normalizeLog(fromFlatRows(rows, mapping));
+    expect(normalized.totals).toEqual({ cases: 2, events: 3 });
+    expect(normalized.cases[0]?.events.map((e) => e.activity)).toEqual([
+      "Create Order",
+      "Check Credit",
+    ]);
+  });
+});
+
+describe("normalizeLifecycle", () => {
+  it("recognizes the default spellings, case-insensitively", () => {
+    expect(normalizeLifecycle("START")).toBe("start");
+    expect(normalizeLifecycle(" Completed ")).toBe("complete");
+    expect(normalizeLifecycle("schedule")).toBe("start");
+  });
+
+  it("answers undefined for an unknown or empty value", () => {
+    expect(normalizeLifecycle("suspend")).toBeUndefined();
+    expect(normalizeLifecycle("")).toBeUndefined();
+    expect(normalizeLifecycle(undefined)).toBeUndefined();
+  });
+
+  it("honours a source that spells the transitions differently", () => {
+    expect(normalizeLifecycle("S", { start: ["S"], complete: ["C"] })).toBe("start");
+    expect(normalizeLifecycle("C", { start: ["S"], complete: ["C"] })).toBe("complete");
+    // An override of one half falls back to the defaults for the other.
+    expect(normalizeLifecycle("complete", { start: ["S"] })).toBe("complete");
+  });
+
+  it("reaches normalizeLog through fromFlatRows and pairs the two halves", () => {
+    const log = fromFlatRows(
+      [
+        { case: "1", step: "Pick", when: "2026-01-05T09:00:00Z", phase: "S" },
+        { case: "1", step: "Pick", when: "2026-01-05T10:00:00Z", phase: "C" },
+      ],
+      { ...mapping, lifecycle: "phase", lifecycleValues: { start: ["S"], complete: ["C"] } },
+    );
+    const events = normalizeLog(log).cases[0]?.events ?? [];
+    expect(events).toHaveLength(1);
+    expect(events[0]?.duration).toBe(3_600_000);
+  });
+
+  it("exports the default spellings so a caller can extend rather than replace them", () => {
+    expect(DEFAULT_LIFECYCLE_VALUES.start).toContain("start");
+    expect(DEFAULT_LIFECYCLE_VALUES.complete).toContain("complete");
+  });
+});

package/src/core/adapters/flat.ts

@@ -0,0 +1,168 @@
+/**
+ * Flat tabular adapter — RM-049.
+ *
+ * Pre-shaped tabular data is the lingua franca of event logs: whatever the source (a
+ * warehouse query, a spreadsheet export, an API page), it arrives as rows of columns. This
+ * adapter maps those columns onto `EventRow`, so every other importer — the CSV reader
+ * next door, and any future one — can be a thin front end over this single mapping step
+ * rather than a second, subtly different interpretation of the same log.
+ *
+ * Pure and deterministic: no clock, no I/O, no mutation of the caller's rows.
+ */
+import type { EventLog, EventRow } from "../types";
+
+/** One row of a flat source. Values are read defensively — a source may hand back anything. */
+export type FlatRow = Record<string, unknown>;
+
+/** Which raw cell to read a lifecycle transition's `"start"` / `"complete"` from. */
+export interface LifecycleValues {
+  start?: readonly string[];
+  complete?: readonly string[];
+}
+
+/** Column names that `fromFlatRows` reads. Only `caseId`, `activity` and `timestamp` are required. */
+export interface FlatRowMapping {
+  /** Column holding the case (process instance) id. */
+  caseId: string;
+  /** Column holding the activity name. */
+  activity: string;
+  /** Column holding the event timestamp. */
+  timestamp: string;
+  /** Column holding an explicit interval start, when the source models one. */
+  startTimestamp?: string;
+  /** Column holding the executing resource. */
+  resource?: string;
+  /** Column holding a lifecycle transition. */
+  lifecycle?: string;
+  /** Extra columns copied verbatim into `EventRow.attributes`. */
+  attributes?: readonly string[];
+  /**
+   * Columns copied into `EventLog.caseAttributes`, taking the FIRST non-empty value seen
+   * per case. Case attributes are case-level by definition, so a later row disagreeing
+   * with an earlier one is a data problem, not something an adapter should silently
+   * resolve by overwriting.
+   */
+  caseAttributes?: readonly string[];
+  /**
+   * Raw cell values that mean `"start"` / `"complete"`, compared case-insensitively after
+   * trimming. Defaults to {@link DEFAULT_LIFECYCLE_VALUES}; supply your own for a source
+   * that spells them differently (`"S"` / `"C"`, `"begin"` / `"done"`).
+   */
+  lifecycleValues?: LifecycleValues;
+}
+
+/** The lifecycle spellings recognized when a mapping does not override them. */
+export const DEFAULT_LIFECYCLE_VALUES: Required<LifecycleValues> = {
+  start: ["start", "started", "begin", "assign", "schedule"],
+  complete: ["complete", "completed", "end", "finish", "finished", "done"],
+};
+
+/** Read a cell as a trimmed string, treating `null`/`undefined`/`""` as absent. */
+function readString(row: FlatRow, column: string | undefined): string | undefined {
+  if (column === undefined) return undefined;
+  const value = row[column];
+  if (value === undefined || value === null) return undefined;
+  const text = typeof value === "string" ? value.trim() : String(value);
+  return text === "" ? undefined : text;
+}
+
+/** Read a cell as something `toEpochMs` can resolve, without pre-converting it. */
+function readTimestamp(
+  row: FlatRow,
+  column: string | undefined,
+): string | number | Date | undefined {
+  if (column === undefined) return undefined;
+  const value = row[column];
+  if (value === undefined || value === null) return undefined;
+  if (value instanceof Date || typeof value === "number") return value;
+  const text = String(value).trim();
+  return text === "" ? undefined : text;
+}
+
+/** Coerce a cell into the `attributes` value union; anything else becomes its string form. */
+function readAttribute(value: unknown): string | number | boolean | null {
+  if (value === null || value === undefined) return null;
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  if (value instanceof Date) return value.toISOString();
+  return String(value);
+}
+
+/** Map a raw lifecycle cell onto the canonical pair, or `undefined` when it matches neither. */
+export function normalizeLifecycle(
+  raw: string | undefined,
+  values: LifecycleValues = DEFAULT_LIFECYCLE_VALUES,
+): "start" | "complete" | undefined {
+  if (raw === undefined) return undefined;
+  const needle = raw.trim().toLowerCase();
+  if (needle === "") return undefined;
+  const starts = values.start ?? DEFAULT_LIFECYCLE_VALUES.start;
+  const completes = values.complete ?? DEFAULT_LIFECYCLE_VALUES.complete;
+  for (const candidate of starts) if (candidate.toLowerCase() === needle) return "start";
+  for (const candidate of completes) if (candidate.toLowerCase() === needle) return "complete";
+  return undefined;
+}
+
+/**
+ * Map flat rows onto an {@link EventLog}.
+ *
+ * Rows missing a case id, an activity or a timestamp are SKIPPED rather than throwing: a
+ * single blank trailing line or one incomplete record must not fail an entire import, and
+ * an event with no activity cannot take part in a directly-follows relation anyway. Count
+ * the difference between `rows.length` and `log.events.length` when you need to surface
+ * how many were dropped.
+ */
+export function fromFlatRows(rows: readonly FlatRow[], mapping: FlatRowMapping): EventLog {
+  const events: EventRow[] = [];
+  let caseAttributes: Record<string, Record<string, unknown>> | undefined;
+
+  for (const row of rows) {
+    if (row === null || typeof row !== "object") continue;
+    const caseId = readString(row, mapping.caseId);
+    const activity = readString(row, mapping.activity);
+    const timestamp = readTimestamp(row, mapping.timestamp);
+    if (caseId === undefined || activity === undefined || timestamp === undefined) continue;
+
+    const event: EventRow = { caseId, activity, timestamp };
+
+    const startTimestamp = readTimestamp(row, mapping.startTimestamp);
+    if (startTimestamp !== undefined) event.startTimestamp = startTimestamp;
+
+    const resource = readString(row, mapping.resource);
+    if (resource !== undefined) event.resource = resource;
+
+    const lifecycle = normalizeLifecycle(
+      readString(row, mapping.lifecycle),
+      mapping.lifecycleValues,
+    );
+    if (lifecycle !== undefined) event.lifecycle = lifecycle;
+
+    if (mapping.attributes !== undefined && mapping.attributes.length > 0) {
+      const attributes: Record<string, string | number | boolean | null> = {};
+      let any = false;
+      for (const column of mapping.attributes) {
+        if (!(column in row)) continue;
+        attributes[column] = readAttribute(row[column]);
+        any = true;
+      }
+      if (any) event.attributes = attributes;
+    }
+
+    if (mapping.caseAttributes !== undefined && mapping.caseAttributes.length > 0) {
+      caseAttributes ??= {};
+      const bucket = (caseAttributes[caseId] ??= {});
+      for (const column of mapping.caseAttributes) {
+        if (bucket[column] !== undefined) continue;
+        const value = readString(row, column);
+        if (value !== undefined) bucket[column] = value;
+      }
+    }
+
+    events.push(event);
+  }
+
+  const log: EventLog = { events };
+  if (caseAttributes !== undefined) log.caseAttributes = caseAttributes;
+  return log;
+}