@origints/xlsx 0.1.1 → 0.3.2

package/README.md

@@ -4,14 +4,6 @@
 
 ---
 
-## Why
-
-Extracting data from Excel files often means losing track of where values came from. When a number is wrong, you can't easily trace it back to cell B47 on the "Q3 Sales" sheet.
-
-This package provides rich navigation APIs for Excel workbooks while maintaining complete provenance. Every value knows its exact location: workbook, sheet, row, column, and cell address.
-
----
-
 ## Features
 
 - Parse XLSX files from streams, buffers, or file paths
@@ -24,158 +16,296 @@ This package provides rich navigation APIs for Excel workbooks while maintaining
 
 ---
 
-## Quick Start
+## Installation
 
 ```bash
 npm install @origints/xlsx @origints/core
 ```
 
-```ts
-import { parseXlsxFile } from "@origints/xlsx";
+---
 
-const result = await parseXlsxFile("data.xlsx");
+## Usage with Planner
 
-if (result.ok) {
-  const workbook = result.value;
-  const sheet = workbook.getSheet("Sheet1");
-  const value = sheet.cell("A1").asString();
-  console.log(value);
-}
-```
+### Extract cell values from a spreadsheet
 
-Expected output:
+```ts
+import { Planner, loadFile, run } from '@origints/core'
+import { parseXlsx } from '@origints/xlsx'
 
+const plan = new Planner()
+  .in(loadFile('data.xlsx'))
+  .mapIn(parseXlsx())
+  .emit((out, $) =>
+    out
+      .add('title', $.firstSheet().cell('A1').string())
+      .add('revenue', $.firstSheet().cell('B2').number())
+  )
+  .compile()
+
+const result = await run(plan, { readFile, registry })
+// result.value: { title: 'Q4 Report', revenue: 150000 }
 ```
-Hello
-```
-
----
-
-## Installation
 
-- Supported platforms:
-  - macOS / Linux / Windows
-- Runtime requirements:
-  - Node.js >= 18
-- Package managers:
-  - npm, pnpm, yarn
-- Peer dependencies:
-  - @origints/core ^0.1.0
+### Extract from specific sheets
 
-```bash
-npm install @origints/xlsx @origints/core
-# or
-pnpm add @origints/xlsx @origints/core
+```ts
+const plan = new Planner()
+  .in(loadFile('report.xlsx'))
+  .mapIn(parseXlsx())
+  .emit((out, $) =>
+    out
+      .add('totalSales', $.sheet('Sales').cell('B10').number())
+      .add('totalExpenses', $.sheet('Expenses').cell('B10').number())
+  )
+  .compile()
 ```
 
----
-
-## Usage
+### Extract rows from a range
 
-### Reading cells
+Use `range().rows()` to iterate over rows in a range and extract structured data:
 
 ```ts
-import { parseXlsxFile } from "@origints/xlsx";
+// Spreadsheet has headers in row 1: Name | Age | Department
+// Data rows in A2:C10
 
-const result = await parseXlsxFile("report.xlsx");
+const plan = new Planner()
+  .in(loadFile('employees.xlsx'))
+  .mapIn(parseXlsx())
+  .emit((out, $) =>
+    out.add(
+      'employees',
+      $.firstSheet()
+        .range('A2:C4')
+        .rows(row => ({
+          kind: 'object',
+          properties: {
+            name: row.col(1).string(),
+            age: row.col(2).number(),
+            dept: row.col(3).string(),
+          },
+        }))
+    )
+  )
+  .compile()
+
+const result = await run(plan, { readFile, registry })
+// result.value: {
+//   employees: [
+//     { name: 'Alice', age: 30, dept: 'Engineering' },
+//     { name: 'Bob', age: 25, dept: 'Marketing' },
+//     ...
+//   ]
+// }
+```
 
