@origints/xlsx 0.1.1 → 0.3.2

package/dist/xlsx-spec-builder.d.ts

@@ -0,0 +1,220 @@
+import { StepBuilder, ArraySpec, ObjectSpec, ExtractSpec, Spec, SpecLike } from '@origints/core';
+import { XlsxStep, Direction } from './xlsx-spec';
+import { CellPred, SheetPred, RowPred } from './xlsx-predicate-spec';
+/**
+ * Spec builder at the cell level — terminal extraction and navigation methods.
+ */
+export declare class XlsxCellSB extends StepBuilder<XlsxStep, 'xlsx'> {
+    protected get format(): "xlsx";
+    /** @internal */
+    constructor(steps: readonly XlsxStep[]);
+    /** @internal Expose steps for colWhere/rowWhere headerRef */
+    get _steps(): readonly XlsxStep[];
+    /** Extract cell value as string */
+    string(): ExtractSpec<XlsxStep, 'string'>;
+    /** Extract cell value as number */
+    number(): ExtractSpec<XlsxStep, 'number'>;
+    /** Extract cell value as boolean */
+    boolean(): ExtractSpec<XlsxStep, 'boolean'>;
+    /** Extract cell value as Date */
+    date(): ExtractSpec<XlsxStep, 'date'>;
+    /** Extract raw cell value */
+    value(): ExtractSpec<XlsxStep, 'value'>;
+    /** Extract cell formula */
+    formula(): ExtractSpec<XlsxStep, 'formula'>;
+    /** Extract cell value as string, returning default on failure */
+    optionalString(defaultValue?: unknown): ExtractSpec<XlsxStep, 'string'>;
+    /** Extract cell value as number, returning default on failure */
+    optionalNumber(defaultValue?: unknown): ExtractSpec<XlsxStep, 'number'>;
+    /** Extract cell value as boolean, returning default on failure */
+    optionalBoolean(defaultValue?: unknown): ExtractSpec<XlsxStep, 'boolean'>;
+    /** Extract cell value as Date, returning default on failure */
+    optionalDate(defaultValue?: unknown): ExtractSpec<XlsxStep, 'date'>;
+    /** Extract raw cell value, returning default on failure */
+    optionalValue(defaultValue?: unknown): ExtractSpec<XlsxStep, 'value'>;
+    /** Move right by count cells (default 1) */
+    right(count?: number): XlsxCellSB;
+    /** Move left by count cells (default 1) */
+    left(count?: number): XlsxCellSB;
+    /** Move up by count cells (default 1) */
+    up(count?: number): XlsxCellSB;
+    /** Move down by count cells (default 1) */
+    down(count?: number): XlsxCellSB;
+    /** Move by row and column deltas */
+    offset(rowDelta: number, colDelta: number): XlsxCellSB;
+    /** Scan in direction until predicate matches */
+    scanTo(direction: Direction, predicate: CellPred): XlsxCellSB;
+    /** Skip cells in direction while predicate matches, land on first non-matching */
+    skipWhile(direction: Direction, predicate: CellPred): XlsxCellSB;
+    /**
+     * Iterate over cells from this position in a direction while the predicate matches.
+     * Returns an ArraySpec whose items are produced by the itemMapper.
+     * The mapper can return a Spec, a FluentSpec, or a plain record (auto-wrapped to ObjectSpec).
+     */
+    eachCell<T extends Spec>(direction: Direction, while_: CellPred, itemMapper: (cell: XlsxCellSB) => T): ArraySpec<T>;
+    eachCell(direction: Direction, while_: CellPred, itemMapper: (cell: XlsxCellSB) => Record<string, SpecLike>): ArraySpec<ObjectSpec>;
+    /**
+     * Iterate over slices (rows or columns) from this cell position.
+     * Each slice is passed as an XlsxSliceSB to the mapper, providing
+     * header-relative column/row access via colWhere/rowWhere.
+     * The mapper can return a Spec, a FluentSpec, or a plain record (auto-wrapped to ObjectSpec).
+     */
+    eachSlice<T extends Spec>(direction: Direction, while_: RowPred, itemMapper: (slice: XlsxSliceSB) => T): ArraySpec<T>;
+    eachSlice(direction: Direction, while_: RowPred, itemMapper: (slice: XlsxSliceSB) => Record<string, SpecLike>): ArraySpec<ObjectSpec>;
+}
+/**
+ * XLSX extract type for column definitions.
+ */
+export type XlsxExtractType = 'string' | 'number' | 'boolean' | 'date' | 'value' | 'formula';
+/**
+ * Column definition for XLSX `columns()` shorthand.
+ *
+ * - `CellPred` — `colWhere(header, pred).string()`
+ * - `[CellPred, XlsxExtractType]` — `colWhere(header, pred).{type}()`
+ * - `[number, XlsxExtractType?]` — `col(offset).{type ?? 'string'}()`
+ * - `SpecLike` — passthrough (any Spec or FluentSpec)
+ */
+export type XlsxColumnDef = CellPred | [CellPred, XlsxExtractType] | [number, XlsxExtractType?] | SpecLike;
+/**
+ * Spec builder for items within a slice (row or column section).
+ * Provides header-relative column/row access.
+ */
+export declare class XlsxSliceSB extends StepBuilder<XlsxStep, 'xlsx'> {
+    protected get format(): "xlsx";
+    /** @internal */
+    constructor(steps: readonly XlsxStep[]);
+    /** Access a column by matching its header cell against a predicate (header-relative) */
+    colWhere(headerRef: XlsxCellSB, predicate: CellPred): XlsxCellSB;
+    /** Access a row by matching its header cell against a predicate (header-relative, for rotated tables) */
+    rowWhere(headerRef: XlsxCellSB, predicate: CellPred): XlsxCellSB;
+    /** Access a column by 0-based offset from the anchor */
+    col(offset: number): XlsxCellSB;
+    /** Access a row by 0-based offset from the anchor (for rotated tables) */
+    row(offset: number): XlsxCellSB;
+    /**
+     * Extract multiple columns at once, producing an ObjectSpec.
+     *
+     * @example
+     * ```ts
+     * row.columns(header, {
+     *   name: cell.equals('Investment'),               // colWhere(header, pred).string()
+     *   amount: [cell.contains('Amount'), 'number'],   // colWhere(header, pred).number()
+     *   note: [2, 'string'],                            // col(2).string()
+     *   custom: fluent(row.col(0).string()).map(v => v.trim(), 'trim'),  // passthrough
+     * })
+     * ```
+     */
+    columns(headerRef: XlsxCellSB, mapping: Record<string, XlsxColumnDef>): ObjectSpec;
+    /** @internal Resolve a single column definition to a Spec */
+    private _resolveColumnDef;
+}
+/**
+ * Spec builder for items within a row (receives an XlsxRange representing one row).
+ * Provides column access to navigate within the row.
+ */
+export declare class XlsxRowItemSB extends StepBuilder<XlsxStep, 'xlsx'> {
+    protected get format(): "xlsx";
+    /** @internal */
+    constructor(steps: readonly XlsxStep[]);
+    /** Access a column by 1-based index within the row */
+    col(index: number): XlsxCellSB;
+    /** Navigate to a cell by address within the row */
+    cell(ref: string): XlsxCellSB;
+}
+/**
+ * Spec builder at the range level — cell navigation, rows, and cells collection.
+ */
+export declare class XlsxRangeSB extends StepBuilder<XlsxStep, 'xlsx'> {
+    protected get format(): "xlsx";
+    /** @internal */
+    constructor(steps: readonly XlsxStep[]);
+    /** Navigate to a cell by address within the range */
+    cell(ref: string): XlsxCellSB;
+    /** Navigate to a cell by coordinates within the range */
+    cellAt(row: number, col: number): XlsxCellSB;
+    /**
+     * Iterate over rows in the range.
+     * Each row is provided as an XlsxRowItemSB to the mapper.
+     * Returns an ArraySpec.
+     */
+    rows<T extends Spec>(itemMapper: (row: XlsxRowItemSB) => T): ArraySpec<T>;
+    /**
+     * Iterate over all cells in the range as a flat list.
+     * Each cell is provided as an XlsxCellSB to the mapper.
+     * Returns an ArraySpec.
+     */
+    cells<T extends Spec>(itemMapper: (cell: XlsxCellSB) => T): ArraySpec<T>;
+}
+/**
+ * Spec builder at the row level.
+ */
+export declare class XlsxRowSB extends StepBuilder<XlsxStep, 'xlsx'> {
+    protected get format(): "xlsx";
+    /** @internal */
+    constructor(steps: readonly XlsxStep[]);
+    /** Navigate to a cell by address within this row */
+    cell(ref: string): XlsxCellSB;
+    /** Navigate to a cell by column within this row */
+    cellAt(row: number, col: number): XlsxCellSB;
+}
+/**
+ * Spec builder at the column level.
+ */
+export declare class XlsxColSB extends StepBuilder<XlsxStep, 'xlsx'> {
+    protected get format(): "xlsx";
+    /** @internal */
+    constructor(steps: readonly XlsxStep[]);
+    /** Navigate to a cell by address within this column */
+    cell(ref: string): XlsxCellSB;
+    /** Navigate to a cell by coordinates within this column */
+    cellAt(row: number, col: number): XlsxCellSB;
+}
+/**
+ * Spec builder at the sheet level — cell, range, row, column, and search navigation.
+ */
+export declare class XlsxSheetSB extends StepBuilder<XlsxStep, 'xlsx'> {
+    protected get format(): "xlsx";
+    /** @internal */
+    constructor(steps: readonly XlsxStep[]);
+    /** Navigate to a cell by address (e.g., "A1", "B2") */
+    cell(ref: string): XlsxCellSB;
+    /** Navigate to a cell by 1-based row and column coordinates */
+    cellAt(row: number, col: number): XlsxCellSB;
+    /** Find the first cell matching the predicate */
+    find(predicate: CellPred): XlsxCellSB;
+    /** Find the first cell matching the predicate in the specified row */
+    findInRow(rowIndex: number, predicate: CellPred): XlsxCellSB;
+    /** Find the first cell matching the predicate in the specified column */
+    findInCol(colIndex: number, predicate: CellPred): XlsxCellSB;
+    /** Find the first cell matching the predicate in the specified range */
+    findInRange(rangeRef: string, predicate: CellPred): XlsxCellSB;
+    /** Navigate to a range by address (e.g., "A1:C10") */
+    range(ref: string): XlsxRangeSB;
+    /** Navigate to a range by two corner addresses */
+    range(from: string, to: string): XlsxRangeSB;
+    /** Navigate to a range defined by two dynamically resolved cells */
+    range(from: XlsxCellSB, to: XlsxCellSB): XlsxRangeSB;
+    /** Navigate to a row by 1-based index */
+    row(index: number): XlsxRowSB;
+    /** Navigate to a column by 1-based index */
+    col(index: number): XlsxColSB;
+}
+/**
+ * Spec builder for XLSX workbook — the entry point for xlsx navigation specs.
+ *
+ * Used as `$` in `emit()` after `.mapIn(parseXlsx())`.
+ */
+export declare class XlsxSpecBuilder extends StepBuilder<XlsxStep, 'xlsx'> {
+    protected get format(): "xlsx";
+    private constructor();
+    /** Create a root spec builder */
+    static root(): XlsxSpecBuilder;
+    /** Navigate to a sheet by name */
+    sheet(name: string): XlsxSheetSB;
+    /** Navigate to a sheet by 1-based index */
+    sheetAt(index: number): XlsxSheetSB;
+    /** Navigate to the first sheet */
+    firstSheet(): XlsxSheetSB;
+    /** Find a sheet matching the predicate */
+    findSheet(predicate: SheetPred): XlsxSheetSB;
+}

