@origints/xlsx 0.1.0

package/dist/xlsx-range.d.ts

@@ -0,0 +1,166 @@
+import { Worksheet } from 'exceljs';
+import { XlsxCell } from './xlsx-cell';
+import { XlsxResult, XlsxPath, CellValue } from './xlsx-result';
+import { CellPredicate } from './xlsx-query';
+/**
+ * A range of cells in an XLSX sheet.
+ *
+ * XlsxRange enables iteration over cells, rows, and columns within
+ * a defined rectangular region. It supports predicate-based queries
+ * and conversion to various formats.
+ */
+export declare class XlsxRange {
+    private readonly worksheet;
+    private readonly _startRow;
+    private readonly _startCol;
+    private readonly _endRow;
+    private readonly _endCol;
+    private readonly _path;
+    private readonly _sheetName;
+    private readonly _file?;
+    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;
+    /**
+     * Creates an XlsxRange from an address string.
+     * @internal
+     */
+    static fromAddress(worksheet: Worksheet, address: string, sheetName: string, file?: string): XlsxResult<XlsxRange>;
+    /**
+     * Returns the range address (e.g., "A1:C10").
+     */
+    get address(): string;
+    /**
+     * Returns the start row (1-based).
+     */
+    get startRow(): number;
+    /**
+     * Returns the start column (1-based).
+     */
+    get startCol(): number;
+    /**
+     * Returns the end row (1-based).
+     */
+    get endRow(): number;
+    /**
+     * Returns the end column (1-based).
+     */
+    get endCol(): number;
+    /**
+     * Returns the current path for lineage tracking.
+     */
+    get path(): XlsxPath;
+    /**
+     * Returns the number of rows in the range.
+     */
+    get rowCount(): number;
+    /**
+     * Returns the number of columns in the range.
+     */
+    get colCount(): number;
+    /**
+     * Returns the total number of cells in the range.
+     */
+    get cellCount(): number;
+    /**
+     * Get a cell at specific row and column within this range.
+     * Coordinates are relative to the range start (0-indexed).
+     */
+    cellAt(rowOffset: number, colOffset: number): XlsxResult<XlsxCell>;
+    /**
+     * Get a cell by its address within this range.
+     */
+    cell(address: string): XlsxResult<XlsxCell>;
+    /**
+     * Iterate over all cells in the range (row by row).
+     */
+    cells(): Iterable<XlsxCell>;
+    /**
+     * Iterate over rows, returning arrays of cells.
+     */
+    rows(): Iterable<XlsxCell[]>;
+    /**
+     * Iterate over columns, returning arrays of cells.
+     */
+    cols(): Iterable<XlsxCell[]>;
+    /**
+     * Get all values in the range as a 2D array.
+     */
+    values(): CellValue[][];
+    /**
+     * Get all cells as a flat array.
+     */
+    cellsArray(): XlsxCell[];
+    /**
+     * Get a subrange within this range.
+     */
+    subRange(address: string): XlsxResult<XlsxRange>;
+    /**
+     * Get the first row as a range.
+     */
+    firstRow(): XlsxRange;
+    /**
+     * Get the last row as a range.
+     */
+    lastRow(): XlsxRange;
+    /**
+     * Get the first column as a range.
+     */
+    firstCol(): XlsxRange;
+    /**
+     * Get the last column as a range.
+     */
+    lastCol(): XlsxRange;
+    /**
+     * Get a specific row as a range (0-indexed offset from start).
+     */
+    rowAt(offset: number): XlsxResult<XlsxRange>;
+    /**
+     * Get a specific column as a range (0-indexed offset from start).
+     */
+    colAt(offset: number): XlsxResult<XlsxRange>;
+    /**
+     * Find the first cell matching the predicate.
+     */
+    find(predicate: CellPredicate): XlsxResult<XlsxCell>;
+    /**
+     * Find all cells matching the predicate.
+     */
+    findAll(predicate: CellPredicate): XlsxCell[];
+    /**
+     * Find the first cell with the specified value.
+     */
+    findValue(value: CellValue): XlsxResult<XlsxCell>;
+    /**
+     * Check if any cell matches the predicate.
+     */
+    some(predicate: CellPredicate): boolean;
+    /**
+     * Check if all cells match the predicate.
+     */
+    every(predicate: CellPredicate): boolean;
+    /**
+     * Count cells matching the predicate.
+     */
+    count(predicate: CellPredicate): number;
+    /**
+     * Convert range to a 2D array of values.
+     */
+    toArray(): CellValue[][];
+    /**
+     * Convert range to array of objects using a header row.
+     * @param headerRowOffset - Row offset for headers (default: 0, first row)
+     * @param dataStartOffset - Row offset where data starts (default: 1, second row)
+     */
+    toObjects(headerRowOffset?: number, dataStartOffset?: number): Record<string, CellValue>[];
+    /**
+     * Convert range to JSON-compatible structure.
+     */
+    toJson(): {
+        address: string;
+        rows: Array<Array<CellValue>>;
+    };
+}

