@origints/xlsx 0.1.0

package/dist/xlsx-cell.d.ts

@@ -0,0 +1,212 @@
+import { Cell as ExcelJSCell } from 'exceljs';
+import { XlsxResult, XlsxPath, CellValue, ExtendedCellValue } from './xlsx-result';
+/**
+ * Cell style information.
+ */
+export interface CellStyle {
+    readonly font?: {
+        readonly name?: string;
+        readonly size?: number;
+        readonly bold?: boolean;
+        readonly italic?: boolean;
+        readonly underline?: boolean;
+        readonly strikethrough?: boolean;
+        readonly color?: string;
+    };
+    readonly fill?: {
+        readonly type?: string;
+        readonly color?: 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;
+    };
+    readonly numFmt?: string;
+}
+/**
+ * A segment of rich text with its formatting.
+ */
+export interface RichTextSegment {
+    readonly text: string;
+    readonly bold?: boolean;
+    readonly italic?: boolean;
+    readonly underline?: boolean;
+    readonly strikethrough?: boolean;
+    readonly color?: string;
+    readonly size?: number;
+    readonly font?: string;
+}
+/**
+ * Rich text content with all formatting preserved.
+ */
+export interface RichTextContent {
+    readonly segments: readonly RichTextSegment[];
+    readonly hyperlink?: string;
+}
+/**
+ * A wrapper around ExcelJS Cell 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 _path;
+    private readonly _sheetName;
+    private constructor();
+    /**
+     * Creates an XlsxCell from an ExcelJS cell.
+     * @internal
+     */
+    static fromExcelJS(cell: ExcelJSCell, sheetName: string, file?: string): XlsxCell;
+    /**
+     * Returns the cell address (e.g., "A1").
+     */
+    get address(): string;
+    /**
+     * Returns the 1-based row number.
+     */
+    get row(): number;
+    /**
+     * Returns the 1-based column number.
+     */
+    get col(): number;
+    /**
+     * Returns the column letter(s) (e.g., "A", "AA").
+     */
+    get colLetter(): string;
+    /**
+     * Returns the current path for lineage tracking.
+     */
+    get path(): XlsxPath;
+    /**
+     * Returns the sheet name this cell belongs to.
+     */
+    get sheetName(): string;
+    /**
+     * Returns the raw cell value.
+     */
+    value(): XlsxResult<CellValue>;
+    /**
+     * Returns the extended cell value (including formula info).
+     */
+    extendedValue(): XlsxResult<ExtendedCellValue>;
+    /**
+     * Extract value as a string.
+     */
+    string(): XlsxResult<string>;
+    /**
+     * Extract value as a number.
+     */
+    number(): XlsxResult<number>;
+    /**
+     * Extract value as a boolean.
+     */
+    boolean(): XlsxResult<boolean>;
+    /**
+     * Extract value as a Date.
+     */
+    date(): XlsxResult<Date>;
+    /**
+     * Get the formula if this cell contains one.
+     */
+    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>;
+    /**
+     * Check if the cell contains rich text (multiple formatted segments).
+     */
+    isRichText(): boolean;
+    /**
+     * Check if the cell is empty.
+     */
+    isEmpty(): boolean;
+    /**
+     * Check if the cell contains a formula.
+     */
+    isFormula(): boolean;
+    /**
+     * Check if the cell is part of a merged range.
+     */
+    isMerged(): boolean;
+    /**
+     * Check if this is the master cell of a merged range.
+     */
+    isMergedMaster(): boolean;
+    /**
+     * Check if the cell contains a string.
+     */
+    isString(): boolean;
+    /**
+     * Check if the cell contains a number.
+     */
+    isNumber(): boolean;
+    /**
+     * Check if the cell contains a boolean.
+     */
+    isBoolean(): boolean;
+    /**
+     * Check if the cell contains a date.
+     */
+    isDate(): boolean;
+    /**
+     * Check if the cell contains an error.
+     */
+    isError(): boolean;
+    /**
+     * Get the cell's style information.
+     */
+    style(): CellStyle;
+    /**
+     * Get the hyperlink URL if the cell contains one.
+     */
+    hyperlink(): XlsxResult<string>;
+    /**
+     * Get the comment/note if the cell has one.
+     */
+    comment(): XlsxResult<string>;
+    /**
+     * Get a cell offset from this one.
+     * @internal Used by navigation methods
+     */
+    getOffsetCell(rowDelta: number, colDelta: number, getCell: (row: number, col: number) => XlsxCell | undefined): XlsxResult<XlsxCell>;
+    /**
+     * Get the raw value, handling ExcelJS value 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).
+     */
+    private excelDateToJS;
+}

package/dist/xlsx-cursor.d.ts