package/dist/xlsx-spec-executor.d.ts

@@ -0,0 +1,25 @@
+import { TYPE_LABEL, ExtractionResult, SpecScope } from '@origints/core';
+import { XlsxSpec } from './xlsx-spec';
+import { XlsxWorkbook } from './xlsx-workbook';
+import { XlsxSheet } from './xlsx-sheet';
+import { XlsxCell } from './xlsx-cell';
+/**
+ * Context wrapper for slice items.
+ * Carries workbook+sheet references so colWhere/rowWhere can resolve headers.
+ */
+export declare class XlsxSliceContext {
+    readonly workbook: XlsxWorkbook;
+    readonly sheet: XlsxSheet;
+    readonly anchorCell: XlsxCell;
+    get [TYPE_LABEL](): string;
+    constructor(workbook: XlsxWorkbook, sheet: XlsxSheet, anchorCell: XlsxCell);
+}
+/**
+ * Execute an XlsxSpec against data.
+ *
+ * The executor is polymorphic — it detects the input type:
+ * - XlsxWorkbook → starts at workbook level
+ * - XlsxRange → starts at range level (used for row items)
+ * - XlsxCell → starts at cell level (used for cell items)
+ */
+export declare function executeXlsxSpec(spec: XlsxSpec, data: unknown, scope?: SpecScope): ExtractionResult<unknown>;