-if (result.ok) {
-  const sheet = result.value.getSheet("Data");
+### Range from two corners
 
-  const name = sheet.cell("A1").asString();
-  const amount = sheet.cell("B1").asNumber();
-  const date = sheet.cell("C1").asDate();
-}
+`range()` accepts two addresses or two dynamic cell builders:
+
+```ts
+// Two string addresses — equivalent to range("A2:C10")
+$.firstSheet().range("A2", "C10").rows(...)
+
+// Dynamic corners — cells resolved at runtime
+const topLeft = $.firstSheet().find(cell.equals("Name"));
+const bottomRight = $.firstSheet().find(cell.equals("Total")).left();
+$.firstSheet().range(topLeft, bottomRight).rows((row) => ({
+  kind: "object",
+  properties: {
+    name: row.col(1).string(),
+    value: row.col(2).number(),
+  },
+}));
 ```
 
-### Working with ranges
+### Collect rows with predicates
 
-```ts
-const sheet = workbook.getSheet("Sales");
+Use `eachSlice()` to iterate rows from a starting cell while a predicate holds, with header-relative column access:
 
-// Get a range
-const range = sheet.range("A1:D10");
+```ts
+import { cell, rowCol } from '@origints/xlsx'
 
-// Convert to array of arrays
-const rows = rangeToArray(range);
+const hasData = rowCol(0, cell.isNotEmpty()).and(
+  rowCol(0, cell.startsWith('Total').not())
+)
 
-// Convert to objects using first row as headers
-const records = rangeToObjects(range);
+const plan = new Planner()
+  .in(loadFile('report.xlsx'))
+  .mapIn(parseXlsx())
+  .emit((out, $) => {
+    const header = $.firstSheet().find(cell.equals('Name'))
+
+    return out.add(
+      'people',
+      header.down().eachSlice('down', hasData, row => ({
+        kind: 'object',
+        properties: {
+          name: row.colWhere(header, cell.equals('Name')).string(),
+          role: row.colWhere(header, cell.equals('Role')).string(),
+        },
+      }))
+    )
+  })
+  .compile()
 ```
 
-### Cursor-based iteration
-
-```ts
-import { XlsxCursor } from "@origints/xlsx";
+### Collect cell values in a direction
 
-const cursor = new XlsxCursor(sheet, "A1");
+Use `eachCell()` to gather cells in a direction while a predicate matches:
 
-// Move and grab values
-cursor.move("right", 2);
-const value = cursor.grab();
+```ts
+import { cell } from '@origints/xlsx'
 
-// Iterate rows
-while (cursor.hasMore("down")) {
-  const row = cursor.grabRow(4);
-  cursor.move("down");
-}
+const plan = new Planner()
+  .in(loadFile('data.xlsx'))
+  .mapIn(parseXlsx())
+  .emit((out, $) =>
+    out.add(
+      'values',
+      $.firstSheet()
+        .cell('B2')
+        .eachCell('down', cell.isNotEmpty(), c => c.number())
+    )
+  )
+  .compile()
+
+const result = await run(plan, { readFile, registry })
+// result.value: { values: [100, 200, 300, 400] }
 ```
 
-### Using with Origins plans
+### Optional and fallback extraction
 
-```ts
-import { Planner, loadFile, globalRegistry } from "@origints/core";
-import { parseXlsx, registerXlsxTransforms } from "@origints/xlsx";
+Handle missing or invalid cell values using `optional()`, `tryExtract()`, `mapSpec()`, and `guard()`:
 
-registerXlsxTransforms(globalRegistry);
+```ts
+import { literal, optional, tryExtract, mapSpec, guard } from '@origints/core'
+import { cell, rowCol } from '@origints/xlsx'
 
-const plan = Planner.in(loadFile("data.xlsx"))
+const plan = new Planner()
+  .in(loadFile('portfolio.xlsx'))
   .mapIn(parseXlsx())
   .emit((out, $) => {
-    const sheet = $.getSheet("Summary");
-    out.add("total", sheet.cell("B10").asNumber());
+    const header = $.firstSheet().find(cell.equals('Company'))
+    const hasData = rowCol(0, cell.isNotEmpty()).and(
+      rowCol(0, cell.startsWith('Total').not())
+    )
+
+    return out.add(
+      'companies',
+      header.down().eachSlice('down', hasData, row => ({
+        kind: 'object',
+        properties: {
+          // Required field
+          name: row.colWhere(header, cell.equals('Company')).string(),
+          // Optional: returns null when cell is empty or has wrong type
+          ownership: optional(
+            row.colWhere(header, cell.equals('Ownership %')).number(),
+            null
+          ),
+          // Fallback: try number first, then parse string, then null
+          revenue: tryExtract(
+            row.colWhere(header, cell.equals('Revenue')).number(),
+            mapSpec(
+              row.colWhere(header, cell.equals('Revenue')).string(),
+              v => parseFloat((v as string).replace(/[,$]/g, '')),
+              'parseFloat'
+            ),
+            literal(null)
+          ),
+          // Guard: ensure investment amount is positive
+          investment: guard(
+            row.colWhere(header, cell.equals('Investment')).number(),
+            v => (v as number) > 0,
+            'Investment must be positive'
+          ),
+        },
+      }))
+    )
   })