@@ -0,0 +1,203 @@
+import { XlsxSheet } from './xlsx-sheet';
+import { XlsxCell } from './xlsx-cell';
+import { XlsxResult, XlsxPath } from './xlsx-result';
+import { CellPredicate } from './xlsx-query';
+/**
+ * Direction for cursor movement.
+ */
+export type CursorDirection = 'right' | 'left' | 'down' | 'up';
+/**
+ * Result of a grab operation.
+ */
+export interface GrabResult {
+    readonly cells: XlsxCell[];
+    readonly cursor: XlsxCursor;
+}
+/**
+ * Result of a single grab operation.
+ */
+export interface GrabOneResult {
+    readonly cell: XlsxCell;
+    readonly cursor: XlsxCursor;
+}
+/**
+ * An immutable cursor for navigating through cells in a sheet.
+ *
+ * XlsxCursor provides a fluent API for moving through cells,
+ * skipping cells based on predicates, and grabbing sequences
+ * of cells. Each operation returns a new cursor, maintaining
+ * immutability.
+ */
+export declare class XlsxCursor {
+    private readonly sheet;
+    private readonly _row;
+    private readonly _col;
+    private readonly _direction;
+    private constructor();
+    /**
+     * Create a cursor from an address string.
+     * @internal
+     */
+    static create(sheet: XlsxSheet, address: string): XlsxCursor;
+    /**
+     * Create a cursor from row and column coordinates.
+     * @internal
+     */
+    static createAt(sheet: XlsxSheet, row: number, col: number): XlsxCursor;
+    /**
+     * Get the current row (1-based).
+     */
+    get row(): number;
+    /**
+     * Get the current column (1-based).
+     */
+    get col(): number;
+    /**
+     * Get the current address.
+     */
+    get address(): string;
+    /**
+     * Get the current column letter.
+     */
+    get colLetter(): string;
+    /**
+     * Get the current direction.
+     */
+    get direction(): CursorDirection;
+    /**
+     * Get the path for lineage tracking.
+     */
+    get path(): XlsxPath;
+    /**
+     * Move by a delta (returns new cursor).
+     */
+    move(rowDelta: number, colDelta: number): XlsxCursor;
+    /**
+     * Move to a specific address.
+     */
+    moveTo(address: string): XlsxCursor;
+    /**
+     * Move to a specific row.
+     */
+    moveToRow(row: number): XlsxCursor;
+    /**
+     * Move to a specific column.
+     */
+    moveToCol(col: number | string): XlsxCursor;
+    /**
+     * Move left by count cells.
+     */
+    left(count?: number): XlsxCursor;
+    /**
+     * Move right by count cells.
+     */
+    right(count?: number): XlsxCursor;
+    /**
+     * Move up by count cells.
+     */
+    up(count?: number): XlsxCursor;
+    /**
+     * Move down by count cells.
+     */
+    down(count?: number): XlsxCursor;
+    /**
+     * Set the current direction.
+     */
+    setDirection(direction: CursorDirection): XlsxCursor;
+    /**
+     * Move forward in the current direction.
+     */
+    forward(count?: number): XlsxCursor;
+    /**
+     * Move to the start of the current row.
+     */
+    startOfRow(): XlsxCursor;
+    /**
+     * Move to the start of the current column.
+     */
+    startOfCol(): XlsxCursor;
+    /**
+     * Skip empty cells in the current direction.
+     */
+    skipEmpty(): XlsxCursor;
+    /**
+     * Skip cells while the predicate is true.
+     */
+    skipWhile(predicate: CellPredicate): XlsxCursor;
+    /**
+     * Skip cells until the predicate is true.
+     */
+    skipUntil(predicate: CellPredicate): XlsxCursor;
+    /**
+     * Skip cells until a specific value is found.
+     */
+    skipToValue(value: unknown): XlsxCursor;
+    /**
+     * Skip a specific number of cells.
+     */
+    skip(count: number): XlsxCursor;
+    /**
+     * Grab the current cell and move forward.
+     */
+    grab(): XlsxResult<GrabOneResult>;
+    /**
+     * Grab n cells in the current direction.
+     */
+    grabN(count: number): XlsxResult<GrabResult>;
+    /**
+     * Grab cells while the predicate is true.
+     */
+    grabWhile(predicate: CellPredicate): XlsxResult<GrabResult>;
+    /**
+     * Grab cells until the predicate is true (not including the matching cell).
+     */
+    grabUntil(predicate: CellPredicate): XlsxResult<GrabResult>;
+    /**
+     * Grab the rest of the current row.
+     */
+    grabRow(): XlsxResult<GrabResult>;
+    /**
+     * Grab the rest of the current column.
+     */
+    grabCol(): XlsxResult<GrabResult>;
+    /**
+     * Grab non-empty cells in the current direction.
+     */
+    grabNonEmpty(): XlsxResult<GrabResult>;
+    /**
+     * Peek at the current cell without moving.
+     */
+    peek(): XlsxResult<XlsxCell>;
+    /**
+     * Peek at cells ahead without moving.
+     */
+    peekAhead(count: number): XlsxResult<XlsxCell[]>;
+    /**
+     * Peek at a cell at an offset without moving.
+     */
+    peekAt(rowDelta: number, colDelta: number): XlsxResult<XlsxCell>;
+    /**
+     * Get the cell at the current position.
+     */
+    cell(): XlsxResult<XlsxCell>;
+    /**
+     * Get the value of the current cell.
+     */
+    value(): XlsxResult<unknown>;
+    /**
+     * Check if the cursor is at a valid position with data.
+     */
+    isValid(): boolean;
+    /**
+     * Check if the current cell is empty.
+     */
+    isEmpty(): boolean;
+    /**
+     * Check if the current cell is non-empty.
+     */
+    isNotEmpty(): boolean;
+    /**
+     * Create a new cursor at the same position.
+     */
+    clone(): XlsxCursor;
+}

