clear-excel 0.1.0 → 1.0.0

package/README.md

@@ -1,27 +1,29 @@
 # clear-excel
 
-`clear-excel` safely removes drawing-backed content and unused cell styles from
-OOXML `.xlsx` workbooks while preserving worksheet data and structure. It is a
-plain Node.js library with no framework or build-time requirement.
+`clear-excel` safely removes drawing-backed content from legacy `.xls` and
+OOXML `.xlsx`/`.xlsm` workbooks while preserving worksheet data and structure.
+It is an ESM-only Node.js library with no framework or consumer-side build
+requirement.
 
 ## What it removes
 
-- drawings and images;
-- classic and threaded comments;
-- controls, OLE objects, VML drawings, and worksheet pictures;
-- threaded-comment person metadata;
-- unused `cellXfs` style records.
+- 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.
+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.
 
 ## Requirements
 
 - Node.js 22 or newer;
-- OOXML `.xlsx` input.
+- Excel 97-2003 BIFF8 `.xls`, OOXML `.xlsx`, or macro-enabled `.xlsm` input.
 
-Legacy `.xls` files and macro-enabled `.xlsm` workbooks are intentionally not
-supported.
+Encrypted `.xls` workbooks are not supported.
 
 ## Installation
 
@@ -31,8 +33,6 @@ npm install clear-excel
 
 ## Buffer API
 
-ES modules:
-
 ```js
 import { readFile, writeFile } from "node:fs/promises";
 import { sanitizeExcel } from "clear-excel";
@@ -42,19 +42,15 @@ const output = await sanitizeExcel(input);
 await writeFile("report.cleaned.xlsx", output);
 ```
 
-CommonJS:
-
-```js
-const { readFile, writeFile } = require("node:fs/promises");
-const { sanitizeExcel } = require("clear-excel");
+`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.
 
-const input = await readFile("report.xlsx");
-const output = await sanitizeExcel(input);
-await writeFile("report.cleaned.xlsx", output);
-```
+## Version 1 migration
 
-`sanitizeExcel` accepts a Node.js `Buffer`, returns a new `Buffer`, and never
-modifies the input buffer.
+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.
 
 ## File API
 
@@ -64,9 +60,10 @@ import { sanitizeExcelFile } from "clear-excel";
 await sanitizeExcelFile("report.xlsx", "report.cleaned.xlsx");
 ```
 
