Loading & saving

Wrap an ArrayBuffer or Uint8Array. The bytes are referenced (Uint8Array input) or wrapped without copy (ArrayBuffer input).

function fromArrayBuffer(buf: ArrayBuffer | Uint8Array<ArrayBufferLike>): XlsxSource

Wrap a Blob (or File, since File extends Blob) as an XlsxSource. The source materialises bytes lazily on the first XlsxSource.toBytes call.

function fromBlob(blob: Blob): XlsxSource

Wrap a fetch Response as an XlsxSource. `toBytes` collects the entire response body via `Response.arrayBuffer()`; `toStream` returns `response.body` directly so the ZIP reader can pull chunks lazily from the network. The Response can have been fetched with any method and content-type; this helper does no validation.

function fromResponse(response: Response): XlsxSource

Wrap a Web ReadableStream of bytes as an XlsxSource. `toStream` returns the stream directly; `toBytes` drains it once and caches the bytes. Streams can only be consumed once — calling `toBytes` after `toStream` (or vice versa) on the same source throws.

function fromStream(stream: ReadableStream<Uint8Array<ArrayBufferLike>>): XlsxSource

In-memory ArrayBuffer sink.

function toArrayBuffer(): XlsxSink & { result: unknown; toBytes: unknown }

In-memory Blob sink. Convenience `result()` returns the accumulated payload as a Blob with the supplied MIME type.

function toBlob(mime?: string): XlsxSink & { result: unknown; toBytes: unknown }

Wrap a filesystem path as an XlsxSource. `toBytes` reads the whole file into memory; `toStream` opens a `fs.createReadStream` and bridges it to a Web ReadableStream via `Readable.toWeb` so the ZIP reader can iterate without loading the entire xlsx up front.

function fromFile(path: string): XlsxSource

Synchronous variant of fromFile. Convenience for tooling / scripts where the cost of `await fs.readFile` outweighs the ergonomic gain. The returned source's `toBytes` resolves immediately with the bytes already in memory.

function fromFileSync(path: string): XlsxSource

Wrap a Node.js Readable as an XlsxSource. `toBytes` consumes the entire stream synchronously (collecting chunks); `toStream` bridges to a Web ReadableStream via `Readable.toWeb` so the ZIP reader can pull chunks lazily.

function fromReadable(readable: Readable): XlsxSource

Filesystem sink. Each `write(chunk)` call streams the bytes to disk via `fs.createWriteStream`, honouring backpressure: the actual `writable.write` for each chunk is queued behind any pending `drain`, so the writable's internal buffer never grows past its `highWaterMark` (default 16 KB) no matter how fast the producer hands chunks over. Note on the producer-side memory budget: the sink contract is intentionally synchronous (`write(chunk): void`), so a producer that races ahead without yielding will let chunk references pile up in the queue. That keeps `writable`'s buffer bounded but does not bound the queue itself. Producers that need a hard ceiling should yield between writes (`await new Promise(setImmediate)` is enough) or use a sink with an async write contract. `result()` returns the destination path; `finish()` resolves with an empty `Uint8Array` once the stream has flushed. Callers that need the on-disk bytes should `readFile()` the returned path themselves — re-reading inside `finish()` would defeat the "streamed to disk, never resident" guarantee.

function toFile(path: string): XlsxSink & { result: unknown; toBytes: unknown }

Wrap a Node.js Writable as an XlsxSink. The actual `writable.write` for each chunk is queued behind any pending `drain`, so the writable's internal buffer never exceeds its `highWaterMark` regardless of how fast the producer is. See toFile for the same caveat about producer-side memory: the synchronous `write(chunk)` API does not let backpressure flow back to the caller, so a tight non-yielding producer can still let chunk references accumulate in the queue. `result()` returns the writable itself for downstream chaining.

function toWritable(writable: Writable): XlsxSink & { result: unknown; toBytes: unknown }

Wrap a Buffer or Uint8Array as an XlsxSource. The underlying bytes are referenced — no copy — so callers must not mutate them while the source is in use.

function fromBuffer(buf: Uint8Array<ArrayBufferLike> | Buffer<ArrayBufferLike>): XlsxSource

In-memory Buffer sink. The buffered path concatenates appended chunks into a single allocation when BufferedSinkWriter.finish resolves; the convenience `result()` returns it as a Node Buffer.

function toBuffer(): XlsxSink & { result: unknown; toBytes: unknown }

Save a workbook through the given sink. Returns once `finalize()` resolves.

function saveWorkbook(wb: Workbook, sink: XlsxSink, _opts?: SaveOptions): Promise<void>

Convenience: serialise a Workbook to an in-memory `Uint8Array` xlsx. Browser-safe: this path uses an in-memory `Uint8Array` sink and never touches Node's `Buffer` global, so it works unchanged in browser bundles.

function workbookToBytes(wb: Workbook, opts?: SaveOptions): Promise<Uint8Array<ArrayBufferLike>>

Load a workbook from any XlsxSource. Currently produces a scaffold Workbook: each Worksheet is empty (no cells / styles / shared strings / theme yet). The next phase-3 iterations layer those in atop the same skeleton.

function loadWorkbook(source: XlsxSource, opts?: LoadOptions): Promise<Workbook>