@bilig/xlsx 0.164.0

package/README.md

@@ -0,0 +1,25 @@
+# @bilig/xlsx
+
+`@bilig/xlsx` provides ZIP, address, and source-preserving patch primitives used
+by Bilig runtime packages. This package does not depend on SheetJS or the
+`xlsx` CDN tarball.
+
+## Source-Preserving Literal Patches
+
+Use `exportXlsxSourceLiteralPatchesToFileAsync` when a service needs to apply
+scalar cell edits to an existing XLSX package while preserving untouched package
+parts and avoiding full-source reads:
+
+```ts
+import { exportXlsxSourceLiteralPatchesToFileAsync } from '@bilig/xlsx'
+
+await exportXlsxSourceLiteralPatchesToFileAsync({
+  source: fileBackedXlsxReader,
+  outputPath: './patched.xlsx',
+  sheetNames: ['Inputs'],
+  patches: [{ sheetName: 'Inputs', address: 'B3', value: 96000 }],
+})
+```
+
+The file-backed source only needs `byteLength` and `readRange(start, end)` for
+the streaming patch path. `readBytes()` is a fallback, not the normal path.

package/dist/address.d.ts

@@ -0,0 +1,15 @@
+export interface XlsxCellAddress {
+    readonly r: number;
+    readonly c: number;
+}
+export interface XlsxCellRange {
+    readonly s: XlsxCellAddress;
+    readonly e: XlsxCellAddress;
+}
+export declare function decodeCellAddress(address: string): XlsxCellAddress;
+export declare function encodeColumnAddress(columnIndex: number): string;
+export declare function decodeColumnAddress(columnAddress: string): number;
+export declare function encodeCellAddress(address: XlsxCellAddress): string;
+export declare function normalizeCellAddress(address: string): string;
+export declare function decodeCellRange(ref: string): XlsxCellRange;
+export declare function encodeCellRange(range: XlsxCellRange): string;

package/dist/address.js

@@ -0,0 +1,82 @@
+const cellAddressPattern = /^\$?([A-Za-z]{1,4})\$?([1-9][0-9]*)$/u;
+export function decodeCellAddress(address) {
+    const match = cellAddressPattern.exec(address);
+    if (!match) {
+        throw new Error(`Invalid XLSX cell address: ${address}`);
+    }
+    const rowNumber = Number(match[2]);
+    if (!Number.isSafeInteger(rowNumber) || rowNumber < 1) {
+        throw new Error(`Invalid XLSX row number: ${address}`);
+    }
+    let column = 0;
+    for (const character of match[1].toUpperCase()) {
+        const code = character.charCodeAt(0);
+        if (code < 65 || code > 90) {
+            throw new Error(`Invalid XLSX column address: ${address}`);
+        }
+        column = column * 26 + code - 64;
+    }
+    return { r: rowNumber - 1, c: column - 1 };
+}
+export function encodeColumnAddress(columnIndex) {
+    if (!Number.isSafeInteger(columnIndex) || columnIndex < 0) {
+        throw new Error(`Invalid XLSX column index: ${String(columnIndex)}`);
+    }
+    let column = columnIndex + 1;
+    let output = '';
+    while (column > 0) {
+        const remainder = (column - 1) % 26;
+        output = String.fromCharCode(65 + remainder) + output;
+        column = Math.floor((column - 1) / 26);
+    }
+    return output;
+}
+export function decodeColumnAddress(columnAddress) {
+    const normalized = columnAddress.trim().replaceAll('$', '').toUpperCase();
+    if (!/^[A-Z]{1,4}$/u.test(normalized)) {
+        throw new Error(`Invalid XLSX column address: ${columnAddress}`);
+    }
+    let column = 0;
+    for (const character of normalized) {
+        const code = character.charCodeAt(0);
+        if (code < 65 || code > 90) {
+            throw new Error(`Invalid XLSX column address: ${columnAddress}`);
+        }
+        column = column * 26 + code - 64;
+    }
+    return column - 1;
+}
+export function encodeCellAddress(address) {
+    if (!Number.isSafeInteger(address.r) || !Number.isSafeInteger(address.c) || address.r < 0 || address.c < 0) {
+        throw new Error(`Invalid XLSX cell coordinates: ${JSON.stringify(address)}`);
+    }
+    return `${encodeColumnAddress(address.c)}${String(address.r + 1)}`;
+}
+export function normalizeCellAddress(address) {
+    return encodeCellAddress(decodeCellAddress(address.replaceAll('$', '')));
+}
+export function decodeCellRange(ref) {
+    const parts = ref.split(':');
+    const [startRef, endRef] = parts;
+    if (!startRef || parts.length > 2) {
+        throw new Error(`Invalid XLSX cell range: ${ref}`);
+    }
+    const start = decodeCellAddress(startRef);
+    const end = decodeCellAddress(endRef ?? startRef);
+    return {
+        s: {
+            r: Math.min(start.r, end.r),
+            c: Math.min(start.c, end.c),
+        },
+        e: {
+            r: Math.max(start.r, end.r),
+            c: Math.max(start.c, end.c),
+        },
+    };
+}
+export function encodeCellRange(range) {
+    const start = encodeCellAddress(range.s);
+    const end = encodeCellAddress(range.e);
+    return start === end ? start : `${start}:${end}`;
+}
+//# sourceMappingURL=address.js.map