-The input and output paths must be different and end in `.xlsx`. The output
-directory must already exist. An existing output file is not replaced unless
-`overwrite: true` is explicitly supplied:
+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", {
@@ -79,24 +76,24 @@ await sanitizeExcelFile("report.xlsx", "report.cleaned.xlsx", {
 
 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. |
+| 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`.
 
 The exported `DEFAULT_LIMITS` object contains the defaults:
 
-| Limit | Default |
-| --- | ---: |
-| `maxEntryCount` | 10,000 entries |
-| `maxUncompressedBytes` | 512 MiB |
-| `maxXmlBytes` | 512 MiB aggregate XML output |
-| `maxWorksheetXmlBytes` | 256 MiB per worksheet |
-| `maxStylesXmlBytes` | 64 MiB |
-| `maxMetadataXmlBytes` | 16 MiB per metadata part |
+| Limit                      |                      Default |
+| -------------------------- | ---------------------------: |
+| `maxEntryCount`            |               10,000 entries |
+| `maxUncompressedBytes`     |                      512 MiB |
+| `maxXmlBytes`              | 512 MiB aggregate XML output |
+| `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:
@@ -111,7 +108,9 @@ const output = await sanitizeExcel(input, {
 ```
 
 Every limit must be a positive safe integer. Raising limits can significantly
-increase memory usage.
+increase memory usage. For `.xls`, `maxEntryCount` and
+`maxUncompressedBytes` apply to the CFB container; the XML-specific limits apply
+only to `.xlsx` and `.xlsm`.
 
 ## Errors
 
@@ -131,33 +130,39 @@ try {
 }
 ```
 
-| Code | Meaning |
-| --- | --- |
-| `ERR_INVALID_ARGUMENT` | An argument or option has an invalid type or value. |
-| `ERR_UNSUPPORTED_EXTENSION` | A file path does not end in `.xlsx`. |
-| `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. |
+| 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 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.
+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 or execute embedded
-content.
+the defaults. The sanitizer does not evaluate formulas, execute embedded
+content, or execute VBA projects.
 
 ## Publishing
 
@@ -170,11 +175,23 @@ npm login
 npm publish
 ```
 
-`npm run check` validates syntax, runs the tests, inspects `npm pack --dry-run`,
-and installs a temporary tarball to smoke-test both ESM and CommonJS exports.
-`prepublishOnly` runs the same checks automatically. npm credentials and
+`npm run check` verifies Oxfmt formatting, runs type-aware Oxlint and strict
+TypeScript checks, executes the tests, builds the ESM bundle and declarations,
+inspects `npm pack --dry-run`, and installs a temporary tarball to smoke-test
+both runtime imports and a TypeScript consumer. `prepack` creates `dist/`, and
+`prepublishOnly` runs the complete check automatically. npm credentials and
 publishing automation are deliberately not stored in this repository.
 
+Useful development commands:
+
+```sh
+npm run format
+npm run lint
+npm run check:types
+npm test
+npm run build
+```
+
 ## License
 
 MIT

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

@@ -0,0 +1,5 @@
+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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize-excel-file.d.ts","sourceRoot":"","sources":["../../src/api/sanitize-excel-file.ts"],"names":[],"mappings":"AAMA,OAAO,EAAmB,eAAe,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAGjF,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAG5D,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,CAAC;AAE3C,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,wBAAwB,GACjC,OAAO,CAAC,IAAI,CAAC,CAuBf"}

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

@@ -0,0 +1,3 @@
+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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize-excel.d.ts","sourceRoot":"","sources":["../../src/api/sanitize-excel.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAExD,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,MAAM,CAAC,CAmBjB"}

package/dist/biff/workbook.d.ts

@@ -0,0 +1,4 @@
+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

package/dist/biff/workbook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workbook.d.ts","sourceRoot":"","sources":["../../src/biff/workbook.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAmC7D,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAKhE;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,MAAM,CAAC,CAqBjB"}

package/dist/constants.d.ts

@@ -0,0 +1,6 @@
+import type { ExcelSanitizationLimits } from "./types.js";
+export declare const DEFAULT_LIMITS: Readonly<ExcelSanitizationLimits>;
+export declare const SANITIZE_OPTION_NAMES: ReadonlySet<string>;
+export declare const FILE_OPTION_NAMES: ReadonlySet<string>;
+export declare const LIMIT_NAMES: ReadonlySet<string>;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE1D,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,uBAAuB,CAQ3D,CAAC;AAEH,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,MAAM,CAGpD,CAAC;AAEH,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAIhD,CAAC;AAEH,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,MAAM,CAQ1C,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,20 @@
+import type { ExcelSanitizationLimits } from "./types.js";
+export type ExcelSanitizationErrorCode = "ERR_INVALID_ARGUMENT" | "ERR_UNSUPPORTED_EXTENSION" | "ERR_INVALID_XLS" | "ERR_INVALID_XLSX" | "ERR_LIMIT_EXCEEDED" | "ERR_WORKSHEET_COUNT" | "ERR_SAME_PATH" | "ERR_OUTPUT_EXISTS" | "ERR_FILE_READ" | "ERR_FILE_WRITE";
+export interface ExcelSanitizationErrorOptions {
+    cause?: unknown;
+    details?: Readonly<Record<string, unknown>>;
+}
+interface CreateErrorOptions extends ExcelSanitizationErrorOptions {
+    message?: string;
+}
+export type SafetyLimitName = keyof ExcelSanitizationLimits | "partBytes";
+export declare class ExcelSanitizationError extends Error {
+    readonly name = "ExcelSanitizationError";
+    readonly code: ExcelSanitizationErrorCode;
+    readonly details?: Readonly<Record<string, unknown>>;
+    constructor(code: ExcelSanitizationErrorCode, message: string, options?: ExcelSanitizationErrorOptions);
+}
+export declare function createError(code: ExcelSanitizationErrorCode, options?: CreateErrorOptions): ExcelSanitizationError;
+export declare function limitExceeded(limit: SafetyLimitName, configured: number, actual: number, partName?: string): ExcelSanitizationError;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE1D,MAAM,MAAM,0BAA0B,GAClC,sBAAsB,GACtB,2BAA2B,GAC3B,iBAAiB,GACjB,kBAAkB,GAClB,oBAAoB,GACpB,qBAAqB,GACrB,eAAe,GACf,mBAAmB,GACnB,eAAe,GACf,gBAAgB,CAAC;AAErB,MAAM,WAAW,6BAA6B;IAC5C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC7C;AAED,UAAU,kBAAmB,SAAQ,6BAA6B;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,eAAe,GAAG,MAAM,uBAAuB,GAAG,WAAW,CAAC;AAgB1E,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,SAAkB,IAAI,4BAA4B;IAClD,QAAQ,CAAC,IAAI,EAAE,0BAA0B,CAAC;IAC1C,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAErD,YACE,IAAI,EAAE,0BAA0B,EAChC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,6BAAkC,EAO5C;CACF;AAED,wBAAgB,WAAW,CACzB,IAAI,EAAE,0BAA0B,EAChC,OAAO,GAAE,kBAAuB,GAC/B,sBAAsB,CAExB;AAED,wBAAgB,aAAa,CAC3B,KAAK,EAAE,eAAe,EACtB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,MAAM,GAChB,sBAAsB,CASxB"}

package/dist/formats.d.ts

@@ -0,0 +1,5 @@
+export type ExcelFileFormat = "xls" | "xlsx" | "xlsm";
+export declare function excelFileFormat(name: unknown): ExcelFileFormat | undefined;
+export declare function isExcelFilename(name: unknown): name is string;
+export declare function isXlsxFilename(name: unknown): name is string;
+//# sourceMappingURL=formats.d.ts.map

package/dist/formats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formats.d.ts","sourceRoot":"","sources":["../src/formats.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;AAEtD,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,eAAe,GAAG,SAAS,CAQ1E;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,MAAM,CAE7D;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,MAAM,CAE5D"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { sanitizeExcel } from "./api/sanitize-excel.js";
+export { isExcelFilename, isXlsxFilename, sanitizeExcelFile } from "./api/sanitize-excel-file.js";
+export { DEFAULT_LIMITS } from "./constants.js";
+export { ExcelSanitizationError } from "./errors.js";
+export type { ExcelSanitizationErrorCode, ExcelSanitizationErrorOptions } from "./errors.js";
+export type { ExcelFileFormat } from "./formats.js";
+export type { ExcelSanitizationLimits, SanitizeExcelFileOptions, SanitizeExcelOptions, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAClG,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACrD,YAAY,EAAE,0BAA0B,EAAE,6BAA6B,EAAE,MAAM,aAAa,CAAC;AAC7F,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,YAAY,EACV,uBAAuB,EACvB,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,YAAY,CAAC"}