@origints/xlsx 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,184 @@
+# @origints/xlsx
+
+> XLSX parsing for Origins with full traceability to sheets, ranges, and cells.
+
+---
+
+## 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
+- Navigate workbooks, sheets, ranges, and cells
+- Cursor-based iteration for sequential processing
+- Cell predicates for conditional extraction
+- Convert ranges to JSON, arrays, or objects
+- Export to CSV format
+- Full source location tracking for every cell
+
+---
+
+## Quick Start
+
+```bash
+npm install @origints/xlsx @origints/core
+```
+
+```ts
+import { parseXlsxFile } from "@origints/xlsx";
+
+const result = await parseXlsxFile("data.xlsx");
+
+if (result.ok) {
+  const workbook = result.value;
+  const sheet = workbook.getSheet("Sheet1");
+  const value = sheet.cell("A1").asString();
+  console.log(value);
+}
+```
+
+Expected output:
+
+```
+Hello
+```
+
+---
+
+## Installation
+
+- Supported platforms:
+  - macOS / Linux / Windows
+- Runtime requirements:
+  - Node.js >= 18
+- Package managers:
+  - npm, pnpm, yarn
+- Peer dependencies:
+  - @origints/core ^0.1.0
+
+```bash
+npm install @origints/xlsx @origints/core
+# or
+pnpm add @origints/xlsx @origints/core
+```
+
+---
+
+## Usage
+
+### Reading cells
+
+```ts
+import { parseXlsxFile } from "@origints/xlsx";
+
+const result = await parseXlsxFile("report.xlsx");
+
+if (result.ok) {
+  const sheet = result.value.getSheet("Data");
+
+  const name = sheet.cell("A1").asString();
+  const amount = sheet.cell("B1").asNumber();
+  const date = sheet.cell("C1").asDate();
+}
+```
+
+### Working with ranges
+
+```ts
+const sheet = workbook.getSheet("Sales");
+
+// Get a range
+const range = sheet.range("A1:D10");
+
+// Convert to array of arrays
+const rows = rangeToArray(range);
+
+// Convert to objects using first row as headers
+const records = rangeToObjects(range);
+```
+
+### Cursor-based iteration
+
+```ts
+import { XlsxCursor } from "@origints/xlsx";
+
+const cursor = new XlsxCursor(sheet, "A1");
+
+// Move and grab values
+cursor.move("right", 2);
+const value = cursor.grab();
+
+// Iterate rows
+while (cursor.hasMore("down")) {
+  const row = cursor.grabRow(4);
+  cursor.move("down");
+}
+```
+
+### Using with Origins plans
+
+```ts
+import { Planner, loadFile, globalRegistry } from "@origints/core";
+import { parseXlsx, registerXlsxTransforms } from "@origints/xlsx";
+
+registerXlsxTransforms(globalRegistry);
+
+const plan = Planner.in(loadFile("data.xlsx"))
+  .mapIn(parseXlsx())
+  .emit((out, $) => {
+    const sheet = $.getSheet("Summary");
+    out.add("total", sheet.cell("B10").asNumber());
+  })
+  .compile();
+```
+
+### Export to CSV
+
+```ts
+import { sheetToCsv, rangeToCsv } from "@origints/xlsx";
+
+const csv = sheetToCsv(sheet);
+// or for a specific range
+const rangeCsv = rangeToCsv(sheet.range("A1:C10"));
+```
+
+---
+
+## Project Status
+
+- **Experimental** - APIs may change
+
+---
+
+## Non-Goals
+
+- Not an XLSX writer/generator
+- Not a formula evaluator
+- Not a chart/image extractor
+
+---
+
+## Documentation
+
+- See `@origints/core` for Origins concepts
+- See [exceljs](https://www.npmjs.com/package/exceljs) for underlying parser
+
+---
+
+## Contributing
+
+- Open an issue before large changes
+- Keep PRs focused
+- Tests required for new features
+
+---
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@origints/xlsx",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "XLSX parsing for Origins with full traceability to sheets, ranges, and cells.",
   "type": "module",
   "license": "MIT",
@@ -20,6 +20,13 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint \"{src,tests}/**/*.{ts,tsx}\" --max-warnings 0",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
   "dependencies": {
     "exceljs": "^4.4.0"
   },
@@ -27,20 +34,13 @@
     "@origints/core": "^0.1.0"
   },
   "devDependencies": {
+    "@origints/core": "workspace:*",
     "@types/node": "25.0.6",
     "@vitest/coverage-v8": "^4.0.16",
     "eslint": "9.39.2",
     "typescript": "5.9.3",
     "vite": "7.3.1",
     "vite-plugin-dts": "4.5.4",
-    "vitest": "4.0.16",
-    "@origints/core": "0.1.0"
-  },
-  "scripts": {
-    "build": "vite build",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage",
-    "lint": "eslint \"{src,tests}/**/*.{ts,tsx}\" --max-warnings 0",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "vitest": "4.0.16"
   }
-}
+}