@lotics/xlsx 0.1.0

package/src/fill_patterns.ts

@@ -0,0 +1,71 @@
+// =============================================================================
+// Fill Patterns
+// =============================================================================
+//
+// Predefined cycle tables for auto-fill series (months, days, quarters).
+// detectCyclePattern checks if values match a contiguous subsequence of any
+// predefined list, enabling drag-fill to continue the cycle.
+// =============================================================================
+
+const CYCLE_LISTS: string[][] = [
+  ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"],
+  ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"],
+  ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"],
+  ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"],
+  ["Q1", "Q2", "Q3", "Q4"],
+];
+
+// Lowercase lookup tables built once
+const CYCLE_LOOKUPS = CYCLE_LISTS.map((list) => list.map((v) => v.toLowerCase()));
+
+export interface CycleMatch {
+  list: string[];
+  startIndex: number;
+}
+
+/**
+ * Check if the given values match a contiguous subsequence of any predefined cycle list.
+ * Returns the matched list and start index, or null if no match.
+ */
+export function detectCyclePattern(values: string[]): CycleMatch | null {
+  if (values.length === 0) return null;
+
+  const lowerValues = values.map((v) => v.toLowerCase());
+
+  for (let listIdx = 0; listIdx < CYCLE_LOOKUPS.length; listIdx++) {
+    const lookup = CYCLE_LOOKUPS[listIdx];
+    const list = CYCLE_LISTS[listIdx];
+
+    // Find the first value in the cycle
+    const firstIndex = lookup.indexOf(lowerValues[0]);
+    if (firstIndex === -1) continue;
+
+    // Check if all values follow contiguously (wrapping around)
+    let matches = true;
+    for (let i = 1; i < lowerValues.length; i++) {
+      const expected = lookup[(firstIndex + i) % lookup.length];
+      if (lowerValues[i] !== expected) {
+        matches = false;
+        break;
+      }
+    }
+
+    if (matches) {
+      return { list, startIndex: firstIndex };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Given a matched cycle, return the next N values after the matched sequence.
+ */
+export function continueCycle(match: CycleMatch, matchedCount: number, count: number): string[] {
+  const result: string[] = [];
+  for (let i = 0; i < count; i++) {
+    const idx = (match.startIndex + matchedCount + i) % match.list.length;
+    result.push(match.list[idx]);
+  }
+  return result;
+}

package/src/flash_fill.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect } from "vitest";
+import { flashFill } from "./flash_fill";
+
+describe("flashFill", () => {
+  it("induces UPPER from one example", () => {
+    const out = flashFill(
+      [{ source: "John", output: "JOHN" }],
+      ["Mary", "Sue"],
+    );
+    expect(out).toEqual(["MARY", "SUE"]);
+  });
+
+  it("induces token pick — first by space", () => {
+    const out = flashFill(
+      [
+        { source: "John Smith", output: "John" },
+        { source: "Mary Jane", output: "Mary" },
+      ],
+      ["Bob Builder"],
+    );
+    expect(out).toEqual(["Bob"]);
+  });
+
+  it("induces token pick — last by space", () => {
+    const out = flashFill(
+      [
+        { source: "John Quincy Smith", output: "Smith" },
+        { source: "Mary Jane", output: "Jane" },
+      ],
+      ["Bob Builder"],
+    );
+    expect(out).toEqual(["Builder"]);
+  });
+
+  it("induces fixed slice", () => {
+    const out = flashFill(
+      [
+        { source: "12345", output: "234" },
+        { source: "67890", output: "789" },
+      ],
+      ["00000"],
+    );
+    expect(out).toEqual(["000"]);
+  });
+
+  it("induces concat template (Mr. + first token)", () => {
+    const out = flashFill(
+      [
+        { source: "John Smith", output: "Mr. John" },
+        { source: "Mary Jane", output: "Mr. Mary" },
+      ],
+      ["Bob Builder", "Sue Storm"],
+    );
+    expect(out).toEqual(["Mr. Bob", "Mr. Sue"]);
+  });
+
+  it("induces token pick from email (split by @)", () => {
+    const out = flashFill(
+      [
+        { source: "alice@example.com", output: "alice" },
+        { source: "bob@example.com", output: "bob" },
+      ],
+      ["carol@example.com"],
+    );
+    expect(out).toEqual(["carol"]);
+  });
+
+  it("returns undefined when no pattern matches", () => {
+    const out = flashFill(
+      [{ source: "hello", output: "totally unrelated" }],
+      ["test"],
+    );
+    expect(out).toBeUndefined();
+  });
+});

package/src/flash_fill.ts

@@ -0,0 +1,221 @@
+// =============================================================================
+// Flash Fill — Excel's Ctrl+E pattern induction
+// =============================================================================
+//
+// Detect a simple text transformation by example: the user types one or more
+// example outputs in a column adjacent to a source column, then presses
+// Ctrl+E. We compare each example to the source row in the column to its
+// left, induce a transformation pattern, and apply it to the rest of the
+// column.
+//
+// Coverage targets the most common Flash Fill use cases that don't need
+// a real DSL synthesizer:
+//   - **Identity**: copy source verbatim
+//   - **Substring**: prefix / suffix / range slice (start..end)
+//   - **Token pick**: split source by a delimiter, pick the Nth token
+//   - **Concat**: prefix + token + suffix patterns
+//   - **Case change**: UPPER / lower / Title Case
+//
+// More complex transformations (regex, conditional formatting, multi-source
+// columns) are out of scope; users fall back to formulas.
+// =============================================================================
+
+export interface FlashFillExample {
+  source: string;
+  output: string;
+}
+
+/**
+ * Induce a pattern from examples and apply it to a list of new sources.
+ * Returns one output per `applyTo` source, or `undefined` for that row when
+ * no pattern matches. If no consistent pattern is induced, returns
+ * `undefined` for the whole array (caller should leave cells unchanged).
+ */
+export function flashFill(
+  examples: FlashFillExample[],
+  applyTo: string[],
+): (string | undefined)[] | undefined {
+  const filtered = examples.filter((e) => e.output !== "");
+  if (filtered.length === 0) return undefined;
+
+  const patterns = [
+    inducePassthrough,
+    induceUpper,
+    induceLower,
+    induceTitle,
+    induceTokenPick,
+    induceSlice,
+    induceConcatTemplate,
+  ];
+
+  for (const induce of patterns) {
+    const fn = induce(filtered);
+    if (!fn) continue;
+    return applyTo.map((src) => fn(src));
+  }
+  return undefined;
+}
+
+type Transform = (source: string) => string | undefined;
+type Inducer = (examples: FlashFillExample[]) => Transform | undefined;
+
+// ---------------------------------------------------------------------------
+// Trivial: copy source.
+// ---------------------------------------------------------------------------
+const inducePassthrough: Inducer = (examples) => {
+  if (examples.every((e) => e.source === e.output)) return (s) => s;
+  return undefined;
+};
+
+// ---------------------------------------------------------------------------
+// Case transformations.
+// ---------------------------------------------------------------------------
+const induceUpper: Inducer = (examples) => {
+  if (examples.every((e) => e.source.toUpperCase() === e.output)) return (s) => s.toUpperCase();
+  return undefined;
+};
+
+const induceLower: Inducer = (examples) => {
+  if (examples.every((e) => e.source.toLowerCase() === e.output)) return (s) => s.toLowerCase();
+  return undefined;
+};
+
+const induceTitle: Inducer = (examples) => {
+  const titlecase = (s: string) =>
+    s.replace(/\w\S*/g, (w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase());
+  if (examples.every((e) => titlecase(e.source) === e.output)) return titlecase;
+  return undefined;
+};
+
+// ---------------------------------------------------------------------------
+// Token pick: split source by a single delimiter, return the Nth token.
+// We try every common delimiter and every reasonable index.
+// ---------------------------------------------------------------------------
+const COMMON_DELIMITERS = [" ", ",", "-", "/", ".", "_", "@", ";", "\t"];
+
+const induceTokenPick: Inducer = (examples) => {
+  for (const delim of COMMON_DELIMITERS) {
+    if (!examples.every((e) => e.source.includes(delim))) continue;
+    const tokenCounts = examples.map((e) => e.source.split(delim).length);
+    const minTokens = Math.min(...tokenCounts);
+    for (let i = 0; i < minTokens; i++) {
+      const pickFromEnd = false;
+      let allMatch = true;
+      for (const e of examples) {
+        const tokens = e.source.split(delim);
+        const idx = pickFromEnd ? tokens.length - 1 - i : i;
+        if (tokens[idx] !== e.output) { allMatch = false; break; }
+      }
+      if (allMatch) {
+        return (s) => {
+          const tokens = s.split(delim);
+          return tokens[i];
+        };
+      }
+    }
+    // Pick from the end (negative index)
+    for (let i = 0; i < minTokens; i++) {
+      let allMatch = true;
+      for (const e of examples) {
+        const tokens = e.source.split(delim);
+        if (tokens[tokens.length - 1 - i] !== e.output) { allMatch = false; break; }
+      }
+      if (allMatch) {
+        return (s) => {
+          const tokens = s.split(delim);
+          return tokens[tokens.length - 1 - i];
+        };
+      }
+    }
+  }
+  return undefined;
+};
+
+// ---------------------------------------------------------------------------
+// Substring slice: output is contiguous slice [start..end] of source.
+// We induce by checking the first example, then verifying on the rest.
+// ---------------------------------------------------------------------------
+const induceSlice: Inducer = (examples) => {
+  const e0 = examples[0];
+  if (!e0.output) return undefined;
+  // Find indexOf(output, source) — first matching contiguous slice.
+  const idx = e0.source.indexOf(e0.output);
+  if (idx < 0) return undefined;
+  const len = e0.output.length;
+  const fromEnd = e0.source.length - idx - len;
+
+  // Try fixed-start fixed-length
+  if (examples.every((e) => e.source.substr(idx, len) === e.output)) {
+    return (s) => s.substr(idx, len);
+  }
+  // Try fixed-start, run-to-end
+  if (examples.every((e) => e.source.substring(idx) === e.output)) {
+    return (s) => s.substring(idx);
+  }
+  // Try start-to-fixed-length
+  if (idx === 0 && examples.every((e) => e.source.substring(0, len) === e.output)) {
+    return (s) => s.substring(0, len);
+  }
+  // Try fixed-from-end
+  if (examples.every((e) => e.source.substring(e.source.length - fromEnd - len, e.source.length - fromEnd) === e.output)) {
+    return (s) => s.substring(s.length - fromEnd - len, s.length - fromEnd);
+  }
+  return undefined;
+};
+
+// ---------------------------------------------------------------------------
+// Concat template: detect a literal prefix + extracted-token + literal suffix.
+// Example: "John Smith" → "Mr. John" comes from "Mr. " + first-token-by-space.
+// We probe for the longest literal prefix and suffix shared across outputs,
+// then check that the remaining middle is a token from the source.
+// ---------------------------------------------------------------------------
+const induceConcatTemplate: Inducer = (examples) => {
+  if (examples.length < 1) return undefined;
+  const outputs = examples.map((e) => e.output);
+
+  // Common prefix across outputs
+  let prefix = outputs[0];
+  for (let i = 1; i < outputs.length; i++) {
+    let j = 0;
+    while (j < prefix.length && j < outputs[i].length && prefix[j] === outputs[i][j]) j++;
+    prefix = prefix.slice(0, j);
+  }
+
+  // Common suffix across outputs
+  let suffix = outputs[0];
+  for (let i = 1; i < outputs.length; i++) {
+    let j = 0;
+    while (j < suffix.length && j < outputs[i].length && suffix[suffix.length - 1 - j] === outputs[i][outputs[i].length - 1 - j]) j++;
+    suffix = suffix.slice(suffix.length - j);
+  }
+
+  if (prefix.length + suffix.length === 0) return undefined;
+  // The middle bit (output without the prefix/suffix) must be a substring of
+  // source for every example. Check what slice of source produces it.
+  const middles = examples.map((e) =>
+    e.output.slice(prefix.length, e.output.length - suffix.length),
+  );
+
+  // Try: middle is the first token by some delimiter
+  for (const delim of COMMON_DELIMITERS) {
+    if (examples.every((e, i) => e.source.split(delim)[0] === middles[i])) {
+      return (s) => `${prefix}${s.split(delim)[0]}${suffix}`;
+    }
+    if (examples.every((e, i) => {
+      const t = e.source.split(delim);
+      return t[t.length - 1] === middles[i];
+    })) {
+      return (s) => {
+        const t = s.split(delim);
+        return `${prefix}${t[t.length - 1]}${suffix}`;
+      };
+    }
+  }
+
+  // Try: middle is the entire source
+  if (examples.every((e, i) => e.source === middles[i])) {
+    return (s) => `${prefix}${s}${suffix}`;
+  }
+
+  return undefined;
+};

package/src/formula_deps.ts

@@ -0,0 +1,189 @@
+// =============================================================================
+// Formula Dependency Graph
+// =============================================================================
+//
+// Tracks which cells depend on which other cells. Used for:
+// 1. Incremental recalculation — only recompute affected cells after an edit
+// 2. Topological sort — evaluate formulas in correct dependency order
+// 3. Circular reference detection — detect and flag #CIRC! errors
+//
+// Cell keys are qualified: "Sheet1!A1", "Sheet2!B5", etc.
+// =============================================================================
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface CellRef {
+  sheet: string;
+  ref: string; // A1-style
+}
+
+/** Unique string key for a cell reference. */
+export function cellKey(cell: CellRef): string {
+  return `${cell.sheet}!${cell.ref}`;
+}
+
+export function parseCellKey(key: string): CellRef {
+  const bang = key.indexOf("!");
+  return { sheet: key.slice(0, bang), ref: key.slice(bang + 1) };
+}
+
+// =============================================================================
+// DependencyGraph
+// =============================================================================
+
+export class DependencyGraph {
+  // Forward edges: cell → cells it references (precedents)
+  private precedents = new Map<string, Set<string>>();
+  // Reverse edges: cell → cells that reference it (dependents)
+  private dependents = new Map<string, Set<string>>();
+
+  /** Set all dependencies for a cell (replacing any existing ones). */
+  setDependencies(cell: string, deps: string[]): void {
+    // Remove old edges
+    this.removeCell(cell);
+
+    if (deps.length === 0) return;
+
+    // Add new edges
+    const precSet = new Set(deps);
+    this.precedents.set(cell, precSet);
+    for (const dep of precSet) {
+      let depSet = this.dependents.get(dep);
+      if (!depSet) {
+        depSet = new Set();
+        this.dependents.set(dep, depSet);
+      }
+      depSet.add(cell);
+    }
+  }
+
+  /** Remove all edges for a cell (when formula is deleted or cell is cleared). */
+  removeCell(cell: string): void {
+    const oldPrec = this.precedents.get(cell);
+    if (oldPrec) {
+      for (const dep of oldPrec) {
+        this.dependents.get(dep)?.delete(cell);
+      }
+      this.precedents.delete(cell);
+    }
+  }
+
+  /** Get all cells that directly depend on the given cell. */
+  getDirectDependents(cell: string): string[] {
+    return Array.from(this.dependents.get(cell) ?? []);
+  }
+
+  /** Get all cells that need recalculation when the given cells change, in topological order. */
+  getRecalcOrder(changed: string[]): string[] {
+    const changedSet = new Set(changed);
+
+    // BFS to find all transitive dependents (index pointer instead of shift())
+    const affected = new Set<string>();
+    const queue = [...changed];
+    let head = 0;
+    while (head < queue.length) {
+      const cell = queue[head++];
+      const deps = this.dependents.get(cell);
+      if (!deps) continue;
+      for (const dep of deps) {
+        if (!affected.has(dep)) {
+          affected.add(dep);
+          queue.push(dep);
+        }
+      }
+    }
+
+    if (affected.size === 0) return [];
+
+    // Topological sort using Kahn's algorithm (restricted to affected cells).
+    // inDegree counts precedents in `affected` only — precedents in
+    // `changedSet` (the seed) are evaluated before this `order` runs, so
+    // their dependents must start with inDegree 0 within affected. Including
+    // changedSet here would make every dependent appear cyclic when the
+    // seed is the entire formula set (evaluateAll), degenerating Kahn into
+    // arbitrary insertion order and breaking cascading SUM/range formulas.
+    const inDegree = new Map<string, number>();
+    for (const cell of affected) {
+      let count = 0;
+      const prec = this.precedents.get(cell);
+      if (prec) {
+        for (const p of prec) {
+          if (affected.has(p)) count++;
+        }
+      }
+      inDegree.set(cell, count);
+    }
+
+    const result: string[] = [];
+    const ready: string[] = [];
+    let readyHead = 0;
+    for (const [cell, deg] of inDegree) {
+      if (deg === 0) ready.push(cell);
+    }
+
+    while (readyHead < ready.length) {
+      const cell = ready[readyHead++];
+      result.push(cell);
+      const deps = this.dependents.get(cell);
+      if (!deps) continue;
+      for (const dep of deps) {
+        if (!affected.has(dep)) continue;
+        const newDeg = (inDegree.get(dep) ?? 1) - 1;
+        inDegree.set(dep, newDeg);
+        if (newDeg === 0) ready.push(dep);
+      }
+    }
+
+    // Any remaining cells with non-zero in-degree are part of a cycle
+    const resultSet = new Set(result);
+    for (const [cell, deg] of inDegree) {
+      if (deg > 0 && !resultSet.has(cell)) {
+        result.push(cell);
+      }
+    }
+
+    return result;
+  }
+
+  /** Detect if `cell` appears in its own transitive precedent chain (circular reference). */
+  detectCycle(cell: string): string[] | null {
+    const visited = new Set<string>();
+    const stack = new Array<{ cell: string; path: string[] }>();
+
+    // Seed with direct precedents
+    const prec = this.precedents.get(cell);
+    if (!prec) return null;
+
+    for (const p of prec) {
+      stack.push({ cell: p, path: [cell, p] });
+    }
+
+    while (stack.length > 0) {
+      const { cell: current, path } = stack.pop()!;
+      if (current === cell) return path;
+      if (visited.has(current)) continue;
+      visited.add(current);
+
+      const nextPrec = this.precedents.get(current);
+      if (!nextPrec) continue;
+      for (const p of nextPrec) {
+        stack.push({ cell: p, path: [...path, p] });
+      }
+    }
+
+    return null;
+  }
+
+  /** Clear the entire graph. */
+  clear(): void {
+    this.precedents.clear();
+    this.dependents.clear();
+  }
+
+  /** Number of cells with dependencies. */
+  get size(): number {
+    return this.precedents.size;
+  }
+}