-  .compile();
+  .compile()
 ```
 
-### Export to CSV
+### Combine with other data sources
 
 ```ts
-import { sheetToCsv, rangeToCsv } from "@origints/xlsx";
-
-const csv = sheetToCsv(sheet);
-// or for a specific range
-const rangeCsv = rangeToCsv(sheet.range("A1:C10"));
+const plan = new Planner()
+  .in(loadFile('budget.xlsx'))
+  .mapIn(parseXlsx())
+  .emit((out, $) => out.add('budget', $.firstSheet().cell('B2').number()))
+  .in(loadFile('config.json'))
+  .mapIn(parseJson())
+  .emit((out, $) => out.add('department', $.get('department').string()))
+  .compile()
 ```
 
----
-
-## Project Status
+### Standalone usage (without Planner)
 
-- **Experimental** - APIs may change
+For direct workbook navigation:
 
----
+```ts
+import { parseXlsxAsyncImpl, XlsxWorkbook } from '@origints/xlsx'
+
+const workbook = (await parseXlsxAsyncImpl.execute(buffer)) as XlsxWorkbook
+
+// Navigate sheets
+const sheetResult = workbook.sheet('Sheet1')
+if (sheetResult.ok) {
+  const sheet = sheetResult.value
+
+  // Read a cell
+  const cellResult = sheet.cell('A1')
+  if (cellResult.ok) {
+    console.log(cellResult.value.string().value)
+  }
+
+  // Work with ranges
+  const rangeResult = sheet.range('A1:D10')
+  if (rangeResult.ok) {
+    const range = rangeResult.value
+    // Convert to array of arrays
+    const rows = range.toArray()
+    // Convert to objects using first row as headers
+    const records = range.toObjects()
+  }
+}
+```
 
-## Non-Goals
+### Cursor-based iteration
 
-- Not an XLSX writer/generator
-- Not a formula evaluator
-- Not a chart/image extractor
+```ts
+import { XlsxCursor } from '@origints/xlsx'
 
----
+const sheetResult = workbook.sheet('Data')
+if (sheetResult.ok) {
+  const cursor = new XlsxCursor(sheetResult.value, 'A1')
 
-## Documentation
+  // Move and grab values
+  cursor.move('right', 2)
+  const value = cursor.grab()
 
-- See `@origints/core` for Origins concepts
-- See [exceljs](https://www.npmjs.com/package/exceljs) for underlying parser
+  // Iterate rows
+  while (cursor.hasMore('down')) {
+    const row = cursor.grabRow(4)
+    cursor.move('down')
+  }
+}
+```
 
 ---
 
-## Contributing
-
-- Open an issue before large changes
-- Keep PRs focused
-- Tests required for new features
+## API
+
+| Export                             | Description                                           |
+| ---------------------------------- | ----------------------------------------------------- |
+| `parseXlsx(options?)`              | Create a transform AST for use with `Planner.mapIn()` |
+| `parseXlsxImpl`                    | Sync transform implementation                         |
+| `parseXlsxAsyncImpl`               | Async transform implementation (stream/buffer)        |
+| `registerXlsxTransforms(registry)` | Register all XLSX transforms with a registry          |
+| `XlsxWorkbook`                     | Workbook navigation                                   |
+| `XlsxSheet`                        | Sheet navigation with cell/range access               |
+| `XlsxRange`                        | Range operations and conversion                       |
+| `XlsxCell`                         | Cell value extraction                                 |
+| `XlsxCursor`                       | Sequential cursor-based iteration                     |
 
 ---