package/dist/xlsx-spec.d.ts

@@ -0,0 +1,121 @@
+import { ExtractSpec, Spec } from '@origints/core';
+import { CellPredicateSpec, SheetPredicateSpec, RowPredicateSpec } from './xlsx-predicate-spec';
+/**
+ * Direction for cell navigation.
+ */
+export type Direction = 'right' | 'left' | 'up' | 'down';
+/**
+ * A single navigation step through an XLSX workbook.
+ */
+export type XlsxStep = {
+    readonly kind: 'sheet';
+    readonly name: string;
+} | {
+    readonly kind: 'sheetAt';
+    readonly index: number;
+} | {
+    readonly kind: 'firstSheet';
+} | {
+    readonly kind: 'findSheet';
+    readonly predicate: SheetPredicateSpec;
+} | {
+    readonly kind: 'find';
+    readonly predicate: CellPredicateSpec;
+} | {
+    readonly kind: 'findInRow';
+    readonly rowIndex: number;
+    readonly predicate: CellPredicateSpec;
+} | {
+    readonly kind: 'findInCol';
+    readonly colIndex: number;
+    readonly predicate: CellPredicateSpec;
+} | {
+    readonly kind: 'findInRange';
+    readonly rangeRef: string;
+    readonly predicate: CellPredicateSpec;
+} | {
+    readonly kind: 'cell';
+    readonly ref: string;
+} | {
+    readonly kind: 'cellAt';
+    readonly row: number;
+    readonly col: number;
+} | {
+    readonly kind: 'right';
+    readonly count: number;
+} | {
+    readonly kind: 'left';
+    readonly count: number;
+} | {
+    readonly kind: 'up';
+    readonly count: number;
+} | {
+    readonly kind: 'down';
+    readonly count: number;
+} | {
+    readonly kind: 'offset';
+    readonly rowDelta: number;
+    readonly colDelta: number;
+} | {
+    readonly kind: 'scanTo';
+    readonly direction: Direction;
+    readonly predicate: CellPredicateSpec;
+} | {
+    readonly kind: 'skipWhile';
+    readonly direction: Direction;
+    readonly predicate: CellPredicateSpec;
+} | {
+    readonly kind: 'colWhere';
+    readonly headerRef: Spec;
+    readonly predicate: CellPredicateSpec;
+} | {
+    readonly kind: 'rowWhere';
+    readonly headerRef: Spec;
+    readonly predicate: CellPredicateSpec;
+} | {
+    readonly kind: 'range';
+    readonly ref: string;
+} | {
+    readonly kind: 'rangeFromCells';
+    readonly from: Spec;
+    readonly to: Spec;
+} | {
+    readonly kind: 'row';
+    readonly index: number;
+} | {
+    readonly kind: 'col';
+    readonly index: number;
+};
+/**
+ * Specification for iterating over cells in a direction while a predicate matches.
+ */
+export interface EachCellExtract {
+    readonly kind: 'eachCell';
+    readonly direction: Direction;
+    readonly while: CellPredicateSpec;
+}
+/**
+ * Specification for iterating over slices (rows or columns) in a direction
+ * while a row-level predicate matches. Each slice is an anchor cell
+ * wrapped in XlsxSliceContext for header-relative navigation.
+ */
+export interface EachSliceExtract {
+    readonly kind: 'eachSlice';
+    readonly direction: Direction;
+    readonly while: RowPredicateSpec;
+}
+/**
+ * The terminal extraction type for an XLSX value.
+ *
+ * - Cell-level: 'string', 'number', 'boolean', 'date', 'value', 'formula'
+ * - Range-level (produce arrays): 'rows', 'cells'
+ * - Cell-level (produce arrays): EachCellExtract, EachSliceExtract
+ */
+export type XlsxExtract = 'string' | 'number' | 'boolean' | 'date' | 'value' | 'formula' | 'rows' | 'cells' | EachCellExtract | EachSliceExtract;
+/**
+ * A complete XLSX extraction spec.
+ *
+ * Describes a path through the workbook (steps) and what to extract (extract).
+ * JSON-serializable and suitable for AST introspection.
+ */
+export type XlsxSpec = ExtractSpec<XlsxStep, XlsxExtract>;

