/**
 * xlsx STREAMING — read-only row iteration that never builds the sheet DOM.
 *
 * OWNERSHIP (DESIGN-P3.md): this file belongs to the STREAMING agent. It
 * imports from `./internal.js`, `../zip/index.js`, `../opc/index.js` and
 * `../xml/index.js` (for parsing the SMALL parts only) — never from
 * `./index.js`, `./styles.js`, `./structure.js` or `./formula/`. The
 * Integrate agent re-exports {@link readRows} from src/xlsx/index.ts.
 *
 * ```ts
 * for await (const row of readRows(bytes, { sheet: 'Data' })) {
 *   console.log(row.index, row.values);
 * }
 * ```
 *
 * MEMORY MODEL (honest, normative — CONTRACTS.md §8.19):
 * - The input `bytes` are already fully in memory (this library's API is
 *   Uint8Array in / Uint8Array out — there is no file-handle streaming).
 *   What streaming buys is everything ON TOP of the raw bytes:
 * - The worksheet XML is decompressed INCREMENTALLY through
 *   DecompressionStream and scanned by an incremental tokenizer; neither
 *   the decompressed XML text nor any DOM for it ever exists in full.
 *   Peak per-sheet overhead is O(one row) + fixed-size scan buffers.
 *   (Precisely: one copy of the sheet entry's COMPRESSED byte stream —
 *   always ≤ the input — plus a bounded decode window: the largest single
 *   XML token/cell text spanning a chunk boundary, plus the rows decoded
 *   from one chunk that the consumer has not pulled yet.)
 * - sharedStrings.xml IS materialized as a string array (cell `t="s"`
 *   entries are random-access by index; there is no way around holding
 *   them). Memory ∝ total shared-string text.
 * - workbook.xml, its rels, [Content_Types].xml and styles.xml are tiny
 *   and parsed normally (styles only to resolve date number formats).
 * - Net effect: a 1M-row sheet iterates in memory ≈ input bytes +
 *   shared strings + one row, instead of the multi-GB DOM `Workbook.open`
 *   would build.
 *
 * Typing rules are IDENTICAL to `Worksheet.getCell` (CONTRACTS.md §8.3):
 * shared/inline strings resolved, booleans, dates via the style's number
 * format (1900/1904 systems), errors as type 'error' with the literal.
 *
 * Single-pass caveat (deliberate, documented): the scan stops at
 * `</sheetData>` (or after the requested range's last row), so markup
 * AFTER the point where iteration stops is never validated — a file whose
 * trailing bytes are malformed can stream successfully even though
 * `Workbook.open` (which parses the whole part) would throw. Everything
 * the scanner DOES read is validated and malformed input throws typed
 * errors; the iterator never hangs and never yields garbage rows.
 */
import { type CellType, type CellValue } from './internal.js';
/** One decoded cell from a streamed row. */
export interface StreamedCell {
    /** A1 reference ('C7'). */
    readonly ref: string;
    /** 1-based column. */
    readonly col: number;
    /** Same classification as `Worksheet.getCellInfo`. */
    readonly type: CellType;
    readonly value: CellValue;
    /** Formula text, when the cell has one (never evaluated). */
    readonly formula?: string;
}
/** One streamed row. */
export interface StreamedRow {
    /** 1-based row number (rows the file omits are skipped by default). */
    readonly index: number;
    /** Cells that exist in the file, in column order. */
    readonly cells: readonly StreamedCell[];
    /**
     * Dense view: values[0] = column A … values[n] = the rightmost cell of
     * THIS row; gaps are null. Built lazily per row — using only `cells`
     * costs nothing extra.
     */
    readonly values: readonly CellValue[];
}
/** Options for {@link readRows}. */
export interface ReadRowsOptions {
    /**
     * Which sheet to stream: tab name (case-insensitive, as Excel matches)
     * or 0-based index in workbook order. Default: the first sheet.
     * Unknown name/index throws before iteration starts, listing the
     * available sheet names. Chartsheets and other non-worksheet entries
     * throw (they have no rows).
     */
    readonly sheet?: string | number;
    /**
     * Restrict iteration to an A1 range ('A1:F1000'). Rows outside are
     * skipped; cells outside the column span are omitted from `cells` /
     * `values`. Iteration STOPS after the range's last row — on a sorted
     * sheet this makes "first 100 rows of a million" cheap.
     */
    readonly range?: string;
    /**
     * Yield empty rows (rows the file omits entirely or stores with no
     * cells) as `{ index, cells: [], values: [] }` so `index` is contiguous.
     * Default false.
     *
     * Coverage: without a `range`, indices run from 1 through the LAST row
     * stored in the file (trailing rows are unknowable). With a `range`,
     * exactly the rows `range.start.row … range.end.row` are yielded,
     * including trailing empties.
     */
    readonly includeEmptyRows?: boolean;
}
/**
 * Iterate the rows of one worksheet without materializing the sheet DOM
 * — THE way to read million-row files. Read-only: nothing about the
 * workbook can be mutated through this API, and it never marks parts
 * dirty. See the module header for the exact memory model.
 *
 * The iterator is single-pass and lazy: work happens as you pull rows,
 * and an early `break`/`return` stops decompression immediately.
 * Malformed input throws the same typed errors as `Workbook.open`
 * (zip/xml/xlsx-prefixed), never hangs, and never returns garbage rows.
 *
 * ```ts
 * let total = 0;
 * for await (const row of readRows(bytes, { sheet: 'Data', range: 'B2:B1000000' })) {
 *   const v = row.cells[0]?.value;
 *   if (typeof v === 'number') total += v;
 * }
 * ```
 */
export declare function readRows(bytes: Uint8Array, options?: ReadRowsOptions): AsyncIterableIterator<StreamedRow>;
//# sourceMappingURL=streaming.d.ts.map