package/dist/xlsx-result.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Result types for XLSX operations.
+ *
+ * @module xlsx/xlsx-result
+ */
+/**
+ * Excel source location for lineage tracking.
+ * Compatible with @origints/core ExcelLocation.
+ */
+export interface ExcelLocation {
+    readonly kind: 'excel';
+    readonly file: string;
+    readonly sheet: string;
+    readonly range: string;
+}
+/**
+ * Path through an XLSX structure, tracking how we arrived at a value.
+ */
+export interface XlsxPath {
+    /** Source file name (if known) */
+    readonly file?: string;
+    /** Sheet name */
+    readonly sheet?: string;
+    /** Cell address (e.g., "A1") */
+    readonly cell?: string;
+    /** Range address (e.g., "A1:C10") */
+    readonly range?: string;
+}
+/**
+ * Failure kinds specific to XLSX operations.
+ */
+export type XlsxFailureKind = 'parse' | 'type' | 'missing' | 'range' | 'format' | 'bounds' | 'merged' | 'formula';
+/**
+ * A failure during XLSX traversal or extraction.
+ */
+export interface XlsxFailure {
+    readonly kind: XlsxFailureKind;
+    readonly message: string;
+    readonly path: XlsxPath;
+    readonly sourceLocation?: ExcelLocation;
+}
+/**
+ * Result of an XLSX extraction - either a successful value or a failure.
+ */
+export type XlsxResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+    readonly path: XlsxPath;
+} | {
+    readonly ok: false;
+    readonly failure: XlsxFailure;
+};
+/**
+ * Creates a success result.
+ */
+export declare function ok<T>(value: T, path: XlsxPath): XlsxResult<T>;
+/**
+ * Creates a failure result.
+ */
+export declare function fail(kind: XlsxFailureKind, message: string, path: XlsxPath, sourceLocation?: ExcelLocation): XlsxResult<never>;
+/**
+ * Formats a path for display.
+ */
+export declare function formatXlsxPath(path: XlsxPath): string;
+/**
+ * Creates an ExcelLocation from a path.
+ */
+export declare function toExcelLocation(path: XlsxPath): ExcelLocation | undefined;
+/**
+ * Cell value types in XLSX.
+ */
+export type CellValue = string | number | boolean | Date | null;
+/**
+ * Extended cell value including formula and error types.
+ */
+export type ExtendedCellValue = CellValue | {
+    readonly formula: string;
+    readonly result?: CellValue;
+} | {
+    readonly error: string;
+};
+/**
+ * Type guard for formula values.
+ */
+export declare function isFormula(value: ExtendedCellValue): value is {
+    formula: string;
+    result?: CellValue;
+};
+/**
+ * Type guard for error values.
+ */
+export declare function isError(value: ExtendedCellValue): value is {
+    error: string;
+};

package/dist/xlsx-sheet.d.ts