package/dist/xlsx-query.d.ts

@@ -0,0 +1,155 @@
+import { XlsxCell } from './xlsx-cell';
+import { CellValue } from './xlsx-result';
+/**
+ * A predicate function for matching cells.
+ */
+export type CellPredicate = (cell: XlsxCell) => boolean;
+/**
+ * Built-in predicates for common cell matching scenarios.
+ */
+export declare const predicates: {
+    /**
+     * Match cells with the exact value.
+     */
+    equals: (value: CellValue) => CellPredicate;
+    /**
+     * Match cells containing the specified text (case-insensitive by default).
+     */
+    contains: (text: string, caseSensitive?: boolean) => CellPredicate;
+    /**
+     * Match cells whose value matches the regex pattern.
+     */
+    matches: (pattern: RegExp) => CellPredicate;
+    /**
+     * Match cells whose string value starts with the prefix.
+     */
+    startsWith: (prefix: string, caseSensitive?: boolean) => CellPredicate;
+    /**
+     * Match cells whose string value ends with the suffix.
+     */
+    endsWith: (suffix: string, caseSensitive?: boolean) => CellPredicate;
+    /**
+     * Match cells containing a string value.
+     */
+    isString: () => CellPredicate;
+    /**
+     * Match cells containing a numeric value.
+     */
+    isNumber: () => CellPredicate;
+    /**
+     * Match cells containing a boolean value.
+     */
+    isBoolean: () => CellPredicate;
+    /**
+     * Match cells containing a date value.
+     */
+    isDate: () => CellPredicate;
+    /**
+     * Match empty cells.
+     */
+    isEmpty: () => CellPredicate;
+    /**
+     * Match non-empty cells.
+     */
+    isNotEmpty: () => CellPredicate;
+    /**
+     * Match cells containing a formula.
+     */
+    isFormula: () => CellPredicate;
+    /**
+     * Match cells containing an error.
+     */
+    isError: () => CellPredicate;
+    /**
+     * Match merged cells.
+     */
+    isMerged: () => CellPredicate;
+    /**
+     * Match cells with numeric value greater than n.
+     */
+    greaterThan: (n: number) => CellPredicate;
+    /**
+     * Match cells with numeric value greater than or equal to n.
+     */
+    greaterThanOrEqual: (n: number) => CellPredicate;
+    /**
+     * Match cells with numeric value less than n.
+     */
+    lessThan: (n: number) => CellPredicate;
+    /**
+     * Match cells with numeric value less than or equal to n.
+     */
+    lessThanOrEqual: (n: number) => CellPredicate;
+    /**
+     * Match cells with numeric value between min and max (inclusive).
+     */
+    between: (min: number, max: number) => CellPredicate;
+    /**
+     * Match cells with date before the specified date.
+     */
+    dateBefore: (date: Date) => CellPredicate;
+    /**
+     * Match cells with date after the specified date.
+     */
+    dateAfter: (date: Date) => CellPredicate;
+    /**
+     * Match cells with date between start and end (inclusive).
+     */
+    dateBetween: (start: Date, end: Date) => CellPredicate;
+    /**
+     * Match cells in the specified row.
+     */
+    inRow: (rowNum: number) => CellPredicate;
+    /**
+     * Match cells in the specified column.
+     */
+    inCol: (colNum: number) => CellPredicate;
+    /**
+     * Match cells in the specified column (by letter).
+     */
+    inColLetter: (colLetter: string) => CellPredicate;
+    /**
+     * Match cells that satisfy all predicates.
+     */
+    and: (...preds: CellPredicate[]) => CellPredicate;
+    /**
+     * Match cells that satisfy at least one predicate.
+     */
+    or: (...preds: CellPredicate[]) => CellPredicate;
+    /**
+     * Match cells that do not satisfy the predicate.
+     */
+    not: (pred: CellPredicate) => CellPredicate;
+    /**
+     * Match cells with bold font.
+     */
+    isBold: () => CellPredicate;
+    /**
+     * Match cells with italic font.
+     */
+    isItalic: () => CellPredicate;
+    /**
+     * Match cells with a hyperlink.
+     */
+    hasHyperlink: () => CellPredicate;
+    /**
+     * Match cells with a comment.
+     */
+    hasComment: () => CellPredicate;
+    /**
+     * Always match.
+     */
+    always: () => CellPredicate;
+    /**
+     * Never match.
+     */
+    never: () => CellPredicate;
+    /**
+     * Create a custom predicate from a function.
+     */
+    custom: (fn: (cell: XlsxCell) => boolean) => CellPredicate;
+};
+/**
+ * Type for the predicates object.
+ */
+export type Predicates = typeof predicates;