@origints/xlsx 0.1.1 → 0.3.2

package/dist/parse.d.ts

@@ -1,4 +1,5 @@
 import { XlsxWorkbook } from './xlsx-workbook';
+import { XlsxSpecBuilder } from './xlsx-spec-builder';
 /**
  * Transform AST specification.
  * Compatible with @origints/core TransformAst.
@@ -9,6 +10,14 @@ export interface TransformAst {
     readonly name: string;
     readonly args?: unknown;
 }
+/**
+ * Typed transform AST with spec builder type parameter.
+ * Compatible with @origints/core TypedTransformAst.
+ */
+export interface TypedTransformAst<SB = unknown> extends TransformAst {
+    readonly __specBuilder?: SB;
+    readonly specBuilderFactory: () => SB;
+}
 /**
  * Transform implementation.
  * Compatible with @origints/core TransformImpl.
@@ -59,12 +68,12 @@ export interface XlsxParseOptions {
  *   .in(loadFile('data.xlsx'))
  *   .mapIn(parseXlsx())
  *   .emit((out, $) => out
- *     .add('revenue', $.sheet('Sales').cell('B2').number())
+ *     .add('revenue', $.get('Sales').get('B2').number())
  *   )
  *   .compile()
  * ```
  */
-export declare function parseXlsx(options?: XlsxParseOptions): TransformAst;
+export declare function parseXlsx(options?: XlsxParseOptions): TypedTransformAst<XlsxSpecBuilder>;
 /**
  * Sync transform implementation for parseXlsx.
  * Note: XLSX parsing requires async due to file reading.

package/dist/xlsx-cell.d.ts

@@ -1,5 +1,78 @@
-import { Cell as ExcelJSCell } from 'exceljs';
+import { TYPE_LABEL } from '@origints/core';
 import { XlsxResult, XlsxPath, CellValue, ExtendedCellValue } from './xlsx-result';
+/**
+ * Internal cell data — parser-agnostic representation.
+ * Created by the parser (SheetJS) and consumed by XlsxCell.
+ */
+export interface CellData {
+    readonly address: string;
+    readonly row: number;
+    readonly col: number;
+    /** Resolved value (formula result or plain value). */
+    readonly resolvedValue: CellValue;
+    /** Formula string, if this cell contains a formula. */
+    readonly formula?: string;
+    /** Error string, if this cell contains an error. */
+    readonly error?: string;
+    /** Hyperlink URL. */
+    readonly hyperlink?: string;
+    /** Comment/note text. */
+    readonly comment?: string;
+    /** Number format string. */
+    readonly numFmt?: string;
+    /** Whether this cell is part of a merged range. */
+    readonly isMerged: boolean;
+    /** Address of the master cell if this is a non-master merged cell. */
+    readonly masterAddress?: string;
+    /** Rich text segments (when available from the parser). */
+    readonly richText?: ReadonlyArray<RichTextSegmentData>;
+    /** Cell style data (best-effort, may not be available with all parsers). */
+    readonly style?: CellStyleData;
+}
+/** Rich text segment from the parser. */
+export interface RichTextSegmentData {
+    readonly text: string;
+    readonly bold?: boolean;
+    readonly italic?: boolean;
+    readonly underline?: boolean;
+    readonly strike?: boolean;
+    readonly color?: string;
+    readonly size?: number;
+    readonly font?: string;
+}
+/** Cell style from the parser. */
+export interface CellStyleData {
+    readonly font?: {
+        readonly name?: string;
+        readonly size?: number;
+        readonly bold?: boolean;
+        readonly italic?: boolean;
+        readonly underline?: boolean;
+        readonly strike?: boolean;
+        readonly color?: {
+            readonly argb?: string;
+            readonly theme?: number;
+        };
+    };
+    readonly fill?: {
+        readonly type?: string;
+        readonly pattern?: string;
+        readonly fgColor?: {
+            readonly argb?: string;
+        };
+    };
+    readonly border?: {
+        readonly top?: boolean;
+        readonly bottom?: boolean;
+        readonly left?: boolean;
+        readonly right?: boolean;
+    };
+    readonly alignment?: {
+        readonly horizontal?: string;
+        readonly vertical?: string;
+        readonly wrapText?: boolean;
+    };
+}
 /**
  * Cell style information.
  */
