OptionalasOpen the source as a copy: the workbook gets its own read-only origin for the same path, so it never saves back over the original — its first save asks where.
OptionalcalcWhat loading is allowed to calculate — ICellContainerOptions.calcOnLoad, with the format handler translating what the FILE says into it.
'auto' — cached values are trusted; the load pass evaluates a formula cell with no
cached value (a repair — Excel always stores one) and refreshes volatiles. Everything is
recalculated only when Excel would recalculate on open: the file sets fullCalcOnLoad,
or for xlsx its calcId is missing or older than the Excel build this library is
verified against. (What this library writes carries one: the source file's, else that
build's.) To take the file's values as they are whatever it says — as openpyxl does —
pass 'none'; to always recalculate, 'full'.'full' — everything is recalculated, whatever the file says.'none' — the calculation engine is not started. Nothing is compiled or calculated, and
a save writes values and formulas exactly as they were read — the pure IO pass. The
first mutation, or an explicit ICalculation.calculate /
IWorkbook.whenCalculationReady, starts the engine.An explicit createWorkbookOptions.calcOnLoad wins over the translation.
OptionalcalcRead the workbook for calculation only, trading visual formatting for a faster, lighter read.
Use this when you need the data — values, formulas, and number formats — but not how it looks: headless calculation, server-side processing, data extraction. Calculated results are always correct; purely visual formatting (fonts, fills, borders, charts, images, …) may be skipped to save time and memory.
OptionalcreateProvide options to the workbook constructor.
OptionalformatOptional file type hint (extension, MIME type, or import key).
Used for type detection when it cannot be inferred from the source. Examples: 'xlsx', 'csv', 'application/json', 'Excel'
OptionalpapaOptions specific for csv parsing.
OptionalpasswordPassword for an encrypted source.
Applies to file encryption (Excel's "password to open") — confidentiality of the bytes — and is handled by the IO layer for every format, not by any one format handler. It is unrelated to sheet/workbook protection, which is a hash-based UI gate stored in the model.
Ignored when the source is not encrypted. Prefer onPassword for interactive callers: it can re-prompt when a password is rejected.
OptionalprogressOptional progress callback for long running imports.
OptionalreadonlyIndicate the the workbook should be read-only.
OptionalsetOptions specific for setting values.
OptionalsourceThe io source for reading. Can be a direct value, Promise, or function.
OptionaltypedAllows for different constructor arguments depending on the type of format detected.
OptionalonCalled once when the source is encrypted and no usable password is in hand.
The handle being opened, plus PasswordRequest.validate for trying a password without ending the prompt.
The accepted password, or null to cancel — IWorkbookIO.read then resolves
to null, exactly as a dismissed open picker does.
The caller owns the retry loop. Use request.validate(password) to test a password and
keep prompting on false; return the password once it is accepted, or null when the user
gives up. The IO layer does not re-invoke this, so a dialog opens once and stays open —
rather than being torn down and rebuilt per attempt, which is visible as flicker.
A caller that skips validate and returns a password directly gets exactly one attempt, and
a wrong one raises InvalidPasswordError. That is the right shape for a non-interactive
caller (a script, a server), which has nothing to re-prompt.
Options for importing from CSV file format.
Remarks
The default options mimic Excel 2024.