package/dist/xlsx-workbook.d.ts

@@ -1,4 +1,4 @@
-import { Workbook } from 'exceljs';
+import { TYPE_LABEL } from '@origints/core';
 import { XlsxSheet } from './xlsx-sheet';
 import { XlsxResult, XlsxPath } from './xlsx-result';
 /**
@@ -17,21 +17,23 @@ export interface WorkbookProperties {
     readonly modified?: Date;
 }
 /**
- * A wrapper around ExcelJS Workbook with navigation and query capabilities.
+ * A wrapper around workbook data with navigation and query capabilities.
  *
  * XlsxWorkbook provides access to sheets, workbook properties, and
  * supports predicate-based queries for finding sheets.
  */
 export declare class XlsxWorkbook {
-    private readonly workbook;
     private readonly _path;
-    private readonly sheetsCache;
+    get [TYPE_LABEL](): string;
+    private readonly _sheets;
+    private readonly _sheetsByName;
+    private readonly _props;
     private constructor();
     /**
-     * Creates an XlsxWorkbook from an ExcelJS workbook.
+     * Creates an XlsxWorkbook from internal data.
      * @internal
      */
-    static fromExcelJS(workbook: Workbook, file?: string): XlsxWorkbook;
+    static create(sheets: XlsxSheet[], props: WorkbookProperties, file?: string): XlsxWorkbook;
     /**
      * Returns the path for lineage tracking.
      */
@@ -120,9 +122,4 @@ export declare class XlsxWorkbook {
      * Map over all sheets.
      */
     map<T>(fn: (sheet: XlsxSheet, index: number) => T): T[];
-    /**
-     * Get the underlying ExcelJS workbook.
-     * @internal
-     */
-    getWorkbook(): Workbook;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@origints/xlsx",
-  "version": "0.1.1",
+  "version": "0.3.2",
   "description": "XLSX parsing for Origins with full traceability to sheets, ranges, and cells.",
   "type": "module",
   "license": "MIT",
@@ -27,14 +27,34 @@
     "lint": "eslint \"{src,tests}/**/*.{ts,tsx}\" --max-warnings 0",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fponticelli/origints.git",
+    "directory": "packages/xlsx"
+  },
+  "homepage": "https://origints.dev",
+  "bugs": "https://github.com/fponticelli/origints/issues",
+  "keywords": [
+    "origints",
+    "data-extraction",
+    "lineage",
+    "provenance",
+    "xlsx",
+    "excel",
+    "spreadsheet"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
   "dependencies": {
-    "exceljs": "^4.4.0"
+    "xlsx": "^0.18.5"
   },
   "peerDependencies": {
-    "@origints/core": "^0.1.0"
+    "@origints/core": "^0.3.0"
   },
   "devDependencies": {
     "@origints/core": "workspace:*",
+    "exceljs": "^4.4.0",
     "@types/node": "25.0.6",
     "@vitest/coverage-v8": "^4.0.16",
     "eslint": "9.39.2",