@@ -51,22 +124,28 @@ export interface RichTextContent {
     readonly hyperlink?: string;
 }
 /**
- * A wrapper around ExcelJS Cell with full metadata preservation.
+ * A wrapper around cell data with full metadata preservation.
  *
  * XlsxCell enables typed extraction of cell values while maintaining
  * provenance information. Each cell knows its exact location in the
  * workbook, allowing full traceability.
  */
 export declare class XlsxCell {
-    private readonly cell;
+    private readonly _data;
     private readonly _path;
     private readonly _sheetName;
+    get [TYPE_LABEL](): string;
     private constructor();
     /**
-     * Creates an XlsxCell from an ExcelJS cell.
+     * Creates an XlsxCell from internal cell data.
      * @internal
      */
-    static fromExcelJS(cell: ExcelJSCell, sheetName: string, file?: string): XlsxCell;
+    static create(data: CellData, sheetName: string, file?: string): XlsxCell;
+    /**
+     * Creates an empty cell for the given coordinates.
+     * @internal
+     */
+    static empty(row: number, col: number, sheetName: string, file?: string): XlsxCell;
     /**
      * Returns the cell address (e.g., "A1").
      */
@@ -121,18 +200,10 @@ export declare class XlsxCell {
     formula(): XlsxResult<string>;
     /**
      * Get the cell content as rich text with formatting preserved.
-     * Returns segments with their individual formatting properties.
      */
     richText(): XlsxResult<RichTextContent>;
     /**
      * Get the cell content as Markdown.
-     *
-     * Converts cell content including:
-     * - Bold text -> **text**
-     * - Italic text -> *text*
-     * - Strikethrough -> ~~text~~
-     * - Hyperlinks -> [text](url)
-     * - Rich text segments with mixed formatting
      */
     markdown(): XlsxResult<string>;
     /**
@@ -193,17 +264,13 @@ export declare class XlsxCell {
      */
     getOffsetCell(rowDelta: number, colDelta: number, getCell: (row: number, col: number) => XlsxCell | undefined): XlsxResult<XlsxCell>;
     /**
-     * Get the raw value, handling ExcelJS value types.
+     * Get the raw value, handling formula/error types.
      */
     private getRawValue;
     /**
      * Get the resolved value (formula result or plain value).
      */
     private getResolvedValue;
-    /**
-     * Normalize a formula result value.
-     */
-    private normalizeResult;
     /**
      * Convert Excel date number to JavaScript Date.
      * Excel dates are days since 1900-01-01 (with a leap year bug).

package/dist/xlsx-cursor.d.ts

@@ -1,3 +1,4 @@
+import { TYPE_LABEL } from '@origints/core';
 import { XlsxSheet } from './xlsx-sheet';
 import { XlsxCell } from './xlsx-cell';
 import { XlsxResult, XlsxPath } from './xlsx-result';
@@ -33,6 +34,7 @@ export declare class XlsxCursor {
     private readonly _row;
     private readonly _col;
     private readonly _direction;
+    get [TYPE_LABEL](): string;
     private constructor();
     /**
      * Create a cursor from an address string.

package/dist/xlsx-predicate-compiler.d.ts

@@ -0,0 +1,24 @@
+import { SpecScope } from '@origints/core';
+import { XlsxSheet } from './xlsx-sheet';
+import { CellPredicate } from './xlsx-query';
+import { SheetPredicate } from './xlsx-workbook';
+import { CellPredicateSpec, SheetPredicateSpec, RowPredicateSpec } from './xlsx-predicate-spec';
+/**
+ * Compile a CellPredicateSpec AST into a runtime CellPredicate closure.
+ *
+ * @param spec - The predicate spec to compile
+ * @param scope - Optional scope for variable reference predicates (equalsRef, containsRef)
+ */
+export declare function compileCellPredicate(spec: CellPredicateSpec, scope?: SpecScope): CellPredicate;
+/**
+ * Compile a SheetPredicateSpec AST into a runtime SheetPredicate closure.
+ */
+export declare function compileSheetPredicate(spec: SheetPredicateSpec): SheetPredicate;
+export type RowPredicate = (sheet: XlsxSheet, row: number, anchorCol: number) => boolean;
+/**
+ * Compile a RowPredicateSpec AST into a runtime RowPredicate closure.
+ *
+ * @param spec - The row predicate spec to compile
+ * @param scope - Optional scope for variable reference predicates
+ */
+export declare function compileRowPredicate(spec: RowPredicateSpec, scope?: SpecScope): RowPredicate;

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

@@ -0,0 +1,211 @@
+import { PredicateWrapper } from '@origints/core';
+import { CellValue } from './xlsx-result';
+export type CellPredicateSpec = {
+    readonly kind: 'equals';
+    readonly value: CellValue;
+} | {
+    readonly kind: 'contains';
+    readonly text: string;
+    readonly caseSensitive: boolean;
+} | {
+    readonly kind: 'matches';
+    readonly pattern: string;
+    readonly flags: string;
+} | {
+    readonly kind: 'startsWith';
+    readonly prefix: string;
+    readonly caseSensitive: boolean;
+} | {
+    readonly kind: 'endsWith';
+    readonly suffix: string;
+    readonly caseSensitive: boolean;
+} | {
+    readonly kind: 'isString';
+} | {
+    readonly kind: 'isNumber';
+} | {
+    readonly kind: 'isBoolean';
+} | {
+    readonly kind: 'isDate';
+} | {
+    readonly kind: 'isEmpty';
+} | {
+    readonly kind: 'isNotEmpty';
+} | {
+    readonly kind: 'isFormula';
+} | {
+    readonly kind: 'isError';
+} | {
+    readonly kind: 'isMerged';
+} | {
+    readonly kind: 'gt';
+    readonly value: number;
+} | {
+    readonly kind: 'gte';
+    readonly value: number;
+} | {
+    readonly kind: 'lt';
+    readonly value: number;
+} | {
+    readonly kind: 'lte';
+    readonly value: number;
+} | {
+    readonly kind: 'between';
+    readonly min: number;
+    readonly max: number;
+} | {
+    readonly kind: 'isBold';
+} | {
+    readonly kind: 'isItalic';
+} | {
+    readonly kind: 'hasHyperlink';
+} | {
+    readonly kind: 'hasComment';
+} | {
+    readonly kind: 'equalsRef';
+    readonly ref: string;
+    readonly path?: readonly (string | number)[];
+} | {
+    readonly kind: 'containsRef';
+    readonly ref: string;
+    readonly path?: readonly (string | number)[];
+    readonly caseSensitive: boolean;
+} | {
+    readonly kind: 'startsWithRef';
+    readonly ref: string;
+    readonly path?: readonly (string | number)[];
+    readonly caseSensitive: boolean;
+} | {
+    readonly kind: 'and';
+    readonly left: CellPredicateSpec;
+    readonly right: CellPredicateSpec;
+} | {
+    readonly kind: 'or';
+    readonly left: CellPredicateSpec;
+    readonly right: CellPredicateSpec;
+} | {
+    readonly kind: 'not';
+    readonly operand: CellPredicateSpec;
+};
+export type SheetPredicateSpec = {
+    readonly kind: 'nameEquals';
+    readonly name: string;
+} | {
+    readonly kind: 'nameContains';
+    readonly text: string;
+} | {
+    readonly kind: 'nameStartsWith';
+    readonly prefix: string;
+} | {
+    readonly kind: 'nameEndsWith';
+    readonly suffix: string;
+} | {
+    readonly kind: 'nameMatches';
+    readonly pattern: string;
+    readonly flags: string;
+} | {
+    readonly kind: 'and';
+    readonly left: SheetPredicateSpec;
+    readonly right: SheetPredicateSpec;
+} | {
+    readonly kind: 'or';
+    readonly left: SheetPredicateSpec;
+    readonly right: SheetPredicateSpec;
+} | {
+    readonly kind: 'not';
+    readonly operand: SheetPredicateSpec;
+};
+export type CellPred = PredicateWrapper<CellPredicateSpec>;
+export type SheetPred = PredicateWrapper<SheetPredicateSpec>;
+export declare const cell: Readonly<{
+    equals: (value: CellValue) => CellPred;
+    contains: (text: string, caseSensitive?: boolean) => CellPred;
+    matches: (pattern: RegExp) => CellPred;
+    startsWith: (prefix: string, caseSensitive?: boolean) => CellPred;
+    endsWith: (suffix: string, caseSensitive?: boolean) => CellPred;
+    isString: () => CellPred;
+    isNumber: () => CellPred;
+    isBoolean: () => CellPred;
+    isDate: () => CellPred;
+    isEmpty: () => CellPred;
+    isNotEmpty: () => CellPred;
+    isFormula: () => CellPred;
+    isError: () => CellPred;
+    isMerged: () => CellPred;
+    gt: (value: number) => CellPred;
+    gte: (value: number) => CellPred;
+    lt: (value: number) => CellPred;
+    lte: (value: number) => CellPred;
+    between: (min: number, max: number) => CellPred;
+    isBold: () => CellPred;
+    isItalic: () => CellPred;
+    hasHyperlink: () => CellPred;
+    hasComment: () => CellPred;
+    /**
+     * Match when cell value equals a bound variable from ForEachSpec scope.
+     *
+     * @example
+     * ```ts
+     * forEach(
+     *   $.get('companies').strings(),
+     *   'company',
+     *   xlsxSB.firstSheet().find(cell.equalsRef('company')).string()
+     * )
+     * ```
+     */
+    equalsRef: (ref: string, path?: readonly (string | number)[]) => CellPred;
+    /**
+     * Match when cell string value contains a bound variable from ForEachSpec scope.
+     *
+     * @example
+     * ```ts
+     * forEach(
+     *   $.get('keywords').strings(),
+     *   'keyword',
+     *   xlsxSB.firstSheet().find(cell.containsRef('keyword')).string()
+     * )
+     * ```
+     */
+    containsRef: (ref: string, path?: readonly (string | number)[], caseSensitive?: boolean) => CellPred;
+    /**
+     * Match when cell string value starts with a bound variable from ForEachSpec scope.
+     *
+     * @example
+     * ```ts
+     * forEach(
+     *   $.get('companies').strings(),
+     *   'company',
+     *   xlsxSB.firstSheet().find(cell.startsWithRef('company')).string()
+     * )
+     * ```
+     */
+    startsWithRef: (ref: string, path?: readonly (string | number)[], caseSensitive?: boolean) => CellPred;
+}>;
+export declare const sheet: Readonly<{
+    nameEquals: (name: string) => SheetPred;
+    nameContains: (text: string) => SheetPred;
+    nameStartsWith: (prefix: string) => SheetPred;
+    nameEndsWith: (suffix: string) => SheetPred;
+    nameMatches: (pattern: RegExp) => SheetPred;
+}>;
+export declare function describeCellPredicate(spec: CellPredicateSpec): string;
+export type RowPredicateSpec = {
+    readonly kind: 'rowCol';
+    readonly offset: number;
+    readonly predicate: CellPredicateSpec;
+} | {
+    readonly kind: 'and';
+    readonly left: RowPredicateSpec;
+    readonly right: RowPredicateSpec;
+} | {
+    readonly kind: 'or';
+    readonly left: RowPredicateSpec;
+    readonly right: RowPredicateSpec;
+} | {
+    readonly kind: 'not';
+    readonly operand: RowPredicateSpec;
+};
+export type RowPred = PredicateWrapper<RowPredicateSpec>;
+export declare function rowCol(offset: number, predicate: CellPred): RowPred;
+export declare function describeRowPredicate(spec: RowPredicateSpec): string;
+export declare function describeSheetPredicate(spec: SheetPredicateSpec): string;

package/dist/xlsx-range.d.ts

@@ -1,7 +1,12 @@
-import { Worksheet } from 'exceljs';
+import { TYPE_LABEL } from '@origints/core';
 import { XlsxCell } from './xlsx-cell';
 import { XlsxResult, XlsxPath, CellValue } from './xlsx-result';
 import { CellPredicate } from './xlsx-query';
+/**
+ * Cell accessor function — resolves a cell by 1-based row/col.
+ * Provided by XlsxSheet so XlsxRange is decoupled from sheet internals.
+ */
+export type CellAccessor = (row: number, col: number) => XlsxResult<XlsxCell>;
 /**
  * A range of cells in an XLSX sheet.
  *
@@ -10,7 +15,7 @@ import { CellPredicate } from './xlsx-query';
  * and conversion to various formats.
  */
 export declare class XlsxRange {
-    private readonly worksheet;
+    private readonly _getCell;
     private readonly _startRow;
     private readonly _startCol;
     private readonly _endRow;
@@ -18,17 +23,18 @@ export declare class XlsxRange {
     private readonly _path;
     private readonly _sheetName;
     private readonly _file?;
+    get [TYPE_LABEL](): string;
     private constructor();
     /**
      * Creates an XlsxRange from coordinates.
      * @internal
      */
-    static fromCoords(worksheet: Worksheet, startRow: number, startCol: number, endRow: number, endCol: number, sheetName: string, file?: string): XlsxRange;
+    static fromCoords(getCell: CellAccessor, startRow: number, startCol: number, endRow: number, endCol: number, sheetName: string, file?: string): XlsxRange;
     /**
      * Creates an XlsxRange from an address string.
      * @internal
      */
-    static fromAddress(worksheet: Worksheet, address: string, sheetName: string, file?: string): XlsxResult<XlsxRange>;
+    static fromAddress(getCell: CellAccessor, address: string, sheetName: string, file?: string): XlsxResult<XlsxRange>;
     /**
      * Returns the range address (e.g., "A1:C10").
      */

package/dist/xlsx-sheet.d.ts

@@ -1,9 +1,9 @@
-import { Worksheet } from 'exceljs';
-import { XlsxCell } from './xlsx-cell';
+import { TYPE_LABEL } from '@origints/core';
+import { CellData, XlsxCell } from './xlsx-cell';
 import { XlsxRange } from './xlsx-range';
-import { XlsxCursor } from './xlsx-cursor';
-import { XlsxResult, XlsxPath, CellValue } from './xlsx-result';
+import { XlsxResult, XlsxPath } from './xlsx-result';
 import { CellPredicate } from './xlsx-query';
+import { XlsxCursor } from './xlsx-cursor';
 /**
  * Dimensions of a sheet's used range.
  */
@@ -16,22 +16,30 @@ export interface SheetDimensions {
     readonly colCount: number;
 }
 /**
- * A wrapper around ExcelJS Worksheet with navigation and query capabilities.
+ * A wrapper around sheet data with navigation and query capabilities.
  *
  * XlsxSheet provides a rich API for navigating cells, ranges, and rows
  * within a worksheet. It supports predicate-based queries and cursor-based
  * navigation for complex data extraction scenarios.
  */
 export declare class XlsxSheet {
-    private readonly worksheet;
+    get [TYPE_LABEL](): string;
+    /** Cell data from the parser — keyed by row*16384+col. */
+    private readonly _cells;
+    /** Cache for XlsxCell wrappers — avoids repeated creation. */
+    private readonly _cellCache;
+    private readonly _dims;
+    private readonly _name;
+    private readonly _index;
+    private readonly _mergeRanges;
     private readonly _path;
     private readonly _file?;
     private constructor();
     /**
-     * Creates an XlsxSheet from an ExcelJS worksheet.
+     * Creates an XlsxSheet from internal data.
      * @internal
      */
-    static fromExcelJS(worksheet: Worksheet, file?: string): XlsxSheet;
+    static create(cells: Map<number, CellData>, dims: SheetDimensions, name: string, index: number, mergeRanges: string[], file?: string): XlsxSheet;
     /**
      * Returns the sheet name.
      */
@@ -55,7 +63,7 @@ export declare class XlsxSheet {
     /**
      * Get the value of a cell directly.
      */
-    getValue(address: string): XlsxResult<CellValue>;
+    getValue(address: string): XlsxResult<import('./xlsx-result').CellValue>;
     /**
      * Get a range by its address (e.g., "A1:C10").
      */
@@ -107,7 +115,7 @@ export declare class XlsxSheet {
     /**
      * Find the first cell with the specified value.
      */
-    findValue(value: CellValue): XlsxResult<XlsxCell>;
+    findValue(value: import('./xlsx-result').CellValue): XlsxResult<XlsxCell>;
     /**
      * Find cells within a specific range matching the predicate.
      */
@@ -136,11 +144,6 @@ export declare class XlsxSheet {
      * Check if a cell is part of a merged range.
      */
     isMerged(address: string): boolean;
-    /**
-     * Get the underlying ExcelJS worksheet.
-     * @internal
-     */
-    getWorksheet(): Worksheet;
     /**
      * Get a cell by coordinates for internal use.
      * @internal