@shbernal/ts-xlsx 3.0.0 → 3.2.0

package/dist/io/opc/inflate.js

@@ -1,5 +1,6 @@
 import { Unzip, UnzipInflate } from 'fflate';
 import { concat } from '../../bytes.js';
+import { quoted } from '../../errors.js';
 import { PackageReadError } from './errors.js';
 const INPUT_SLICE = 1 << 14;
 export function inflatePackage(data, cap) {
@@ -7,6 +8,12 @@ export function inflatePackage(data, cap) {
     let total = 0;
     let failure;
     const unzip = new Unzip((file) => {
+        if (!isPartName(file.name)) {
+            failure ??= new PackageReadError(`illegal part name ${quoted(file.name)} in package`);
+        }
+        else if (file.name in files) {
+            failure ??= new PackageReadError(`duplicate part ${quoted(file.name)} in package`);
+        }
         const chunks = [];
         let size = 0;
         file.ondata = (error, chunk, final) => {
@@ -44,3 +51,10 @@ export function inflatePackage(data, cap) {
         throw failure;
     return files;
 }
+function isPartName(name) {
+    if (name === '' || name.startsWith('/') || name.includes('\\'))
+        return false;
+    if (/^[A-Za-z]:/.test(name))
+        return false;
+    return !name.split('/').includes('..');
+}

package/dist/io/opc/namespaces.d.ts

@@ -6,6 +6,8 @@
  * The SpreadsheetML vocabulary (the main namespace, DrawingML, the Microsoft extension URIs) is a
  * property of the XML codec and lives in `../xlsx/namespaces.ts`.
  */
+import type { NamespaceScope } from '../../xml/xml-namespaces.ts';
+import { type XmlAttributes } from '../../xml/xml-scan.ts';
 /** The `xmlns` of every `.rels` package relationships part. */
 export declare const PKG_RELS_NS = "http://schemas.openxmlformats.org/package/2006/relationships";
 /** The `xmlns` of the package's `[Content_Types].xml`. */
@@ -16,3 +18,17 @@ export declare const CONTENT_TYPES_NS = "http://schemas.openxmlformats.org/packa
  * the relationship graph is written in, so it belongs with the graph and not with either codec.
  */
 export declare const RELATIONSHIPS_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+/**
+ * A relationship attribute (`r:id`, `r:embed`) resolved by namespace rather than by prefix.
+ *
+ * A workbook may bind {@link RELATIONSHIPS_NS} to any prefix it likes, and real toolchains do: reading
+ * the literal `attrs['r:id']` lost every sheet relationship in such a file, so the sheets loaded
+ * permanently empty with no error.
+ *
+ * Falls back to the conventional `r:` spelling when the prefix is not bound anywhere in scope. That is
+ * not laxity for its own sake: a part carrying `r:embed` without declaring `r` is malformed XML that
+ * this scanner does not reject, it was read before, and refusing it now would lose a file to a fix
+ * meant to gain files. Resolution by namespace comes first, so a file that binds `r:` to something
+ * else is read correctly rather than by its prefix.
+ */
+export declare function relAttr(scope: NamespaceScope, attrs: XmlAttributes, local: string): string | undefined;

package/dist/io/opc/namespaces.js

@@ -1,3 +1,7 @@
+import {} from '../../xml/xml-scan.js';
 export const PKG_RELS_NS = 'http://schemas.openxmlformats.org/package/2006/relationships';
 export const CONTENT_TYPES_NS = 'http://schemas.openxmlformats.org/package/2006/content-types';
 export const RELATIONSHIPS_NS = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships';
+export function relAttr(scope, attrs, local) {
+    return scope.attr(attrs, RELATIONSHIPS_NS, local) ?? attrs[`r:${local}`];
+}

package/dist/io/opc/part-paths.d.ts

@@ -1,4 +1,13 @@
 export declare const THEME_PART_PATH = "xl/theme/theme1.xml";
+/**
+ * The extension of a part path (`xl/media/image1.JPEG` → `jpeg`), or `''` when it carries none.
+ *
+ * Lower-cased here rather than by each caller. OPC extensions are case-insensitive, so an extension is
+ * only ever used as a key or compared against a literal, and every caller but one folded the case
+ * itself; the one that did not handed a raw `JPEG` to `addImage`, which folds later, so the same media
+ * type could reach `[Content_Types].xml` as two `<Default Extension>` entries. Folding once at the
+ * source is what makes the missed fold unrepresentable rather than merely unlikely.
+ */
 export declare function extensionOf(partPath: string): string;
 export declare function relsPathFor(partPath: string): string;
 export declare function relativePartPath(fromPath: string, toPath: string): string;

package/dist/io/opc/part-paths.js

@@ -2,7 +2,7 @@ export const THEME_PART_PATH = 'xl/theme/theme1.xml';
 export function extensionOf(partPath) {
     const dot = partPath.lastIndexOf('.');
     const slash = partPath.lastIndexOf('/');
-    return dot > slash ? partPath.slice(dot + 1) : '';
+    return dot > slash ? partPath.slice(dot + 1).toLowerCase() : '';
 }
 export function relsPathFor(partPath) {
     const slash = partPath.lastIndexOf('/');
@@ -23,11 +23,11 @@ export function relativePartPath(fromPath, toPath) {
     return [...Array(up).fill('..'), ...toSegments.slice(common)].join('/');
 }
 export function resolveRelativePart(basePart, target) {
-    if (target.startsWith('/'))
-        return target.slice(1);
-    const baseDir = basePart.slice(0, basePart.lastIndexOf('/') + 1);
+    const joined = target.startsWith('/')
+        ? target
+        : `${basePart.slice(0, basePart.lastIndexOf('/') + 1)}${target}`;
     const out = [];
-    for (const segment of `${baseDir}${target}`.split('/')) {
+    for (const segment of joined.split('/')) {
         if (segment === '' || segment === '.')
             continue;
         if (segment === '..')

package/dist/io/opc/read-opc.d.ts

@@ -5,23 +5,36 @@ export interface PackageAccessors {
     partText: (path: string) => string | undefined;
     /** A part's raw bytes, or undefined when the package holds no such part. */
     partBytes: (path: string) => Uint8Array | undefined;
+    /** The package's own spelling of the part the other two would answer for `path`, or undefined when
+     * there is none: the key an editor replaces or deletes, so it acts on the entry a read found rather
+     * than adding a second one beside it. */
+    partKey: (path: string) => string | undefined;
 }
 /** A spreadsheet package opened for reading: inflated under the read bound, its parts bound to
- * accessors, and its XML office document read if it has one. */
+ * accessors, its office document located through the package's own relationship graph, and that
+ * document read if it is XML. */
 export interface OpenedSpreadsheet {
     /** The inflated parts, for a reader that hands the whole package on to another codec. */
     readonly files: Record<string, Uint8Array>;
     readonly pkg: PackageAccessors;
-    /** `xl/workbook.xml`, or undefined when the package carries no XML office document (a `.xlsb`
-     * carries `xl/workbook.bin` instead). Each entry point answers that case for itself: they
-     * genuinely want different answers, and the difference is documented where they diverge. */
+    /**
+     * Where this package keeps its office document, resolved through `_rels/.rels`. Conventionally
+     * `xl/workbook.xml` (or `xl/workbook.bin` for a `.xlsb`), but the convention is Excel's habit
+     * rather than the format's rule, and a package is free to name the part anything its root
+     * relationship points at.
+     */
+    readonly documentPath: string;
+    /** The office document's text, or undefined when the package's document is not XML (a `.xlsb`
+     * carries a BIFF12 part instead). Each entry point answers that case for itself: they genuinely
+     * want different answers, and the difference is documented where they diverge. */
     readonly workbookXml: string | undefined;
 }
 /**
- * Open a spreadsheet package: the six-step preamble every reader shares, and in particular the two
+ * Open a spreadsheet package: the six-step preamble every reader shares, and in particular the three
  * decisions worth having exactly one of. The inflate bound is a security decision (an unbounded
- * inflate is a zip bomb) and "does this package carry an XML office document" is the dispatch
- * decision between the two codecs, so neither should be restated once per entry point.
+ * inflate is a zip bomb), *where the office document lives* is a question only the package can
+ * answer, and "is that document XML" is the dispatch decision between the two codecs. None should be
+ * restated once per entry point.
  *
  * It deliberately stops short of the shared strings and the style table: those are codec-specific
  * (`xl/sharedStrings.xml` against BIFF12's own record stream), and lifting them here would put
@@ -29,8 +42,6 @@ export interface OpenedSpreadsheet {
  */
 export declare function openSpreadsheetPackage(data: Uint8Array, maxUncompressedBytes: number | undefined): OpenedSpreadsheet;
 export declare function packageAccessors(files: Record<string, Uint8Array>): PackageAccessors;
-export declare function relationshipTargetByType(xml: string, suffix: string): string | undefined;
-export declare function relationshipTargetsByType(xml: string, suffix: string): string[];
 export interface RelationshipRecord {
     readonly id: string;
     readonly type: string;
@@ -46,14 +57,47 @@ export interface PartRelationships {
     byId(id: string): RelationshipRecord | undefined;
     /** Resolve one of this part's targets against the part's own directory. */
     pathOf(target: string): string;
-    /** The package part reached through the first relationship whose Type ends with `/<suffix>`, or
+    /** The package part reached through the first relationship of this class ({@link isRelType}), or
      * undefined when the part declares none: the single-part lookup (notes, printer settings, drawing,
      * background) in one call. */
-    targetPath(suffix: string): string | undefined;
-    /** Every package part reached through a relationship of this type, in declaration order. For a part
+    targetPath(name: string): string | undefined;
+    /** Every package part reached through a relationship of this class, in declaration order. For a part
      * class one sheet may reference more than once (tables, pivot tables). */
-    targetPaths(suffix: string): string[];
+    targetPaths(name: string): string[];
+    /**
+     * The text of the single part reached through a relationship of this type, or `undefined` when the
+     * part declares no such relationship *or* names one the package does not contain.
+     *
+     * Those two are deliberately one answer. A relationship pointing at an absent part is a damaged
+     * package, and every reader here answers a damaged package the same way Excel does: the feature is
+     * simply not there, rather than the load failing over it. Collapsing `targetPath` then `partText`
+     * into one call is what lets that contract be stated once instead of at each of the seven places
+     * that used to spell it out.
+     */
+    relatedText(name: string): string | undefined;
+    /** As {@link relatedText}, for a part whose content is opaque bytes (a printer-settings blob, an
+     * image) rather than XML. */
+    relatedBytes(name: string): Uint8Array | undefined;
+    /**
+     * The text of a part reached through the relationship that names it, falling back to
+     * `conventionalPath` only when the part declares no such relationship, and to `''` when neither
+     * resolves.
+     *
+     * The order is the whole point, and it decides more than where a lookup lands. A package is free
+     * to name any part anything -- the workbook part included -- so the part's own relationships are
+     * what say where its pool and its stylesheet live. Resolved conventional-path-first, a renamed
+     * pool reads as no pooled strings at all, and a renamed stylesheet silently changes cell *types*,
+     * because the date test reads `numFmt` off the resolved style to tell `45000` from a date. The
+     * conventional path stays as the fallback for a package whose rels are damaged.
+     *
+     * The `''` is a real package state, not a lookup that failed quietly: a workbook may carry no pool
+     * and no stylesheet, and every reader of these parses the empty text into the empty table it would
+     * have built anyway. Stated here so the two readers that resolve these parts cannot answer the
+     * same package differently -- a streamed read must not decode a cell differently from a buffered
+     * one.
+     */
+    relatedTextOrPath(name: string, conventionalPath: string): string;
 }
-export declare function readPartRelationships(partPath: string, partText: (path: string) => string | undefined): PartRelationships;
+export declare function readPartRelationships(partPath: string, partText: (path: string) => string | undefined, partBytes?: (path: string) => Uint8Array | undefined): PartRelationships;
 export declare function contentTypeResolver(contentTypesXml: string): (path: string) => string;
 export declare function capturePartClosure(entryPath: string, partText: (path: string) => string | undefined, partBytes: (path: string) => Uint8Array | undefined, contentTypeOf: (path: string) => string): readonly PreservedPart[] | undefined;

package/dist/io/opc/read-opc.js

@@ -1,37 +1,52 @@
 import { strFromU8 } from 'fflate';
+import { isRelType } from '../../rel-type.js';
 import { openElements } from '../../xml/xml-read.js';
 import { extensionOf, relsPathFor, resolveRelativePart } from './part-paths.js';
 import { DEFAULT_MAX_UNCOMPRESSED } from './read-options.js';
 import { inflateSpreadsheetPackage } from './sniff-format.js';
+import { transitionalRelationshipType } from './strict-relationships.js';
 export function openSpreadsheetPackage(data, maxUncompressedBytes) {
     const files = inflateSpreadsheetPackage(data, maxUncompressedBytes ?? DEFAULT_MAX_UNCOMPRESSED);
     const pkg = packageAccessors(files);
-    return { files, pkg, workbookXml: pkg.partText('xl/workbook.xml') };
+    const documentPath = readPartRelationships('', pkg.partText).targetPath(OFFICE_DOCUMENT_REL) ??
+        conventionalDocument(pkg);
+    const workbookXml = extensionOf(documentPath) === 'xml' ? pkg.partText(documentPath) : undefined;
+    return { files, pkg, documentPath, workbookXml };
+}
+const OFFICE_DOCUMENT_REL = 'officeDocument';
+const CONVENTIONAL_DOCUMENTS = ['xl/workbook.xml', 'xl/workbook.bin'];
+function conventionalDocument(pkg) {
+    return (CONVENTIONAL_DOCUMENTS.find((path) => pkg.partBytes(path) !== undefined) ??
+        CONVENTIONAL_DOCUMENTS[0]);
 }
 export function packageAccessors(files) {
+    const folded = new Map();
+    for (const path of Object.keys(files)) {
+        const key = path.toLowerCase();
+        if (!folded.has(key))
+            folded.set(key, path);
+    }
+    const partKey = (path) => files[path] === undefined ? folded.get(path.toLowerCase()) : path;
+    const lookup = (path) => {
+        const key = partKey(path);
+        return key === undefined ? undefined : files[key];
+    };
     return {
         partText: (path) => {
-            const bytes = files[path];
+            const bytes = lookup(path);
             return bytes === undefined ? undefined : strFromU8(bytes);
         },
-        partBytes: (path) => files[path],
+        partBytes: lookup,
+        partKey,
     };
 }
-export function relationshipTargetByType(xml, suffix) {
-    return relationshipTargetsByType(xml, suffix)[0];
-}
-export function relationshipTargetsByType(xml, suffix) {
-    return parseRelationshipRecords(xml)
-        .filter((record) => record.type.endsWith(`/${suffix}`))
-        .map((record) => record.target);
-}
 export function parseRelationshipRecords(xml) {
     const records = [];
     for (const { attrs } of openElements(xml, 'Relationship')) {
         if (attrs.Id !== undefined && attrs.Type !== undefined && attrs.Target !== undefined) {
             records.push({
                 id: attrs.Id,
-                type: attrs.Type,
+                type: transitionalRelationshipType(attrs.Type),
                 target: attrs.Target,
                 external: attrs.TargetMode === 'External',
             });
@@ -39,17 +54,30 @@ export function parseRelationshipRecords(xml) {
     }
     return records;
 }
-export function readPartRelationships(partPath, partText) {
+export function readPartRelationships(partPath, partText, partBytes) {
     const records = parseRelationshipRecords(partText(relsPathFor(partPath)) ?? '');
     const byId = new Map(records.map((record) => [record.id, record]));
     const pathOf = (target) => resolveRelativePart(partPath, target);
-    const targetsOf = (suffix) => records.filter((record) => record.type.endsWith(`/${suffix}`)).map((record) => record.target);
+    const targetsOf = (name) => records.filter((record) => isRelType(record.type, name)).map((record) => record.target);
+    const targetPath = (name) => targetsOf(name).map(pathOf)[0];
     return {
         records,
         byId: (id) => byId.get(id),
         pathOf,
-        targetPath: (suffix) => targetsOf(suffix).map(pathOf)[0],
-        targetPaths: (suffix) => targetsOf(suffix).map(pathOf),
+        targetPath,
+        targetPaths: (name) => targetsOf(name).map(pathOf),
+        relatedText: (name) => {
+            const path = targetPath(name);
+            return path === undefined ? undefined : partText(path);
+        },
+        relatedBytes: (name) => {
+            const path = targetPath(name);
+            return path === undefined ? undefined : partBytes?.(path);
+        },
+        relatedTextOrPath: (name, conventionalPath) => {
+            const path = targetPath(name);
+            return (path === undefined ? undefined : partText(path)) ?? partText(conventionalPath) ?? '';
+        },
     };
 }
 export function contentTypeResolver(contentTypesXml) {
@@ -57,7 +85,7 @@ export function contentTypeResolver(contentTypesXml) {
     const defaults = new Map();
     for (const { local, attrs } of openElements(contentTypesXml, 'Override', 'Default')) {
         if (local === 'Override' && attrs.PartName !== undefined && attrs.ContentType !== undefined) {
-            overrides.set(attrs.PartName, attrs.ContentType);
+            overrides.set(attrs.PartName.toLowerCase(), attrs.ContentType);
         }
         else if (local === 'Default' &&
             attrs.Extension !== undefined &&
@@ -65,16 +93,16 @@ export function contentTypeResolver(contentTypesXml) {
             defaults.set(attrs.Extension.toLowerCase(), attrs.ContentType);
         }
     }
-    return (path) => overrides.get(`/${path}`) ??
-        defaults.get(extensionOf(path).toLowerCase()) ??
+    return (path) => overrides.get(`/${path}`.toLowerCase()) ??
+        defaults.get(extensionOf(path)) ??
         'application/octet-stream';
 }
 export function capturePartClosure(entryPath, partText, partBytes, contentTypeOf) {
     const parts = [];
     const visited = new Set();
     const queue = [entryPath];
-    while (queue.length > 0) {
-        const path = queue.shift();
+    for (let next = 0; next < queue.length; next++) {
+        const path = queue[next];
         if (path === undefined || visited.has(path))
             continue;
         visited.add(path);

package/dist/io/opc/read-options.d.ts

@@ -1,4 +1,8 @@
-export interface ReadXlsxOptions {
+/**
+ * How a reader is allowed to open an OPC package. One knob today: the ceiling on what inflating it
+ * may produce, which every reader shares because every reader inflates the same container.
+ */
+export interface ReadPackageOptions {
     /**
      * Maximum total uncompressed output, in bytes, produced while inflating the package.
      * The bound is enforced by a running counter as bytes are decompressed, never read from

package/dist/io/opc/sniff-format.d.ts

@@ -17,11 +17,11 @@ export declare function sniffContainer(data: Uint8Array): Container;
  */
 export declare function inflateSpreadsheetPackage(data: Uint8Array, cap: number): Record<string, Uint8Array>;
 /**
- * The typed error for an inflated package that carries no `xl/workbook.xml`: a `.xlsb` if its binary
- * `xl/workbook.bin` office document is present, otherwise an unrecognised (non-workbook) ZIP.
+ * The typed error for an inflated package whose office document is not XML: a `.xlsb` if that
+ * document is present as binary, otherwise an unrecognised (non-workbook) ZIP.
  *
  * The `.xlsb` branch takes the caller's own explanation, because whether a binary workbook is
  * readable now depends on *which* entry point was asked: `readXlsx` reads one, the row streamer
  * cannot yet. A single baked-in "not supported" message would be wrong for one of them.
  */
-export declare function unsupportedWorkbookPart(partText: (path: string) => string | undefined, xlsbMessage: string): UnsupportedFormatError;
+export declare function unsupportedWorkbookPart(partBytes: (path: string) => Uint8Array | undefined, documentPath: string, xlsbMessage: string): UnsupportedFormatError;

package/dist/io/opc/sniff-format.js

@@ -34,8 +34,8 @@ export function inflateSpreadsheetPackage(data, cap) {
         throw new PackageReadError('not a readable .xlsx package: the ZIP container is corrupt or truncated and could not be inflated');
     }
 }
-export function unsupportedWorkbookPart(partText, xlsbMessage) {
-    if (partText('xl/workbook.bin') !== undefined) {
+export function unsupportedWorkbookPart(partBytes, documentPath, xlsbMessage) {
+    if (partBytes(documentPath) !== undefined) {
         return new UnsupportedFormatError('xlsb', xlsbMessage);
     }
     return new UnsupportedFormatError('unknown');

package/dist/io/opc/strict-relationships.d.ts

@@ -0,0 +1,2 @@
+/** A relationship type in its Transitional spelling: a Strict one translated, any other as it is. */
+export declare function transitionalRelationshipType(type: string): string;

package/dist/io/opc/strict-relationships.js

@@ -0,0 +1,12 @@
+const STRICT_RELATIONSHIPS = 'http://purl.oclc.org/ooxml/officeDocument/relationships/';
+const TRANSITIONAL_RELATIONSHIPS = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/';
+const RENAMED = new Map([
+    ['extendedProperties', 'extended-properties'],
+    ['customProperties', 'custom-properties'],
+]);
+export function transitionalRelationshipType(type) {
+    if (!type.startsWith(STRICT_RELATIONSHIPS))
+        return type;
+    const name = type.slice(STRICT_RELATIONSHIPS.length);
+    return `${TRANSITIONAL_RELATIONSHIPS}${RENAMED.get(name) ?? name}`;
+}

package/dist/io/read-policy/column-budget.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A per-sheet allowance of column touches, spent by each column run the reader applies.
+ *
+ * A run past the allowance is truncated, and one starting past it is dropped, rather than the read
+ * being refused: that is the stance every reader already takes on an out-of-grid run, and it means a
+ * hostile file loses formatting it could not have meant while a real one is untouched.
+ */
+export declare class ColumnRecordBudget {
+    #private;
+    /** The last column of `[first, last]` this sheet can still afford, or `undefined` when none is. */
+    take(first: number, last: number): number | undefined;
+}
+/**
+ * The columns of a declared run `[first, last]`, one-based, that a sheet actually applies, or
+ * `undefined` for a run that applies to none: one starting past the grid, an empty one, or one the
+ * budget can no longer afford.
+ *
+ * Beside the budget because the two decisions are one decision. The XML readers each had their own
+ * copy, and the copies had already drifted: one tested `first > MAX_COLUMN` and the other did not,
+ * which happened not to matter only because `budget.take` returns `undefined` when `first > last`, an
+ * accident of that method's contract rather than an agreement between the readers.
+ */
+export declare function clampColumnSpan(first: number, last: number, budget: ColumnRecordBudget): {
+    first: number;
+    last: number;
+} | undefined;

package/dist/io/read-policy/column-budget.js

@@ -0,0 +1,18 @@
+import { MAX_COLUMN } from '../../core/address.js';
+const MAX_COLUMN_RECORD_TOUCHES = MAX_COLUMN * 4;
+export class ColumnRecordBudget {
+    #remaining = MAX_COLUMN_RECORD_TOUCHES;
+    take(first, last) {
+        if (this.#remaining <= 0 || first > last)
+            return undefined;
+        const affordable = Math.min(last, first + this.#remaining - 1);
+        this.#remaining -= affordable - first + 1;
+        return affordable;
+    }
+}
+export function clampColumnSpan(first, last, budget) {
+    if (first > MAX_COLUMN)
+        return undefined;
+    const affordable = budget.take(first, Math.min(last, MAX_COLUMN));
+    return affordable === undefined ? undefined : { first, last: affordable };
+}

package/dist/io/read-policy/read-repair.d.ts

@@ -0,0 +1,74 @@
+import { type FormulaPlacement } from '../../core/array-formula-ranges.ts';
+import type { Worksheet } from '../../core/worksheet.ts';
+/**
+ * A sheet name from a file, rewritten into one the model will accept.
+ *
+ * Excel's own repair, in the order the constraints interact: forbidden characters go first (they
+ * can be anywhere), then the length ceiling, then the apostrophe rule *again*, because truncating
+ * can expose an interior apostrophe at the new edge. An empty result becomes `Sheet{n}`, and a
+ * collision takes a ` (2)` suffix that is itself made to fit inside the 31-character limit.
+ *
+ * @param taken the lower-cased names already in the workbook; sheet names collide
+ *   case-insensitively, which is the comparison `Workbook.getWorksheet` makes.
+ */
+export declare function repairSheetName(name: string, taken: ReadonlySet<string>): string;
+/**
+ * A workbook's declared sheets in order, each carrying the name the model will accept: repaired by
+ * {@link repairSheetName} against every name repaired before it.
+ *
+ * Both codecs declare their sheets as an ordered list and both have to know the repaired names before
+ * anything cites a sheet by position, since a scoped defined name and a 3-D reference both index into
+ * that order. The loop threading the taken set through the list is one loop, so it is written once.
+ */
+export declare function repairedSheetNames<T extends {
+    readonly name: string;
+}>(declared: readonly T[]): T[];
+/**
+ * Read a sheet whose array formulas cannot stand as Excel repairs it (`core/array-formula-ranges.ts`). A
+ * file is free to carry an array formula whose range holds another formula, or shares a cell with another
+ * array formula's range, and the writer refuses both, since Excel offers to repair such a package.
+ *
+ * Excel 16.0 keeps the array formula decided first. A formula inside its range loses its formula and its
+ * value, keeping its style, and a shared formula whose master that was loses its formula too, keeping its
+ * value; an array formula whose range only shares cells with it loses its formula, keeping its value. The
+ * value Excel then shows in a cell it emptied is what the kept array formula computes there, which the
+ * library does not compute, so the cell is left empty.
+ */
+export declare function admitArrayRanges(sheet: Worksheet): void;
+/** What Excel's repair takes from a sheet whose array formulas cannot stand. */
+export interface ArrayRangeRepair {
+    /** Formulas whose cell lies in the range of an array formula kept: each loses its whole cell. */
+    readonly cellsRemoved: FormulaPlacement[];
+    /**
+     * Array formulas whose own cell lies in no range kept but whose range shares a cell with one: each loses
+     * its formula and keeps the value it cached.
+     */
+    readonly formulasRemoved: FormulaPlacement[];
+}
+/**
+ * What Excel's repair takes from the sheet, deciding in reading order: an array formula keeps its range
+ * unless that range shares a cell with a range kept before it. A formula of any kind whose cell lies in a
+ * kept range loses the cell; an array formula whose range shares a cell with a kept range, its own cell
+ * outside it, loses its formula and keeps its value. What is left holds no conflict.
+ *
+ * Excel 16.0 (build 20326) repaired B1:B3 holding a plain formula, or an array formula of its own, in B2
+ * by keeping B1's range and removing B2's "cell information", and B1:C2 beside A2:B3 by keeping B1's range
+ * and removing A2's "formula", its value left (`test/corpus/fixtures/excel-oracle/array-formula-ranges.json`).
+ * An array formula's own cell is the first of its range in reading order, so a range is always decided
+ * before any cell it holds, and a range whose formula was taken claims none.
+ */
+export declare function arrayRangeRepair(placements: Iterable<FormulaPlacement>): ArrayRangeRepair;
+/**
+ * Run a model call that is being handed foreign input, and answer `undefined` where the model
+ * refuses it.
+ *
+ * The three caught types are the three a model method raises *about its argument*: an
+ * `AuthoringError` for a composite that cannot exist, and the native `RangeError` / `SyntaxError`
+ * the taxonomy assigns to a single scalar that is out of range or does not parse. Every one of them
+ * is a statement about the caller, and on this path the caller is a file.
+ *
+ * Nothing else is caught. An `XlsxError` raised by a layer below is a real failure of the read and
+ * keeps its identity; an `InternalError` is a bug of ours and must not be swallowed by a reader
+ * being tolerant about somebody else's file.
+ */
+export declare function admitting<T>(build: () => T): T | undefined;

package/dist/io/read-policy/read-repair.js

@@ -0,0 +1,119 @@
+import { tryDecodeAnchoredRange } from '../../core/address.js';
+import { formulaPlacement } from '../../core/array-formula-ranges.js';
+import { INVALID_SHEET_NAME_CHARS, MAX_SHEET_NAME_LENGTH } from '../../core/limits.js';
+import { MergeIndex } from '../../core/merge-index.js';
+import { isFormulaValue, isSharedFormulaValue } from '../../core/value.js';
+import { AuthoringError } from '../../errors.js';
+const INVALID_SHEET_NAME_CHARS_GLOBAL = new RegExp(INVALID_SHEET_NAME_CHARS.source, 'g');
+export function repairSheetName(name, taken) {
+    const stripped = trimApostrophes(name.replace(INVALID_SHEET_NAME_CHARS_GLOBAL, '')).slice(0, MAX_SHEET_NAME_LENGTH);
+    const base = trimApostrophes(stripped);
+    if (base.length === 0)
+        return firstFree((n) => `Sheet${n}`, taken);
+    if (!taken.has(base.toLowerCase()))
+        return base;
+    return firstFree((n) => withSuffix(base, ` (${n})`), taken, 2);
+}
+export function repairedSheetNames(declared) {
+    const taken = new Set();
+    return declared.map((entry) => {
+        const name = repairSheetName(entry.name, taken);
+        taken.add(name.toLowerCase());
+        return { ...entry, name };
+    });
+}
+function trimApostrophes(name) {
+    return name.replace(/^'+/, '').replace(/'+$/, '');
+}
+function firstFree(candidate, taken, from = 1) {
+    for (let n = from;; n++) {
+        const name = candidate(n);
+        if (!taken.has(name.toLowerCase()))
+            return name;
+    }
+}
+function withSuffix(base, suffix) {
+    const room = MAX_SHEET_NAME_LENGTH - suffix.length;
+    return trimApostrophes(base.slice(0, room)) + suffix;
+}
+export function admitArrayRanges(sheet) {
+    const placements = [];
+    for (const { cells } of sheet.rows()) {
+        for (const cell of cells) {
+            const placement = formulaPlacement(cell.address, cell.col, cell.row, cell.value);
+            if (placement !== undefined)
+                placements.push(placement);
+        }
+    }
+    const { cellsRemoved, formulasRemoved } = arrayRangeRepair(placements);
+    if (cellsRemoved.length === 0 && formulasRemoved.length === 0)
+        return;
+    const mastersRemoved = new Set();
+    for (const { address } of cellsRemoved) {
+        const cell = sheet.getCell(address);
+        if (isFormulaValue(cell.value))
+            mastersRemoved.add(address);
+        cell.value = null;
+    }
+    for (const { address } of formulasRemoved) {
+        const cell = sheet.getCell(address);
+        cell.value = cachedResult(cell.value);
+    }
+    if (mastersRemoved.size === 0)
+        return;
+    for (const { cells } of sheet.rows()) {
+        for (const cell of cells) {
+            const value = cell.value;
+            if (isSharedFormulaValue(value) && mastersRemoved.has(value.sharedFormula)) {
+                cell.value = cachedResult(value);
+            }
+        }
+    }
+}
+export function arrayRangeRepair(placements) {
+    const ordered = [...placements].sort((a, b) => a.row - b.row || a.col - b.col);
+    const keptRanges = [];
+    const kept = new MergeIndex(keptRanges);
+    const cellsRemoved = [];
+    const formulasRemoved = [];
+    for (const placement of ordered) {
+        const { col, row } = placement;
+        if (kept.overlapping({ top: row, left: col, bottom: row, right: col }) !== undefined) {
+            cellsRemoved.push(placement);
+            continue;
+        }
+        const range = placement.arrayRef === undefined
+            ? undefined
+            : tryDecodeAnchoredRange(placement.arrayRef, col, row);
+        if (range === undefined)
+            continue;
+        if (kept.overlapping(range) !== undefined) {
+            formulasRemoved.push(placement);
+            continue;
+        }
+        keptRanges.push(range);
+        kept.note(range);
+    }
+    return { cellsRemoved, formulasRemoved };
+}
+function cachedResult(value) {
+    return typeof value === 'object' &&
+        value !== null &&
+        'result' in value &&
+        value.result !== undefined
+        ? value.result
+        : null;
+}
+export function admitting(build) {
+    try {
+        return build();
+    }
+    catch (error) {
+        if (error instanceof AuthoringError ||
+            error instanceof RangeError ||
+            error instanceof SyntaxError) {
+            return undefined;
+        }
+        throw error;
+    }
+}