clear-excel 1.0.3 → 1.0.5

package/CHANGELOG.md

@@ -3,6 +3,40 @@
 All notable changes to this project are documented in this file. The project
 follows [Semantic Versioning](https://semver.org/).
 
+## [1.0.5] - 2026-10-11
+
+### Changed
+
+- Simplify the README to focus on installation, usage, options, errors, and
+  supported workbook limitations.
+
+## [1.0.4] - 2026-10-09
+
+### Fixed
+
+- Preserve existing output files when exclusive creation fails and remove only
+  partial files created by the current write.
+- Reject source-file aliases through symbolic links and hard links, and preserve
+  existing output permissions during atomic overwrite.
+- Preserve worksheet text, CDATA, XML comments, and unrelated elements during
+  namespace-aware drawing and comment cleanup.
+- Resolve sheet relationship IDs by namespace URI and reject missing or invalid
+  relationships before pruning styles.
+- Decode UTF-8 and UTF-16 XML consistently and update encoding declarations when
+  writing UTF-8 output.
+- Enforce the actual aggregate uncompressed size of all retained ZIP parts,
+  including binary VBA projects with forged ZIP size metadata.
+
+### Changed
+
+- Replace Vite with one NodeNext TypeScript build for modular ESM output and
+  declarations, eliminating the duplicate bundled `cfb` dependency.
+- Clean build artifacts before compilation, embed sources in JavaScript maps,
+  and stop publishing declaration maps that reference unavailable source files.
+- Move the transitive `uuid` override to pnpm workspace configuration.
+- Verify the installed package with real `.xls`, `.xlsx`, and `.xlsm` workbooks
+  through both APIs, including retained values, formulas, merges, and macros.
+
 ## [1.0.0] - 2026-08-19
 
 ### Changed
@@ -21,5 +55,7 @@ follows [Semantic Versioning](https://semver.org/).
 - Initial release with buffer and file APIs for sanitizing `.xls`, `.xlsx`,
   and `.xlsm` workbooks.
 
+[1.0.5]: https://www.npmjs.com/package/clear-excel/v/1.0.5
+[1.0.4]: https://www.npmjs.com/package/clear-excel/v/1.0.4
 [1.0.0]: https://www.npmjs.com/package/clear-excel/v/1.0.0
 [0.1.0]: https://www.npmjs.com/package/clear-excel/v/0.1.0

package/README.md

@@ -1,63 +1,34 @@
-<div align="center">
+# clear-excel
 
-<h1>clear-excel</h1>
+Remove images, drawings, comments, controls, and embedded objects from `.xls`,
+`.xlsx`, and `.xlsm` workbooks. Cell values, formulas, merged cells, worksheets,
+and used styles are preserved. Unused styles are also removed from `.xlsx` and
+`.xlsm` workbooks.
 
-<p><strong>Remove drawings, comments, and embedded objects from Excel workbooks
-without rebuilding their data model.</strong></p>
+## Install
 
-<p>
-  <a href="https://www.npmjs.com/package/clear-excel"><img alt="npm version" src="https://img.shields.io/npm/v/clear-excel?style=flat-square&amp;logo=npm"></a>
-  <a href="https://www.npmjs.com/package/clear-excel"><img alt="npm downloads" src="https://img.shields.io/npm/dm/clear-excel?style=flat-square&amp;logo=npm"></a>
-  <a href="https://github.com/Vlad1slav1vanov/clear-excel/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/Vlad1slav1vanov/clear-excel/ci.yml?branch=main&amp;style=flat-square&amp;logo=github&amp;label=CI"></a>
-  <a href="https://www.npmjs.com/package/clear-excel"><img alt="Node.js" src="https://img.shields.io/node/v/clear-excel?style=flat-square&amp;logo=nodedotjs"></a>
-  <a href="./LICENSE"><img alt="License" src="https://img.shields.io/npm/l/clear-excel?style=flat-square"></a>
-</p>
-
-<p>
-  <a href="https://www.npmjs.com/package/clear-excel">npm</a> ·
-  <a href="https://github.com/Vlad1slav1vanov/clear-excel/releases">Releases</a> ·
-  <a href="./CHANGELOG.md">Changelog</a> ·
-  <a href="./CONTRIBUTING.md">Contributing</a> ·
-  <a href="./SECURITY.md">Security</a>
-</p>
-
-</div>
-
-`clear-excel` is an ESM-only Node.js library for sanitizing legacy `.xls` and
-OOXML `.xlsx`/`.xlsm` workbooks while preserving worksheet data and structure.
-It has no framework or consumer-side build requirement.
-
-## What it removes
-
-- drawings, images, comments, controls, and embedded OLE objects;
-- VML drawings, threaded comments, and person metadata in OOXML workbooks;
-- unused `cellXfs` style records in OOXML workbooks;
-- BIFF drawing, note, object, and picture records plus embedded object storages
-  in legacy `.xls` workbooks.
-
-Values, formulas and cached results, merged cells, worksheets, and styles that
-are still referenced by cells, rows, or columns are retained. `.xlsm` VBA
-projects and legacy `.xls` VBA storages are preserved; the library does not
-execute or remove macros.
+```sh
+npm install clear-excel
+```
 
-## Requirements
+Requires Node.js 22 or newer. ESM only; TypeScript declarations are included.
 
-- Node.js 22 or newer;
-- Excel 97-2003 BIFF8 `.xls`, OOXML `.xlsx`, or macro-enabled `.xlsm` input.
+## Usage
 
-Encrypted `.xls` workbooks are not supported.
+### Files
 
-## Installation
+```js
+import { sanitizeExcelFile } from "clear-excel";
 
-```sh
-pnpm add clear-excel
+await sanitizeExcelFile("report.xlsx", "report.cleaned.xlsx");
 ```
 
-The package is published on
-[npm](https://www.npmjs.com/package/clear-excel) and includes TypeScript
-declarations.
+`sanitizeExcelFile(inputPath, outputPath, options?)` returns `Promise<void>`.
+Input and output must refer to different files and use the same supported
+extension (`.xls`, `.xlsx`, or `.xlsm`, case-insensitive). The output directory
+must already exist. To replace an existing output file, set `overwrite: true`.
 
-## Buffer API
+### Buffers
 
 ```js
 import { readFile, writeFile } from "node:fs/promises";
@@ -68,86 +39,65 @@ const output = await sanitizeExcel(input);
 await writeFile("report.cleaned.xlsx", output);
 ```
 
-`sanitizeExcel` accepts a Node.js `Buffer`, returns a new `Buffer`, and never
-modifies the input buffer. It detects legacy CFB/BIFF workbooks by their file
-signature and keeps the input format in the returned buffer.
+`sanitizeExcel(buffer, options?)` accepts a Node.js `Buffer` and returns
+`Promise<Buffer>`. The input buffer is not modified; the output keeps the
+original workbook format.
+
+### Filename checks
 
-## Version 1 migration
+The package also exports `isExcelFilename(name)` for `.xls`, `.xlsx`, and `.xlsm`,
+and `isXlsxFilename(name)` for `.xlsx` only. Both return a boolean, ignore case,
+and check the extension without reading the file.
 
-Version 1 is ESM-only. Replace CommonJS `require("clear-excel")` calls with
-ECMAScript imports. Runtime exports, option types, error codes, and sanitizing
-behavior otherwise remain compatible with version 0.1.
+## Options
 
-## File API
+| Option                   | Default          | Description                                             |
+| ------------------------ | ---------------- | ------------------------------------------------------- |
+| `requireSingleWorksheet` | `false`          | Reject workbooks that do not contain exactly one sheet. |
+| `limits`                 | `DEFAULT_LIMITS` | Override individual size and entry-count limits.        |
+| `overwrite`              | `false`          | Replace an existing output; `sanitizeExcelFile` only.   |
 
 ```js
 import { sanitizeExcelFile } from "clear-excel";
 
-await sanitizeExcelFile("report.xlsx", "report.cleaned.xlsx");
-```
-
-The input and output paths must be different and use the same supported
-extension: `.xls`, `.xlsx`, or `.xlsm` (case-insensitive). The file API does not
-convert between formats. The output directory must already exist. An existing
-output file is not replaced unless `overwrite: true` is explicitly supplied:
-
-```js
 await sanitizeExcelFile("report.xlsx", "report.cleaned.xlsx", {
   overwrite: true,
   requireSingleWorksheet: true,
+  limits: {
+    maxUncompressedBytes: 128 * 1024 * 1024,
+  },
 });
 ```
 
-## Options
-
-Both sanitizing functions accept these options:
-
-| Option                   | Type      | Default   | Description                                             |
-| ------------------------ | --------- | --------- | ------------------------------------------------------- |
-| `requireSingleWorksheet` | `boolean` | `false`   | Reject workbooks that do not contain exactly one sheet. |
-| `limits`                 | `object`  | See below | Override individual ZIP/XML safety limits.              |
-
-`sanitizeExcelFile` additionally accepts `overwrite`, which defaults to
-`false`.
+### Limits
 
-The exported `DEFAULT_LIMITS` object contains the defaults:
+The exported `DEFAULT_LIMITS` contains these defaults. Only specified values
+are overridden; each must be a positive safe integer. Sizes are in bytes.
 
 | Limit                      |                      Default |
 | -------------------------- | ---------------------------: |
 | `maxEntryCount`            |               10,000 entries |
 | `maxUncompressedBytes`     |                      512 MiB |
-| `maxXmlBytes`              | 512 MiB aggregate XML output |
+| `maxXmlBytes`              |  512 MiB aggregate XML reads |
 | `maxWorksheetXmlBytes`     |        256 MiB per worksheet |
 | `maxStylesXmlBytes`        |                       64 MiB |
 | `maxMetadataXmlBytes`      |     16 MiB per metadata part |
 | `maxRelationshipsXmlBytes` | 8 MiB per relationships part |
 
-Only specified values are overridden:
-
-```js
-const output = await sanitizeExcel(input, {
-  limits: {
-    maxUncompressedBytes: 128 * 1024 * 1024,
-    maxWorksheetXmlBytes: 64 * 1024 * 1024,
-  },
-});
-```
-
-Every limit must be a positive safe integer. Raising limits can significantly
-increase memory usage. For `.xls`, `maxEntryCount` and
-`maxUncompressedBytes` apply to the CFB container; the XML-specific limits apply
-only to `.xlsx` and `.xlsm`.
+For `.xls`, only `maxEntryCount` and `maxUncompressedBytes` apply. XML limits
+apply to `.xlsx` and `.xlsm`.
 
 ## Errors
 
-Public functions reject with `ExcelSanitizationError`. Use its stable `code`
-instead of matching the English message:
+Both sanitizing functions reject with `ExcelSanitizationError`. Check `code`
+instead of matching the error message. `details` contains additional context
+when available, and `cause` holds the original error when one exists.
 
 ```js
-import { ExcelSanitizationError, sanitizeExcel } from "clear-excel";
+import { ExcelSanitizationError, sanitizeExcelFile } from "clear-excel";
 
 try {
-  await sanitizeExcel(input);
+  await sanitizeExcelFile("report.xlsx", "report.cleaned.xlsx");
 } catch (error) {
   if (error instanceof ExcelSanitizationError) {
     console.error(error.code, error.details);
@@ -156,73 +106,26 @@ try {
 }
 ```
 
-| Code                        | Meaning                                             |
-| --------------------------- | --------------------------------------------------- |
-| `ERR_INVALID_ARGUMENT`      | An argument or option has an invalid type or value. |
-| `ERR_UNSUPPORTED_EXTENSION` | Paths use an unsupported or mismatched extension.   |
-| `ERR_INVALID_XLS`           | The CFB/BIFF workbook is malformed or unsupported.  |
-| `ERR_INVALID_XLSX`          | The ZIP/OOXML package is malformed or unsupported.  |
-| `ERR_LIMIT_EXCEEDED`        | A configured ZIP or XML limit was exceeded.         |
-| `ERR_WORKSHEET_COUNT`       | Exactly one worksheet was required.                 |
-| `ERR_SAME_PATH`             | Input and output resolve to the same path.          |
-| `ERR_OUTPUT_EXISTS`         | Output exists and `overwrite` is false.             |
-| `ERR_FILE_READ`             | The input could not be read.                        |
-| `ERR_FILE_WRITE`            | The sanitized output could not be written.          |
-
-The original technical error is available through `error.cause` when one
-exists. Limit and worksheet-count failures also include structured `details`.
-
-## Security and memory model
-
-Before loading an OOXML archive, `clear-excel` validates the ZIP central
-directory, rejects ZIP64 and multi-disk archives, rejects unsafe entry paths,
-and checks declared entry counts and expansion sizes. Required XML parts are
-inflated lazily with both per-part and aggregate runtime budgets, including
-protection when ZIP size metadata has been forged.
-
-For `.xls`, the library validates CFB entry and byte limits, parses the BIFF
-record stream without evaluating formulas, removes drawing-layer records, and
-rewrites worksheet offsets after records move. Workbook records are not
-converted through an OOXML or generic tabular representation.
-
-JSZip still loads the ZIP directory and regenerates the complete workbook in
-memory. Plan for memory usage above the input size, especially when increasing
-the defaults. The sanitizer does not evaluate formulas, execute embedded
-content, or execute VBA projects.
-
-## Development
-
-Install dependencies and run the complete verification suite:
-
-```sh
-pnpm install --frozen-lockfile
-pnpm run check
-```
-
-`pnpm run check` verifies Oxfmt formatting, runs type-aware Oxlint and strict
-TypeScript checks, executes the tests, builds the ESM bundle and declarations,
-inspects `pnpm pack --dry-run`, and installs a temporary tarball to smoke-test
-both runtime imports and a TypeScript consumer.
-
-Useful development commands:
-
-```sh
-pnpm run format
-pnpm run lint
-pnpm run check:types
-pnpm test
-pnpm run build
-```
-
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for the contribution and release
-process.
-
-## Security
-
-Please report vulnerabilities privately by following
-[SECURITY.md](./SECURITY.md). Do not open a public issue for a suspected
-security vulnerability.
+| Code                        | Meaning                                              |
+| --------------------------- | ---------------------------------------------------- |
+| `ERR_INVALID_ARGUMENT`      | An argument or option has an invalid type or value.  |
+| `ERR_UNSUPPORTED_EXTENSION` | Paths use an unsupported or mismatched extension.    |
+| `ERR_INVALID_XLS`           | The XLS workbook is malformed or unsupported.        |
+| `ERR_INVALID_XLSX`          | The XLSX/XLSM workbook is malformed or unsupported.  |
+| `ERR_LIMIT_EXCEEDED`        | A configured size or entry-count limit was exceeded. |
+| `ERR_WORKSHEET_COUNT`       | Exactly one worksheet was required.                  |
+| `ERR_SAME_PATH`             | Input and output refer to the same file.             |
+| `ERR_OUTPUT_EXISTS`         | Output exists and `overwrite` is false.              |
+| `ERR_FILE_READ`             | The input could not be read.                         |
+| `ERR_FILE_WRITE`            | The output could not be written.                     |
+
+## Limitations
+
+- `.xls` input must use Excel 97–2003 BIFF8. Encrypted `.xls` files are not supported.
+- VBA macros are preserved. The library does not execute macros or evaluate formulas.
+- Workbooks are processed in memory. Memory usage can exceed the input size,
+  especially when increasing limits.
 
 ## License
 
-[MIT](./LICENSE) © Vladislav Ivanov
+[MIT](./LICENSE)

package/dist/api/sanitize-excel-file.d.ts

@@ -2,4 +2,3 @@ import { isExcelFilename, isXlsxFilename } from "../formats.js";
 import type { SanitizeExcelFileOptions } from "../types.js";
 export { isExcelFilename, isXlsxFilename };
 export declare function sanitizeExcelFile(inputPath: string, outputPath: string, options?: SanitizeExcelFileOptions): Promise<void>;
-//# sourceMappingURL=sanitize-excel-file.d.ts.map

package/dist/api/sanitize-excel-file.js

@@ -0,0 +1,176 @@
+import { randomUUID } from "node:crypto";
+import { open, readFile, realpath, rename, stat, unlink } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { hasCompoundFileSignature } from "../biff/workbook.js";
+import { createError } from "../errors.js";
+import { excelFileFormat, isExcelFilename, isXlsxFilename } from "../formats.js";
+import { normalizeOptions } from "../options.js";
+import { sanitizeExcel } from "./sanitize-excel.js";
+export { isExcelFilename, isXlsxFilename };
+export async function sanitizeExcelFile(inputPath, outputPath, options) {
+    const format = validateFilePaths(inputPath, outputPath);
+    const normalized = normalizeOptions(options, true);
+    const absoluteInputPath = resolve(inputPath);
+    const absoluteOutputPath = resolve(outputPath);
+    if (absoluteInputPath === absoluteOutputPath) {
+        throw createError("ERR_SAME_PATH", {
+            details: { inputPath: absoluteInputPath, outputPath: absoluteOutputPath },
+        });
+    }
+    const input = await readInputFile(absoluteInputPath);
+    await validateDistinctFiles(absoluteInputPath, absoluteOutputPath);
+    validateInputFormat(input, format);
+    const sanitized = await sanitizeExcel(input, {
+        requireSingleWorksheet: normalized.requireSingleWorksheet,
+        limits: normalized.limits,
+    });
+    if (normalized.overwrite) {
+        await replaceFileAtomically(absoluteOutputPath, sanitized);
+    }
+    else {
+        await writeNewFile(absoluteOutputPath, sanitized);
+    }
+}
+function validateFilePaths(inputPath, outputPath) {
+    if (typeof inputPath !== "string" ||
+        inputPath.length === 0 ||
+        typeof outputPath !== "string" ||
+        outputPath.length === 0) {
+        throw createError("ERR_INVALID_ARGUMENT", {
+            message: "inputPath and outputPath must be non-empty strings",
+        });
+    }
+    const inputFormat = excelFileFormat(inputPath);
+    const outputFormat = excelFileFormat(outputPath);
+    if (!inputFormat || !outputFormat || inputFormat !== outputFormat) {
+        throw createError("ERR_UNSUPPORTED_EXTENSION", {
+            details: { inputPath, outputPath, inputFormat, outputFormat },
+        });
+    }
+    return inputFormat;
+}
+function validateInputFormat(input, format) {
+    const isXls = hasCompoundFileSignature(input);
+    if ((format === "xls") !== isXls) {
+        throw createError(format === "xls" ? "ERR_INVALID_XLS" : "ERR_INVALID_XLSX", {
+            details: { format },
+        });
+    }
+}
+async function readInputFile(inputPath) {
+    try {
+        return await readFile(inputPath);
+    }
+    catch (error) {
+        throw createError("ERR_FILE_READ", {
+            cause: error,
+            details: { inputPath },
+        });
+    }
+}
+async function writeNewFile(outputPath, contents) {
+    try {
+        await writeExclusiveFile(outputPath, contents);
+    }
+    catch (error) {
+        if (hasErrorCode(error, "EEXIST")) {
+            throw createError("ERR_OUTPUT_EXISTS", {
+                cause: error,
+                details: { outputPath },
+            });
+        }
+        throw createError("ERR_FILE_WRITE", {
+            cause: error,
+            details: { outputPath },
+        });
+    }
+}
+async function replaceFileAtomically(outputPath, contents) {
+    const temporaryPath = `${outputPath}.${process.pid}.${randomUUID()}.tmp`;
+    let temporaryCreated = false;
+    try {
+        const existingOutput = await stat(outputPath).catch((error) => {
+            if (hasErrorCode(error, "ENOENT")) {
+                return undefined;
+            }
+            throw error;
+        });
+        const outputMode = existingOutput ? existingOutput.mode & 0o777 : undefined;
+        await writeExclusiveFile(temporaryPath, contents, outputMode);
+        temporaryCreated = true;
+        await rename(temporaryPath, outputPath);
+    }
+    catch (error) {
+        if (temporaryCreated) {
+            await removeIfPresent(temporaryPath);
+        }
+        throw createError("ERR_FILE_WRITE", {
+            cause: error,
+            details: { outputPath },
+        });
+    }
+}
+async function writeExclusiveFile(path, contents, mode) {
+    // A failed open does not establish ownership, so it must never trigger unlink.
+    const handle = await open(path, "wx", mode);
+    try {
+        await handle.writeFile(contents);
+        if (mode !== undefined) {
+            await handle.chmod(mode);
+        }
+        await handle.close();
+    }
+    catch (error) {
+        await handle.close().catch(() => undefined);
+        await removeIfPresent(path);
+        throw error;
+    }
+}
+async function validateDistinctFiles(inputPath, outputPath) {
+    let inputRealPath;
+    let inputStat;
+    try {
+        inputRealPath = await realpath(inputPath);
+        inputStat = await stat(inputPath);
+    }
+    catch (error) {
+        throw createError("ERR_FILE_READ", { cause: error, details: { inputPath } });
+    }
+    let sameFile;
+    try {
+        const outputStat = await stat(outputPath).catch((error) => {
+            if (hasErrorCode(error, "ENOENT")) {
+                return undefined;
+            }
+            throw error;
+        });
+        const outputRealPath = outputStat
+            ? await realpath(outputPath)
+            : await realpath(dirname(outputPath))
+                .then((parent) => join(parent, basename(outputPath)))
+                .catch((error) => {
+                if (hasErrorCode(error, "ENOENT")) {
+                    return outputPath;
+                }
+                throw error;
+            });
+        sameFile =
+            inputRealPath === outputRealPath ||
+                (outputStat !== undefined &&
+                    inputStat.dev === outputStat.dev &&
+                    inputStat.ino === outputStat.ino);
+    }
+    catch (error) {
+        throw createError("ERR_FILE_WRITE", { cause: error, details: { outputPath } });
+    }
+    if (sameFile) {
+        throw createError("ERR_SAME_PATH", { details: { inputPath, outputPath } });
+    }
+}
+function hasErrorCode(error, expectedCode) {
+    return (typeof error === "object" && error !== null && "code" in error && error.code === expectedCode);
+}
+async function removeIfPresent(path) {
+    await unlink(path).catch(() => undefined);
+}
+//# sourceMappingURL=sanitize-excel-file.js.map

package/dist/api/sanitize-excel-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize-excel-file.js","sourceRoot":"","sources":["../../src/api/sanitize-excel-file.ts"],"names":[],"mappings":"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","sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport { open, readFile, realpath, rename, stat, unlink } from \"node:fs/promises\";\nimport { basename, dirname, join, resolve } from \"node:path\";\n\nimport { hasCompoundFileSignature } from \"../biff/workbook.js\";\nimport { createError } from \"../errors.js\";\nimport { excelFileFormat, isExcelFilename, isXlsxFilename } from \"../formats.js\";\nimport type { ExcelFileFormat } from \"../formats.js\";\nimport { normalizeOptions } from \"../options.js\";\nimport type { SanitizeExcelFileOptions } from \"../types.js\";\nimport { sanitizeExcel } from \"./sanitize-excel.js\";\n\nexport { isExcelFilename, isXlsxFilename };\n\nexport async function sanitizeExcelFile(\n  inputPath: string,\n  outputPath: string,\n  options?: SanitizeExcelFileOptions,\n): Promise<void> {\n  const format = validateFilePaths(inputPath, outputPath);\n  const normalized = normalizeOptions(options, true);\n  const absoluteInputPath = resolve(inputPath);\n  const absoluteOutputPath = resolve(outputPath);\n  if (absoluteInputPath === absoluteOutputPath) {\n    throw createError(\"ERR_SAME_PATH\", {\n      details: { inputPath: absoluteInputPath, outputPath: absoluteOutputPath },\n    });\n  }\n\n  const input = await readInputFile(absoluteInputPath);\n  await validateDistinctFiles(absoluteInputPath, absoluteOutputPath);\n  validateInputFormat(input, format);\n  const sanitized = await sanitizeExcel(input, {\n    requireSingleWorksheet: normalized.requireSingleWorksheet,\n    limits: normalized.limits,\n  });\n\n  if (normalized.overwrite) {\n    await replaceFileAtomically(absoluteOutputPath, sanitized);\n  } else {\n    await writeNewFile(absoluteOutputPath, sanitized);\n  }\n}\n\nfunction validateFilePaths(inputPath: string, outputPath: string): ExcelFileFormat {\n  if (\n    typeof inputPath !== \"string\" ||\n    inputPath.length === 0 ||\n    typeof outputPath !== \"string\" ||\n    outputPath.length === 0\n  ) {\n    throw createError(\"ERR_INVALID_ARGUMENT\", {\n      message: \"inputPath and outputPath must be non-empty strings\",\n    });\n  }\n  const inputFormat = excelFileFormat(inputPath);\n  const outputFormat = excelFileFormat(outputPath);\n  if (!inputFormat || !outputFormat || inputFormat !== outputFormat) {\n    throw createError(\"ERR_UNSUPPORTED_EXTENSION\", {\n      details: { inputPath, outputPath, inputFormat, outputFormat },\n    });\n  }\n  return inputFormat;\n}\n\nfunction validateInputFormat(input: Buffer, format: ExcelFileFormat): void {\n  const isXls = hasCompoundFileSignature(input);\n  if ((format === \"xls\") !== isXls) {\n    throw createError(format === \"xls\" ? \"ERR_INVALID_XLS\" : \"ERR_INVALID_XLSX\", {\n      details: { format },\n    });\n  }\n}\n\nasync function readInputFile(inputPath: string): Promise<Buffer> {\n  try {\n    return await readFile(inputPath);\n  } catch (error) {\n    throw createError(\"ERR_FILE_READ\", {\n      cause: error,\n      details: { inputPath },\n    });\n  }\n}\n\nasync function writeNewFile(outputPath: string, contents: Buffer): Promise<void> {\n  try {\n    await writeExclusiveFile(outputPath, contents);\n  } catch (error) {\n    if (hasErrorCode(error, \"EEXIST\")) {\n      throw createError(\"ERR_OUTPUT_EXISTS\", {\n        cause: error,\n        details: { outputPath },\n      });\n    }\n    throw createError(\"ERR_FILE_WRITE\", {\n      cause: error,\n      details: { outputPath },\n    });\n  }\n}\n\nasync function replaceFileAtomically(outputPath: string, contents: Buffer): Promise<void> {\n  const temporaryPath = `${outputPath}.${process.pid}.${randomUUID()}.tmp`;\n  let temporaryCreated = false;\n  try {\n    const existingOutput = await stat(outputPath).catch((error: unknown) => {\n      if (hasErrorCode(error, \"ENOENT\")) {\n        return undefined;\n      }\n      throw error;\n    });\n    const outputMode = existingOutput ? existingOutput.mode & 0o777 : undefined;\n    await writeExclusiveFile(temporaryPath, contents, outputMode);\n    temporaryCreated = true;\n    await rename(temporaryPath, outputPath);\n  } catch (error) {\n    if (temporaryCreated) {\n      await removeIfPresent(temporaryPath);\n    }\n    throw createError(\"ERR_FILE_WRITE\", {\n      cause: error,\n      details: { outputPath },\n    });\n  }\n}\n\nasync function writeExclusiveFile(path: string, contents: Buffer, mode?: number): Promise<void> {\n  // A failed open does not establish ownership, so it must never trigger unlink.\n  const handle = await open(path, \"wx\", mode);\n  try {\n    await handle.writeFile(contents);\n    if (mode !== undefined) {\n      await handle.chmod(mode);\n    }\n    await handle.close();\n  } catch (error) {\n    await handle.close().catch(() => undefined);\n    await removeIfPresent(path);\n    throw error;\n  }\n}\n\nasync function validateDistinctFiles(inputPath: string, outputPath: string): Promise<void> {\n  let inputRealPath: string;\n  let inputStat: Awaited<ReturnType<typeof stat>>;\n  try {\n    inputRealPath = await realpath(inputPath);\n    inputStat = await stat(inputPath);\n  } catch (error) {\n    throw createError(\"ERR_FILE_READ\", { cause: error, details: { inputPath } });\n  }\n\n  let sameFile: boolean;\n  try {\n    const outputStat = await stat(outputPath).catch((error: unknown) => {\n      if (hasErrorCode(error, \"ENOENT\")) {\n        return undefined;\n      }\n      throw error;\n    });\n    const outputRealPath = outputStat\n      ? await realpath(outputPath)\n      : await realpath(dirname(outputPath))\n          .then((parent) => join(parent, basename(outputPath)))\n          .catch((error: unknown) => {\n            if (hasErrorCode(error, \"ENOENT\")) {\n              return outputPath;\n            }\n            throw error;\n          });\n    sameFile =\n      inputRealPath === outputRealPath ||\n      (outputStat !== undefined &&\n        inputStat.dev === outputStat.dev &&\n        inputStat.ino === outputStat.ino);\n  } catch (error) {\n    throw createError(\"ERR_FILE_WRITE\", { cause: error, details: { outputPath } });\n  }\n\n  if (sameFile) {\n    throw createError(\"ERR_SAME_PATH\", { details: { inputPath, outputPath } });\n  }\n}\n\nfunction hasErrorCode(error: unknown, expectedCode: string): boolean {\n  return (\n    typeof error === \"object\" && error !== null && \"code\" in error && error.code === expectedCode\n  );\n}\n\nasync function removeIfPresent(path: string): Promise<void> {\n  await unlink(path).catch(() => undefined);\n}\n"]}

package/dist/api/sanitize-excel.d.ts

@@ -1,3 +1,2 @@
 import type { SanitizeExcelOptions } from "../types.js";
 export declare function sanitizeExcel(buffer: Buffer, options?: SanitizeExcelOptions): Promise<Buffer>;
-//# sourceMappingURL=sanitize-excel.d.ts.map

package/dist/api/sanitize-excel.js

@@ -0,0 +1,25 @@
+import { hasCompoundFileSignature, sanitizeBiffWorkbook } from "../biff/workbook.js";
+import { ExcelSanitizationError, createError } from "../errors.js";
+import { sanitizeOoxmlWorkbook } from "../ooxml/workbook.js";
+import { normalizeOptions } from "../options.js";
+export async function sanitizeExcel(buffer, options) {
+    if (!Buffer.isBuffer(buffer)) {
+        throw createError("ERR_INVALID_ARGUMENT", {
+            message: "buffer must be a Node.js Buffer",
+        });
+    }
+    const normalized = normalizeOptions(options);
+    const isBiff = hasCompoundFileSignature(buffer);
+    try {
+        return isBiff
+            ? await sanitizeBiffWorkbook(buffer, normalized)
+            : await sanitizeOoxmlWorkbook(buffer, normalized);
+    }
+    catch (error) {
+        if (error instanceof ExcelSanitizationError) {
+            throw error;
+        }
+        throw createError(isBiff ? "ERR_INVALID_XLS" : "ERR_INVALID_XLSX", { cause: error });
+    }
+}
+//# sourceMappingURL=sanitize-excel.js.map

package/dist/api/sanitize-excel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize-excel.js","sourceRoot":"","sources":["../../src/api/sanitize-excel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AACrF,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAGjD,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAAc,EACd,OAA8B;IAE9B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7B,MAAM,WAAW,CAAC,sBAAsB,EAAE;YACxC,OAAO,EAAE,iCAAiC;SAC3C,CAAC,CAAC;IACL,CAAC;IAED,MAAM,UAAU,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,wBAAwB,CAAC,MAAM,CAAC,CAAC;IAChD,IAAI,CAAC;QACH,OAAO,MAAM;YACX,CAAC,CAAC,MAAM,oBAAoB,CAAC,MAAM,EAAE,UAAU,CAAC;YAChD,CAAC,CAAC,MAAM,qBAAqB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACtD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,sBAAsB,EAAE,CAAC;YAC5C,MAAM,KAAK,CAAC;QACd,CAAC;QACD,MAAM,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,kBAAkB,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACvF,CAAC;AACH,CAAC","sourcesContent":["import { hasCompoundFileSignature, sanitizeBiffWorkbook } from \"../biff/workbook.js\";\nimport { ExcelSanitizationError, createError } from \"../errors.js\";\nimport { sanitizeOoxmlWorkbook } from \"../ooxml/workbook.js\";\nimport { normalizeOptions } from \"../options.js\";\nimport type { SanitizeExcelOptions } from \"../types.js\";\n\nexport async function sanitizeExcel(\n  buffer: Buffer,\n  options?: SanitizeExcelOptions,\n): Promise<Buffer> {\n  if (!Buffer.isBuffer(buffer)) {\n    throw createError(\"ERR_INVALID_ARGUMENT\", {\n      message: \"buffer must be a Node.js Buffer\",\n    });\n  }\n\n  const normalized = normalizeOptions(options);\n  const isBiff = hasCompoundFileSignature(buffer);\n  try {\n    return isBiff\n      ? await sanitizeBiffWorkbook(buffer, normalized)\n      : await sanitizeOoxmlWorkbook(buffer, normalized);\n  } catch (error) {\n    if (error instanceof ExcelSanitizationError) {\n      throw error;\n    }\n    throw createError(isBiff ? \"ERR_INVALID_XLS\" : \"ERR_INVALID_XLSX\", { cause: error });\n  }\n}\n"]}

package/dist/biff/workbook.d.ts

@@ -1,4 +1,3 @@
 import type { NormalizedSanitizeOptions } from "../types.js";
 export declare function hasCompoundFileSignature(buffer: Buffer): boolean;
 export declare function sanitizeBiffWorkbook(buffer: Buffer, options: NormalizedSanitizeOptions): Promise<Buffer>;
-//# sourceMappingURL=workbook.d.ts.map