@@ -0,0 +1,149 @@
+import { Worksheet } from 'exceljs';
+import { XlsxCell } from './xlsx-cell';
+import { XlsxRange } from './xlsx-range';
+import { XlsxCursor } from './xlsx-cursor';
+import { XlsxResult, XlsxPath, CellValue } from './xlsx-result';
+import { CellPredicate } from './xlsx-query';
+/**
+ * Dimensions of a sheet's used range.
+ */
+export interface SheetDimensions {
+    readonly startRow: number;
+    readonly endRow: number;
+    readonly startCol: number;
+    readonly endCol: number;
+    readonly rowCount: number;
+    readonly colCount: number;
+}
+/**
+ * A wrapper around ExcelJS Worksheet 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;
+    private readonly _path;
+    private readonly _file?;
+    private constructor();
+    /**
+     * Creates an XlsxSheet from an ExcelJS worksheet.
+     * @internal
+     */
+    static fromExcelJS(worksheet: Worksheet, file?: string): XlsxSheet;
+    /**
+     * Returns the sheet name.
+     */
+    get name(): string;
+    /**
+     * Returns the sheet index (1-based).
+     */
+    get index(): number;
+    /**
+     * Returns the current path for lineage tracking.
+     */
+    get path(): XlsxPath;
+    /**
+     * Get a cell by its address (e.g., "A1", "B2").
+     */
+    cell(address: string): XlsxResult<XlsxCell>;
+    /**
+     * Get a cell by row and column numbers (1-based).
+     */
+    cellAt(row: number, col: number): XlsxResult<XlsxCell>;
+    /**
+     * Get the value of a cell directly.
+     */
+    getValue(address: string): XlsxResult<CellValue>;
+    /**
+     * Get a range by its address (e.g., "A1:C10").
+     */
+    range(address: string): XlsxResult<XlsxRange>;
+    /**
+     * Get a range from start to end addresses.
+     */
+    rangeFrom(start: string, end: string): XlsxResult<XlsxRange>;
+    /**
+     * Get a range by coordinates (1-based).
+     */
+    rangeAt(startRow: number, startCol: number, endRow: number, endCol: number): XlsxResult<XlsxRange>;
+    /**
+     * Get the used range of the sheet (cells with data).
+     */
+    usedRange(): XlsxResult<XlsxRange>;
+    /**
+     * Get a row as a range.
+     */
+    row(rowNum: number): XlsxResult<XlsxRange>;
+    /**
+     * Get a column as a range.
+     */
+    col(colId: string | number): XlsxResult<XlsxRange>;
+    /**
+     * Iterate over all rows with data.
+     */
+    rows(): Iterable<XlsxRange>;
+    /**
+     * Iterate over all columns with data.
+     */
+    cols(): Iterable<XlsxRange>;
+    /**
+     * Create a cursor starting at the specified address.
+     */
+    cursor(startAddress?: string): XlsxCursor;
+    /**
+     * Create a cursor starting at the specified coordinates (1-based).
+     */
+    cursorAt(row: number, col: number): XlsxCursor;
+    /**
+     * Find the first cell matching the predicate.
+     */
+    find(predicate: CellPredicate): XlsxResult<XlsxCell>;
+    /**
+     * Find all cells matching the predicate.
+     */
+    findAll(predicate: CellPredicate): XlsxCell[];
+    /**
+     * Find the first cell with the specified value.
+     */
+    findValue(value: CellValue): XlsxResult<XlsxCell>;
+    /**
+     * Find cells within a specific range matching the predicate.
+     */
+    findInRange(rangeAddress: string, predicate: CellPredicate): XlsxResult<XlsxCell>;
+    /**
+     * Find all cells within a specific range matching the predicate.
+     */
+    findAllInRange(rangeAddress: string, predicate: CellPredicate): XlsxCell[];
+    /**
+     * Get the dimensions of the used area.
+     */
+    dimensions(): SheetDimensions;
+    /**
+     * Get the number of rows with data.
+     */
+    rowCount(): number;
+    /**
+     * Get the number of columns with data.
+     */
+    colCount(): number;
+    /**
+     * Get all merged cell ranges.
+     */
+    mergedRanges(): string[];
+    /**
+     * 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
+     */
+    getCellInternal(row: number, col: number): XlsxCell | undefined;
+}

