TypeScript

The package ships declarations in types/index.d.ts. The package entry resolves the declarations automatically. No separate types package is needed.

The runtime is CommonJS. In a Node ES module, use a default import; named runtime imports such as import { utils } from "@agent-sheet/wasm" are not supported.

Import the library

With a configuration that supports CommonJS default imports, use:

import XLSX from "@agent-sheet/wasm";
import type { CellObject, WorkBook, WorkSheet, WritingOptions } from "@agent-sheet/wasm";

const sheet: WorkSheet = XLSX.utils.aoa_to_sheet([["Item", "Qty"], ["Pens", 4]]);
const workbook: WorkBook = XLSX.utils.book_new();
XLSX.utils.book_append_sheet(workbook, sheet, "Stock");

const options: WritingOptions = { type: "buffer", bookType: "xlsx" };
const output = XLSX.write(workbook, options);

For TypeScript compiled as CommonJS, an import assignment is another option:

import XLSX = require("@agent-sheet/wasm");

const workbook = XLSX.utils.book_new();
XLSX.utils.book_append_sheet(workbook, XLSX.utils.aoa_to_sheet([[1]]), "Data");

Choose module and moduleResolution for your application host. When using the default import, esModuleInterop: true is a common CommonJS-interoperability setting. Type-only imports are erased and do not request named runtime exports.

Main types

Type	Shape / purpose
WorkBook	SheetNames: string[] and Sheets: Record<string, WorkSheet>, plus optional metadata
WorkSheet	Cell-address properties plus !-prefixed metadata
DenseWorkSheet	Cells in a required !data array
CellObject	t plus optional v, w, f, F, D, z, s, R, h, c, and l
CellAddress	Zero-based { r: number, c: number }
Range	Inclusive { s: CellAddress, e: CellAddress }
WSSpec	Sheet name, zero-based index or worksheet object
RangeSpec	Range text, range object or cell address
CellSpec	A1 cell text or cell address
ParsingOptions	Read options
WritingOptions	Write options
Style, StyleZ	Cell styles; StyleZ adds number format and interior borders
DataValidation, ConditionalFormat	Validation and conditional-format entries
TemplateControl	Control object returned by template control helpers
Pivot	Pivot definition accepted by template_add_pivot

Cell types are "b" (boolean), "n" (number), "e" (error), "s" (string), "d" (date), and "z" (blank stub). v is a union, not narrowed automatically by t. Check the value type before numeric operations in strict application code.

import type { CellObject } from "@agent-sheet/wasm";

function numericValue(cell: CellObject | undefined): number | undefined {
  if (cell?.t !== "n" || typeof cell.v !== "number") return undefined;
  return cell.v;
}

Conversion result types

sheet_to_json<Row>(sheet, options) lets you state an expected output row shape. The generic is not runtime validation. Validate files from users before relying on every row matching that shape.

import XLSX from "@agent-sheet/wasm";

type StockRow = { Item: string; Qty: number };
const sheet = XLSX.utils.aoa_to_sheet([["Item", "Qty"], ["Pen", 3]]);
const rows = XLSX.utils.sheet_to_json<StockRow>(sheet);

SSF and CFB are declared as any; Node streams also have loose return types. Consult the SSF, CFB and stream reference pages for their runtime contracts.

Known declaration/runtime differences

Declarations preserve some names from the original @sheet/edit package and are not a guarantee that every declared feature is present:

Declaration	Runtime behavior
utils.hash_password, utils.test_password	Not defined; calls fail
utils.consts.SHEET_VERYHIDDEN	Not defined; use SHEET_VERY_HIDDEN
BookType union	Omits runtime-supported xlam, biff3, biff4, wk1, wk3
set_date_style(style: number)	Compatibility helper also accepts a number-format string at runtime
Template protection parameters	Runtime also accepts null to remove protection or clear flags
CellObject.f?: string	Template edits also accept f: null to clear a formula
writeFileAsync callback	Declared as zero-argument; Node file completion can provide an error
WorkBook fields	Metadata-only reads can omit normal fields; bookFiles adds package data not listed here

For the omitted format identifiers, a narrowly scoped type assertion on the option is possible after checking the runtime-supported format list. Do not use a broad any cast for the whole workbook. For protection removal, a narrow local wrapper can describe the extra null case your application needs.

New code should use the actual runtime template names template_sheet_set_visibility and template_book_remove_name. See Template helper reference.

Type acceptance also does not guarantee that a format writes every metadata field. Review Supported formats and the relevant feature guide before relying on round-trip preservation.