@openjsxl/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 openjsxl contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,24 @@
+# @openjsxl/core
+
+The zero-dependency OOXML engine behind [`openjsxl`](https://www.npmjs.com/package/openjsxl) —
+the `zip → xml → ooxml → reader` layers that turn an `.xlsx` into typed cells, built only on
+platform Web APIs (`DecompressionStream`, `TextDecoder`, …).
+
+**Most users should install [`openjsxl`](https://www.npmjs.com/package/openjsxl) instead** — it
+re-exports everything here and is the stable public surface. Install `@openjsxl/core` directly
+only if you want the engine without the facade.
+
+```sh
+npm install @openjsxl/core
+```
+
+```ts
+import { openXlsx, streamSheetRows, XlsxError } from '@openjsxl/core'
+```
+
+The API (`openXlsx`, `streamSheetRows`, `Workbook`, `Worksheet`, `XlsxError`, and the A1/date
+helpers) is documented in the [project README](https://github.com/joaquimserafim/openjsxl#readme).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,181 @@
+type XlsxErrorCode = 'not-a-zip' | 'not-xlsx' | 'missing-part' | 'corrupt-zip' | 'unsupported' | 'no-such-sheet' | 'part-too-large';
+declare class XlsxError extends Error {
+    /** Machine-readable discriminant; branch on this rather than the message. */
+    readonly code: XlsxErrorCode;
+    constructor(code: XlsxErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+
+interface CellRef {
+    /** 1-based column index (A = 1). */
+    readonly col: number;
+    /** 1-based row index. */
+    readonly row: number;
+}
+declare function columnToIndex(letters: string): number;
+declare function indexToColumn(index: number): string;
+declare function parseRef(ref: string): CellRef;
+declare function formatRef(ref: CellRef): string;
+
+declare function serialToDate(serial: number, date1904?: boolean): Date;
+
+type CellType = 'empty' | 'string' | 'number' | 'boolean' | 'date' | 'error';
+interface CellBase {
+    /** A1 reference, e.g. "B2". */
+    readonly ref: string;
+}
+type Cell = (CellBase & {
+    readonly type: 'empty';
+    readonly value: null;
+}) | (CellBase & {
+    readonly type: 'string';
+    readonly value: string;
+}) | (CellBase & {
+    readonly type: 'number';
+    readonly value: number;
+}) | (CellBase & {
+    readonly type: 'boolean';
+    readonly value: boolean;
+}) | (CellBase & {
+    readonly type: 'date';
+    readonly value: Date;
+}) | (CellBase & {
+    readonly type: 'error';
+    readonly value: string;
+});
+interface SheetInfo {
+    /** Sheet name as shown on Excel's tab. */
+    readonly name: string;
+    /** Workbook-relative part path, resolved via the relationship graph. */
+    readonly path: string;
+    /** false for hidden or very-hidden sheets. */
+    readonly visible: boolean;
+}
+interface Comment {
+    /** The cell the comment is anchored to, e.g. "B2". */
+    readonly ref: string;
+    /** Comment author, resolved from the authors table. Absent when it can't be resolved. */
+    readonly author?: string;
+    /** The comment's plain text — rich-text runs concatenated, formatting dropped. */
+    readonly text: string;
+}
+interface Hyperlink {
+    /** The cell or range the link covers, e.g. "A1" or "B1:C2". */
+    readonly ref: string;
+    /**
+     * External destination (a URL, `mailto:`, or `file:` target) resolved through the
+     * worksheet's relationships. Absent for a purely in-workbook link.
+     */
+    readonly target?: string;
+    /** In-workbook destination, e.g. "'Sheet2'!B5". Absent for a purely external link. */
+    readonly location?: string;
+    /** Hover text the producer attached to the link, if any. */
+    readonly tooltip?: string;
+    /** Display-text override for the link, if any. */
+    readonly display?: string;
+}
+
+interface StyleTable {
+    /** True when the cell format at this `s` index applies a date/time number format. */
+    isDateStyle(styleIndex: number | undefined): boolean;
+    /**
+     * The number-format code applied at this `s` index — a custom code (`<numFmts>`) or a
+     * built-in one (e.g. `"0.00%"`, `"mm-dd-yy"`). `undefined` when the id is a locale/reserved
+     * built-in with no portable code, or the index is out of range.
+     */
+    formatCode(styleIndex: number | undefined): string | undefined;
+}
+
+interface DecodeContext {
+    /** The workbook's shared string table (F1.5), indexed by `s`-type cells. */
+    readonly sharedStrings: readonly string[];
+    /** Style table (F2.1); when present, date-styled numbers decode as `date` cells. */
+    readonly styles?: StyleTable;
+    /** Workbook 1904 date system flag, selecting the serial epoch. Defaults to false. */
+    readonly date1904?: boolean;
+}
+
+interface Relationship {
+    readonly id: string;
+    readonly type: string;
+    /** Target exactly as written; resolve internal ones with resolveTarget. */
+    readonly target: string;
+    readonly targetMode: 'Internal' | 'External';
+}
+
+interface Row {
+    /** 1-based row index — from `<row r>`, or positional when the attribute is absent. */
+    readonly index: number;
+    /** Cells present in the row, in document order. Gaps are simply absent (sparse). */
+    readonly cells: readonly Cell[];
+}
+
+declare class Worksheet {
+    #private;
+    /** Sheet name as shown on Excel's tab. */
+    readonly name: string;
+    constructor(info: SheetInfo, xml: string, context: DecodeContext, rels?: Map<string, Relationship>, commentsXml?: string);
+    /** Workbook-relative part path, e.g. `xl/worksheets/sheet1.xml`. */
+    get path(): string;
+    /** false for hidden or very-hidden sheets. */
+    get visible(): boolean;
+    /**
+     * Merged-cell ranges in A1 notation (e.g. `['A1:B1', 'A2:A4']`), in document order. Only the
+     * top-left cell of a merge holds a value; the rest read as `empty`. Empty when none.
+     */
+    get mergedCells(): readonly string[];
+    /**
+     * Hyperlinks declared on this sheet, in document order. Each carries the covered `ref` and,
+     * where present, a resolved external `target`, an in-workbook `location`, a `tooltip`, and a
+     * `display` override. Empty when none.
+     */
+    get hyperlinks(): readonly Hyperlink[];
+    /**
+     * The number-format code applied to the cell at `ref` — a custom code like `"yyyy-mm-dd"`
+     * or `"0.00%"`, or a built-in one. `undefined` when the workbook has no style table or the
+     * id has no portable code. An unstyled or absent cell resolves to the default format (style
+     * 0, usually `"General"`), mirroring how date detection defaults.
+     */
+    numberFormat(ref: string): string | undefined;
+    /**
+     * The sheet's declared used range in A1 notation (e.g. `"A1:E10"`, or a single cell), from
+     * the worksheet's `<dimension>`. `undefined` when the producer omits it — it is an optional
+     * hint, not authoritative, so treat a present value as advisory.
+     */
+    get dimension(): string | undefined;
+    /**
+     * The comments anchored to cells on this sheet, in document order — each with its `ref`,
+     * resolved `author`, and plain `text`. Empty when the sheet has no comments part.
+     */
+    get comments(): readonly Comment[];
+    /** The cell at an A1 reference. Absent cells read as `empty` (Excel treats them blank). */
+    cell(ref: string): Cell;
+    /** Stream the populated rows in document order. Sparse: empty rows/cells are absent. */
+    rows(): AsyncGenerator<Row>;
+}
+declare class Workbook {
+    #private;
+    /** Sheets in tab order. */
+    readonly sheets: readonly SheetInfo[];
+    constructor(sheets: SheetInfo[], byName: Map<string, Worksheet>);
+    /** The worksheet with this tab name. Throws if there is none. */
+    sheet(name: string): Worksheet;
+}
+/**
+ * Reader options. `maxPartBytes` caps the declared decompressed size of any single part — a
+ * zip-bomb guard independent of the archive's own (untrusted) size fields. Omit for no ceiling.
+ */
+interface ReadOptions {
+    readonly maxPartBytes?: number;
+}
+declare function openXlsx(source: Uint8Array | ArrayBuffer, options?: ReadOptions): Promise<Workbook>;
+/**
+ * Stream the rows of one sheet with roughly constant memory: the worksheet is never
+ * materialized as a whole string — it is decompressed and tokenized chunk by chunk, and each
+ * row is yielded then discarded (F2.2). Use this for large sheets; use `openXlsx` when you
+ * need random `cell()` access. `sheetName` defaults to the first sheet in tab order.
+ */
+declare function streamSheetRows(source: Uint8Array | ArrayBuffer, sheetName?: string, options?: ReadOptions): AsyncGenerator<Row>;
+
+export { type Cell, type CellRef, type CellType, type Comment, type Hyperlink, type ReadOptions, type Row, type SheetInfo, Workbook, Worksheet, XlsxError, type XlsxErrorCode, columnToIndex, formatRef, indexToColumn, openXlsx, parseRef, serialToDate, streamSheetRows };