package/dist/xlsx-workbook.d.ts

@@ -0,0 +1,128 @@
+import { Workbook } from 'exceljs';
+import { XlsxSheet } from './xlsx-sheet';
+import { XlsxResult, XlsxPath } from './xlsx-result';
+/**
+ * Predicate function for matching sheets.
+ */
+export type SheetPredicate = (sheet: XlsxSheet) => boolean;
+/**
+ * Workbook properties.
+ */
+export interface WorkbookProperties {
+    readonly title?: string;
+    readonly subject?: string;
+    readonly creator?: string;
+    readonly lastModifiedBy?: string;
+    readonly created?: Date;
+    readonly modified?: Date;
+}
+/**
+ * A wrapper around ExcelJS Workbook 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;
+    private constructor();
+    /**
+     * Creates an XlsxWorkbook from an ExcelJS workbook.
+     * @internal
+     */
+    static fromExcelJS(workbook: Workbook, file?: string): XlsxWorkbook;
+    /**
+     * Returns the path for lineage tracking.
+     */
+    get path(): XlsxPath;
+    /**
+     * Returns the file name if known.
+     */
+    get file(): string | undefined;
+    /**
+     * Get a sheet by name.
+     */
+    sheet(name: string): XlsxResult<XlsxSheet>;
+    /**
+     * Get a sheet by index (1-based, as per Excel convention).
+     */
+    sheetAt(index: number): XlsxResult<XlsxSheet>;
+    /**
+     * Get all sheets.
+     */
+    sheets(): XlsxSheet[];
+    /**
+     * Get all sheet names.
+     */
+    sheetNames(): string[];
+    /**
+     * Get the number of sheets.
+     */
+    sheetCount(): number;
+    /**
+     * Get the first sheet.
+     */
+    firstSheet(): XlsxResult<XlsxSheet>;
+    /**
+     * Get the last sheet.
+     */
+    lastSheet(): XlsxResult<XlsxSheet>;
+    /**
+     * Check if a sheet with the given name exists.
+     */
+    hasSheet(name: string): boolean;
+    /**
+     * Find the first sheet matching the predicate.
+     */
+    findSheet(predicate: SheetPredicate): XlsxResult<XlsxSheet>;
+    /**
+     * Find all sheets matching the predicate.
+     */
+    filterSheets(predicate: SheetPredicate): XlsxSheet[];
+    /**
+     * Find a sheet by name pattern (regex).
+     */
+    findSheetByPattern(pattern: RegExp): XlsxResult<XlsxSheet>;
+    /**
+     * Find all sheets by name pattern (regex).
+     */
+    filterSheetsByPattern(pattern: RegExp): XlsxSheet[];
+    /**
+     * Get workbook properties.
+     */
+    properties(): WorkbookProperties;
+    /**
+     * Get the workbook creator.
+     */
+    creator(): string | undefined;
+    /**
+     * Get the workbook creation date.
+     */
+    created(): Date | undefined;
+    /**
+     * Get the workbook modification date.
+     */
+    modified(): Date | undefined;
+    /**
+     * Get all defined names in the workbook.
+     */
+    definedNames(): string[];
+    /**
+     * Iterate over all sheets.
+     */
+    [Symbol.iterator](): Iterator<XlsxSheet>;
+    /**
+     * Execute a function for each sheet.
+     */
+    forEach(fn: (sheet: XlsxSheet, index: number) => void): void;
+    /**
+     * Map over all sheets.
+     */
+    map<T>(fn: (sheet: XlsxSheet, index: number) => T): T[];
+    /**
+     * Get the underlying ExcelJS workbook.
+     * @internal
+     */
+    getWorkbook(): Workbook;
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@origints/xlsx",
+  "version": "0.1.0",
+  "description": "XLSX parsing for Origins with full traceability to sheets, ranges, and cells.",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.es.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.es.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "exceljs": "^4.4.0"
+  },
+  "peerDependencies": {
+    "@origints/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@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"
+  }
+}