package/dist/address.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.js","sourceRoot":"","sources":["../src/address.ts"],"names":[],"mappings":"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"}

package/dist/external-workbook-types.d.ts

@@ -0,0 +1,44 @@
+export interface XlsxExternalWorkbookInput {
+    readonly bytes: Uint8Array | ArrayBuffer;
+    readonly fileName?: string;
+    readonly workbookName?: string;
+    readonly target?: string;
+}
+export declare const xlsxExternalWorkbookByteInputLimit = 1000000;
+export declare function assertXlsxExternalWorkbookByteInputWithinLimit(byteLength: number, fileName: string): void;
+export type XlsxExternalLinkCacheArtifactMode = 'preserve-existing' | 'replace-refreshed';
+export type XlsxExternalWorkbookHydrationStatus = 'refreshed' | 'skipped-no-match' | 'skipped-ambiguous-match' | 'skipped-empty-refresh';
+export type XlsxExternalWorkbookHydrationMatchKind = 'exact-target' | 'unique-workbook-identity';
+export interface XlsxExternalWorkbookHydrationReferenceDiagnostic {
+    readonly bookIndex: number;
+    readonly workbookName?: string;
+    readonly target?: string;
+    readonly status: XlsxExternalWorkbookHydrationStatus;
+    readonly candidateCount: number;
+    readonly referenceCandidateCount?: number;
+    readonly matchKind?: XlsxExternalWorkbookHydrationMatchKind;
+    readonly matchedFileName?: string;
+    readonly matchedWorkbookName?: string;
+    readonly matchedTarget?: string;
+    readonly refreshedSheetCount?: number;
+    readonly refreshedCellCount?: number;
+}
+export interface XlsxExternalWorkbookHydrationDiagnostics {
+    readonly externalWorkbookCount: number;
+    readonly externalReferenceCount: number;
+    readonly refreshedBookIndices: readonly number[];
+    readonly refreshedSheetCount: number;
+    readonly refreshedCellCount: number;
+    readonly skippedNoMatchCount: number;
+    readonly skippedAmbiguousMatchCount: number;
+    readonly skippedEmptyRefreshCount: number;
+    readonly references: readonly XlsxExternalWorkbookHydrationReferenceDiagnostic[];
+}
+export interface ImportedWorkbookDiagnostics {
+    readonly externalWorkbookHydration?: XlsxExternalWorkbookHydrationDiagnostics;
+}
+export interface XlsxImportOptions {
+    readonly externalWorkbooks?: readonly XlsxExternalWorkbookInput[];
+    readonly externalLinkCacheArtifactMode?: XlsxExternalLinkCacheArtifactMode;
+    readonly preferNativeSimpleImport?: boolean;
+}

package/dist/external-workbook-types.js

@@ -0,0 +1,12 @@
+export const xlsxExternalWorkbookByteInputLimit = 1_000_000;
+export function assertXlsxExternalWorkbookByteInputWithinLimit(byteLength, fileName) {
+    if (byteLength <= xlsxExternalWorkbookByteInputLimit) {
+        return;
+    }
+    throw new Error([
+        `external workbook byte input is small-workbook only: ${fileName} is ${byteLength} bytes`,
+        `limit is ${xlsxExternalWorkbookByteInputLimit} bytes`,
+        'Large external workbook hydration must use a native file-backed path before it can be enabled for production large-XLSX jobs.',
+    ].join('; '));
+}
+//# sourceMappingURL=external-workbook-types.js.map

package/dist/external-workbook-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-workbook-types.js","sourceRoot":"","sources":["../src/external-workbook-types.ts"],"names":[],"mappings":"AAOA,MAAM,CAAC,MAAM,kCAAkC,GAAG,SAAS,CAAA;AAE3D,MAAM,UAAU,8CAA8C,CAAC,UAAkB,EAAE,QAAgB;IACjG,IAAI,UAAU,IAAI,kCAAkC,EAAE,CAAC;QACrD,OAAM;IACR,CAAC;IACD,MAAM,IAAI,KAAK,CACb;QACE,wDAAwD,QAAQ,OAAO,UAAU,QAAQ;QACzF,YAAY,kCAAkC,QAAQ;QACtD,+HAA+H;KAChI,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAA;AACH,CAAC"}

package/dist/file-source.d.ts

@@ -0,0 +1,10 @@
+import type { XlsxSourceReader } from './source-preserving-literal-patches.js';
+import type { XlsxZipByteSource } from './zip-reader.js';
+export type FileXlsxSourceReader = XlsxSourceReader & XlsxZipByteSource & {
+    readonly path: string;
+};
+export interface FileXlsxSourceReaderOptions {
+    readonly maxReadBytes?: number | false;
+}
+export declare const defaultFileXlsxSourceReadBytesLimit = 1000000;
+export declare function createFileXlsxSourceReader(path: string, options?: FileXlsxSourceReaderOptions): FileXlsxSourceReader;

package/dist/file-source.js

@@ -0,0 +1,76 @@
+import { closeSync, openSync, readFileSync, readSync, statSync } from 'node:fs';
+export const defaultFileXlsxSourceReadBytesLimit = 1_000_000;
+export function createFileXlsxSourceReader(path, options = {}) {
+    const fd = openSync(path, 'r');
+    const byteLength = statSync(path).size;
+    const maxReadBytes = options.maxReadBytes ?? defaultFileXlsxSourceReadBytesLimit;
+    let closed = false;
+    const assertOpen = () => {
+        if (closed) {
+            throw new Error('XLSX file source has been released');
+        }
+    };
+    const assertRange = (start, end) => {
+        if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 0 || end < start || end > byteLength) {
+            throw new Error(`Invalid XLSX file byte range: ${String(start)}..${String(end)}`);
+        }
+    };
+    const assertReadBytesWithinLimit = () => {
+        if (maxReadBytes === false || byteLength <= maxReadBytes) {
+            return;
+        }
+        throw new Error([
+            `XLSX file source readBytes is small-workbook only: ${path} is ${String(byteLength)} bytes`,
+            `limit is ${String(maxReadBytes)} bytes`,
+            'Use readRange/readRangeInto or a file-backed native XLSX API for large workbooks.',
+        ].join('; '));
+    };
+    return {
+        byteLength,
+        path,
+        readBytes() {
+            assertOpen();
+            assertReadBytesWithinLimit();
+            return readFileSync(path);
+        },
+        readRange(start, end) {
+            assertOpen();
+            assertRange(start, end);
+            const length = end - start;
+            const buffer = new Uint8Array(length);
+            let offset = 0;
+            while (offset < length) {
+                const bytesRead = readSync(fd, buffer, offset, length - offset, start + offset);
+                if (bytesRead === 0) {
+                    throw new Error('Unexpected EOF while reading XLSX file source');
+                }
+                offset += bytesRead;
+            }
+            return buffer;
+        },
+        readRangeInto(start, end, target) {
+            assertOpen();
+            assertRange(start, end);
+            const length = end - start;
+            if (target.byteLength < length) {
+                throw new Error('XLSX file source scratch buffer is too small');
+            }
+            let offset = 0;
+            while (offset < length) {
+                const bytesRead = readSync(fd, target, offset, length - offset, start + offset);
+                if (bytesRead === 0) {
+                    throw new Error('Unexpected EOF while reading XLSX file source');
+                }
+                offset += bytesRead;
+            }
+            return target.subarray(0, length);
+        },
+        release() {
+            if (!closed) {
+                closeSync(fd);
+                closed = true;
+            }
+        },
+    };
+}
+//# sourceMappingURL=file-source.js.map

package/dist/file-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-source.js","sourceRoot":"","sources":["../src/file-source.ts"],"names":[],"mappings":"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"}

package/dist/formula-cache-reader.d.ts

@@ -0,0 +1,30 @@
+import { type StreamingNativeWorkbookCore } from './streaming-native-workbook-core.js';
+export type XlsxFormulaCacheInspectionLimit = number | 'all';
+export type XlsxFormulaCacheLiteral = string | number | boolean | null;
+export type XlsxFormulaCacheReadPhase = 'open-source' | 'zip-central-directory' | 'workbook-metadata' | 'formula-cache-scan';
+export type XlsxFormulaCacheReadErrorReason = 'invalid-or-zip64-xlsx' | 'worksheet-stream-unavailable';
+export interface XlsxFormulaCacheCell {
+    readonly target: string;
+    readonly formula: string;
+    readonly cachedValue?: XlsxFormulaCacheLiteral;
+}
+export interface XlsxFormulaCacheScanResult {
+    readonly inputBytes: number;
+    readonly sheetNames: readonly string[];
+    readonly formulaCellCount: number;
+    readonly cells: readonly XlsxFormulaCacheCell[];
+}
+export declare class XlsxFormulaCacheReadError extends Error {
+    readonly reason: XlsxFormulaCacheReadErrorReason;
+    readonly inputBytes: number;
+    constructor(message: string, reason: XlsxFormulaCacheReadErrorReason, inputBytes: number);
+}
+export declare const defaultXlsxFormulaCacheInspectionLimit: XlsxFormulaCacheInspectionLimit;
+export declare function readXlsxFormulaCacheCellsFromFile(inputPath: string, options?: {
+    readonly inspectLimit?: XlsxFormulaCacheInspectionLimit;
+    readonly onPhase?: (phase: XlsxFormulaCacheReadPhase) => void;
+}): XlsxFormulaCacheScanResult;
+export declare function readXlsxFormulaCacheCellsFromWorkbookCore(core: StreamingNativeWorkbookCore, options?: {
+    readonly inspectLimit?: XlsxFormulaCacheInspectionLimit;
+}): XlsxFormulaCacheScanResult;
+export declare function normalizeXlsxFormulaCacheInspectionLimit(limit: XlsxFormulaCacheInspectionLimit): XlsxFormulaCacheInspectionLimit;

package/dist/formula-cache-reader.js

@@ -0,0 +1,350 @@
+import { translateFormulaReferences } from '@bilig/formula';
+import { decodeCellAddress, encodeCellAddress } from './address.js';
+import { closeStreamingNativeWorkbookCore, openStreamingNativeWorkbookCore, StreamingNativeWorkbookOpenError, } from './streaming-native-workbook-core.js';
+import { decodeXmlText, getXmlElementText, readXmlAttribute } from './xml.js';
+import { forEachInflatedXlsxZipEntryChunk } from './zip-reader.js';
+export class XlsxFormulaCacheReadError extends Error {
+    reason;
+    inputBytes;
+    constructor(message, reason, inputBytes) {
+        super(message);
+        this.name = 'XlsxFormulaCacheReadError';
+        this.reason = reason;
+        this.inputBytes = inputBytes;
+    }
+}
+const textDecoder = new TextDecoder();
+const formulaElementPattern = /<((?:[A-Za-z_][\w.-]*:)?f)\b(?:[^>"']|"[^"]*"|'[^']*')*(?:\/>|>[\s\S]*?<\/\1>)/u;
+const worksheetCellStartTagPattern = /<(?:[A-Za-z_][\w.-]*:)?c\b/u;
+const worksheetCellCarryLength = 128;
+export const defaultXlsxFormulaCacheInspectionLimit = 2000;
+export function readXlsxFormulaCacheCellsFromFile(inputPath, options = {}) {
+    let core;
+    try {
+        core = openStreamingNativeWorkbookCore(inputPath, {
+            onPhase: (phase) => options.onPhase?.(phase),
+        });
+    }
+    catch (error) {
+        if (error instanceof StreamingNativeWorkbookOpenError) {
+            throw new XlsxFormulaCacheReadError(error.message, error.reason, error.inputBytes);
+        }
+        throw error;
+    }
+    try {
+        const scan = options.inspectLimit === undefined
+            ? readXlsxFormulaCacheCellsFromWorkbookCore(core)
+            : readXlsxFormulaCacheCellsFromWorkbookCore(core, { inspectLimit: options.inspectLimit });
+        options.onPhase?.('formula-cache-scan');
+        return scan;
+    }
+    finally {
+        closeStreamingNativeWorkbookCore(core);
+    }
+}
+export function readXlsxFormulaCacheCellsFromWorkbookCore(core, options = {}) {
+    const scan = collectXlsxFormulaCacheCells(core.zip, core.sheetEntries, normalizeXlsxFormulaCacheInspectionLimit(options.inspectLimit ?? defaultXlsxFormulaCacheInspectionLimit), core.inputBytes);
+    return {
+        inputBytes: core.inputBytes,
+        sheetNames: core.sheetNames,
+        formulaCellCount: scan.formulaCellCount,
+        cells: scan.cells,
+    };
+}
+export function normalizeXlsxFormulaCacheInspectionLimit(limit) {
+    if (limit === 'all') {
+        return limit;
+    }
+    if (Number.isInteger(limit) && limit > 0) {
+        return limit;
+    }
+    throw new Error(`Expected inspectLimit to be "all" or a positive integer, received: ${String(limit)}`);
+}
+function collectXlsxFormulaCacheCells(zip, sheetEntries, inspectionLimit, inputBytes) {
+    const pendingCells = [];
+    const sharedStringIndexes = new Set();
+    let formulaCellCount = 0;
+    let collectedCellCount = 0;
+    const shouldCollect = () => inspectionLimit === 'all' || collectedCellCount < inspectionLimit;
+    const markCollected = () => {
+        collectedCellCount += 1;
+    };
+    for (const sheet of sheetEntries) {
+        const scan = collectXlsxFormulaCacheCellsForSheet(zip, sheet.name, sheet.path, shouldCollect, markCollected, sharedStringIndexes, inputBytes);
+        formulaCellCount += scan.formulaCellCount;
+        for (const cell of scan.cells) {
+            pendingCells.push(cell);
+        }
+    }
+    const sharedStrings = readTargetSharedStrings(zip, sharedStringIndexes);
+    return {
+        formulaCellCount,
+        cells: pendingCells.map((cell) => {
+            const output = {
+                target: cell.target,
+                formula: cell.formula,
+            };
+            if (cell.cachedValue !== undefined) {
+                output.cachedValue = literalValueForPendingCacheInspection(cell.cachedValue, sharedStrings);
+            }
+            return output;
+        }),
+    };
+}
+function collectXlsxFormulaCacheCellsForSheet(zip, sheetName, sheetPath, shouldCollect, markCollected, sharedStringIndexes, inputBytes) {
+    const sharedFormulaMasters = new Map();
+    const cells = [];
+    let formulaCellCount = 0;
+    let buffer = '';
+    const processBuffer = (final) => {
+        let cell = shiftWorksheetCellXml(buffer, final);
+        while (cell.status === 'cell') {
+            buffer = cell.buffer;
+            const { cellXml, openingTag } = cell;
+            const addressText = openingTag ? readXmlAttribute(openingTag, 'r') : null;
+            if (addressText) {
+                let decodedAddress;
+                try {
+                    decodedAddress = decodeCellAddress(addressText);
+                }
+                catch {
+                    decodedAddress = null;
+                }
+                const formula = decodedAddress ? readFormulaInfo(cellXml) : null;
+                if (decodedAddress && formula) {
+                    formulaCellCount += 1;
+                    if (formula.sharedFormulaIndex && formula.formula) {
+                        sharedFormulaMasters.set(formula.sharedFormulaIndex, {
+                            formula: formula.formula,
+                            row: decodedAddress.r,
+                            col: decodedAddress.c,
+                        });
+                    }
+                    if (shouldCollect()) {
+                        const formulaText = formulaSourceForCacheInspection(formula, sharedFormulaMasters, decodedAddress.r, decodedAddress.c);
+                        const cachedValue = cachedValueForFormulaCacheInspection(cellXml, openingTag, sharedStringIndexes);
+                        cells.push({
+                            target: formatQualifiedTarget(sheetName, encodeCellAddress(decodedAddress)),
+                            formula: formulaText.startsWith('=') ? formulaText : `=${formulaText}`,
+                            ...(cachedValue === undefined ? {} : { cachedValue }),
+                        });
+                        markCollected();
+                    }
+                }
+            }
+            cell = shiftWorksheetCellXml(buffer, final);
+        }
+        buffer = cell.status === 'pending' ? cell.buffer : '';
+    };
+    const streamed = forEachInflatedXlsxZipEntryChunk(zip, sheetPath, (chunk) => {
+        buffer += textDecoder.decode(chunk, { stream: true });
+        processBuffer(false);
+    }, { chunkSize: 64 * 1024, forceStreamingInflate: true });
+    if (!streamed) {
+        throw new XlsxFormulaCacheReadError(`Unable to stream worksheet XML for ${sheetName}`, 'worksheet-stream-unavailable', inputBytes);
+    }
+    buffer += textDecoder.decode();
+    processBuffer(true);
+    return { formulaCellCount, cells };
+}
+function shiftWorksheetCellXml(buffer, final) {
+    const startMatch = worksheetCellStartTagPattern.exec(buffer);
+    if (!startMatch) {
+        return {
+            status: final ? 'done' : 'pending',
+            buffer: final ? '' : buffer.slice(Math.max(0, buffer.length - worksheetCellCarryLength)),
+        };
+    }
+    const startIndex = startMatch.index;
+    const openingEnd = findXmlTagEnd(buffer, startIndex);
+    if (openingEnd < 0) {
+        return { status: 'pending', buffer: buffer.slice(startIndex) };
+    }
+    const openingTag = buffer.slice(startIndex, openingEnd + 1);
+    const endIndex = openingTag.endsWith('/>') ? openingEnd + 1 : findXmlElementEnd(buffer, openingEnd + 1, openingTag);
+    if (endIndex < 0) {
+        return { status: 'pending', buffer: buffer.slice(startIndex) };
+    }
+    return {
+        status: 'cell',
+        cellXml: buffer.slice(startIndex, endIndex),
+        openingTag,
+        buffer: buffer.slice(endIndex),
+    };
+}
+function findXmlTagEnd(xml, startIndex) {
+    let quote = null;
+    for (let index = startIndex; index < xml.length; index += 1) {
+        const char = xml[index];
+        if (quote) {
+            if (char === quote) {
+                quote = null;
+            }
+        }
+        else if (char === '"' || char === "'") {
+            quote = char;
+        }
+        else if (char === '>') {
+            return index;
+        }
+    }
+    return -1;
+}
+function findXmlElementEnd(xml, startIndex, openingTag) {
+    const tagName = /^<((?:[A-Za-z_][\w.-]*:)?c)\b/u.exec(openingTag)?.[1];
+    if (!tagName) {
+        return -1;
+    }
+    const closingPattern = new RegExp(`</${escapeRegExp(tagName)}\\s*>`, 'u');
+    const relativeMatch = closingPattern.exec(xml.slice(startIndex));
+    return relativeMatch ? startIndex + relativeMatch.index + relativeMatch[0].length : -1;
+}
+function readFormulaInfo(cellXml) {
+    const formulaXml = formulaElementPattern.exec(cellXml)?.[0];
+    if (!formulaXml) {
+        return null;
+    }
+    const openingEnd = formulaXml.indexOf('>');
+    const openingTag = openingEnd >= 0 ? formulaXml.slice(0, openingEnd + 1) : formulaXml;
+    const sharedFormulaIndex = readXmlAttribute(openingTag, 'si');
+    const formula = formulaXml.endsWith('/>') || openingEnd < 0
+        ? null
+        : decodeXmlText(formulaXml.slice(openingEnd + 1, formulaXml.replace(/<\/(?:[A-Za-z_][\w.-]*:)?f>\s*$/u, '').length));
+    return {
+        formula: formula && formula.trim().length > 0 ? formula : null,
+        sharedFormulaIndex,
+    };
+}
+function formulaSourceForCacheInspection(formula, sharedFormulaMasters, row, col) {
+    if (formula.formula) {
+        return formula.formula;
+    }
+    if (!formula.sharedFormulaIndex) {
+        return '';
+    }
+    const master = sharedFormulaMasters.get(formula.sharedFormulaIndex);
+    return master ? translateFormulaReferences(master.formula, row - master.row, col - master.col) : '';
+}
+function cachedValueForFormulaCacheInspection(cellXml, openingTag, sharedStringIndexes) {
+    if (getXmlElementText(cellXml, 'v') === null && readXmlAttribute(openingTag, 't') !== 'inlineStr') {
+        return undefined;
+    }
+    const value = readCellValue(cellXml, openingTag);
+    if (isSharedStringReference(value)) {
+        sharedStringIndexes.add(value.index);
+    }
+    return value;
+}
+function readCellValue(cellXml, openingTag) {
+    const type = readXmlAttribute(openingTag, 't');
+    if (type === 'inlineStr') {
+        return { kind: 'string', value: readTextRuns(cellXml) };
+    }
+    const rawValue = getXmlElementText(cellXml, 'v');
+    if (rawValue === null) {
+        return { kind: 'empty' };
+    }
+    if (type === 's') {
+        const index = Number(rawValue);
+        return Number.isSafeInteger(index) && index >= 0 ? { kind: 'shared-string', index } : { kind: 'empty' };
+    }
+    if (type === 'str') {
+        return { kind: 'string', value: decodeXmlText(rawValue) };
+    }
+    if (type === 'b') {
+        return { kind: 'boolean', value: rawValue === '1' || rawValue.toLowerCase() === 'true' };
+    }
+    if (type === 'e') {
+        return { kind: 'error', value: normalizeErrorText(decodeXmlText(rawValue)) };
+    }
+    const numeric = Number(rawValue);
+    return Number.isFinite(numeric) ? { kind: 'number', value: numeric } : { kind: 'string', value: decodeXmlText(rawValue) };
+}
+function literalValueForPendingCacheInspection(value, sharedStrings) {
+    switch (value.kind) {
+        case 'shared-string':
+            return sharedStrings.get(value.index) ?? '';
+        case 'empty':
+            return null;
+        case 'number':
+            return value.value;
+        case 'boolean':
+            return value.value;
+        case 'string':
+            return value.value;
+        case 'error':
+            return value.value;
+    }
+}
+function readTargetSharedStrings(zip, targetIndexes) {
+    const values = new Map();
+    if (targetIndexes.size === 0) {
+        return values;
+    }
+    let buffer = '';
+    let index = 0;
+    const processBuffer = (final) => {
+        const safeEnd = final ? buffer.length : Math.max(0, buffer.lastIndexOf('<si'));
+        if (safeEnd === 0 && !final) {
+            return true;
+        }
+        const safeXml = buffer.slice(0, safeEnd);
+        for (const match of safeXml.matchAll(/<((?:[A-Za-z_][\w.-]*:)?si)\b(?:[^>"']|"[^"]*"|'[^']*')*>[\s\S]*?<\/\1>/gu)) {
+            if (targetIndexes.has(index)) {
+                values.set(index, readTextRuns(match[0]));
+            }
+            index += 1;
+        }
+        buffer = buffer.slice(safeEnd);
+        return values.size < targetIndexes.size;
+    };
+    const streamed = forEachInflatedXlsxZipEntryChunk(zip, 'xl/sharedStrings.xml', (chunk) => {
+        buffer += textDecoder.decode(chunk, { stream: true });
+        return processBuffer(false);
+    }, { chunkSize: 64 * 1024, forceStreamingInflate: true });
+    if (!streamed) {
+        return values;
+    }
+    buffer += textDecoder.decode();
+    processBuffer(true);
+    return values;
+}
+function isSharedStringReference(value) {
+    return value.kind === 'shared-string';
+}
+function formatQualifiedTarget(sheetName, address) {
+    return `${quoteSheetName(sheetName)}!${address}`;
+}
+function quoteSheetName(sheetName) {
+    return /^[A-Za-z_][A-Za-z0-9_]*$/u.test(sheetName) ? sheetName : `'${sheetName.replaceAll("'", "''")}'`;
+}
+function normalizeErrorText(value) {
+    switch (value.toUpperCase()) {
+        case '#DIV/0!':
+            return '#DIV/0!';
+        case '#REF!':
+            return '#REF!';
+        case '#VALUE!':
+            return '#VALUE!';
+        case '#NAME?':
+            return '#NAME?';
+        case '#N/A':
+            return '#N/A';
+        case '#NUM!':
+            return '#NUM!';
+        case '#FIELD!':
+            return '#FIELD!';
+        case '#NULL!':
+            return '#NULL!';
+        default:
+            return '#VALUE!';
+    }
+}
+function readTextRuns(xml) {
+    const runs = [...xml.matchAll(/<(?:[A-Za-z_][\w.-]*:)?t\b(?:[^>"']|"[^"]*"|'[^']*')*>([\s\S]*?)<\/(?:[A-Za-z_][\w.-]*:)?t>/gu)].map((match) => decodeXmlText(match[1] ?? ''));
+    return runs.length > 0 ? runs.join('') : '';
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+}
+//# sourceMappingURL=formula-cache-reader.js.map