SSF formatting API

XLSX.SSF formats values using spreadsheet number-format codes. It produces text; it does not change a cell’s stored value or evaluate formulas. The namespace is typed as any in the bundled declarations.

Format values

Signature	Parameters	Returns
format(format, value, options?)	format is a format string or built-in format index; value is the value to display	Formatted string
is_date(format)	A format-code string	Boolean indicating whether the code is a date/time format
parse_date_code(serial, options?)	Numeric spreadsheet date serial; options.date1904 selects the 1904 system	Date-parts object, or null for an invalid serial

Formatting options include date1904 for serial-date interpretation and dateNF for the default date format. Date parsing returns fields y, m, d, H, M, S plus D (whole serial days), T (whole seconds), u (fractional seconds), and q (weekday). This is not a JavaScript Date object.

const XLSX = require("@agent-sheet/wasm");
const assert = require("node:assert/strict");
assert.equal(XLSX.SSF.format("0.00", 12.5), "12.50");
assert.equal(XLSX.SSF.is_date("yyyy-mm-dd"), true);
assert.equal(XLSX.SSF.is_date("#,##0.00"), false);
const parts = XLSX.SSF.parse_date_code(45000);
assert.equal(parts.y, 2023);
assert.equal(parts.m, 3);
assert.equal(parts.d, 15);

Built-in format 14 is the default short date format. Excel serial dates have historical calendar rules, including the 1900 leap-year quirk; use the serial formatter rather than treating a serial as Unix milliseconds.

See Number formats and dates.

Format table

Signature	Parameters and semantics	Returns
get_table()	Get the current indexed format table	Format table object
load(format, index?)	Register a format string at index, or choose an available index	Assigned format index
load_table(table)	Load indexed format strings from a table	No result to consume
init_table(table)	Initialize a supplied table with built-in formats	No result to consume
version	Formatter version, separate from the package version	String

Custom format indexes are useful when the same format is used repeatedly. The table belongs to the library instance; changes can affect later formatting and reads in that instance.

const XLSX = require("@agent-sheet/wasm");
const assert = require("node:assert/strict");
const index = XLSX.SSF.load("0.000", 164);
assert.equal(index, 164);
assert.equal(XLSX.SSF.format(index, 1.2), "1.200");
assert.equal(XLSX.SSF.get_table()[index], "0.000");

Locale

Signature	Parameters and semantics	Returns
setlocale(locale)	Select an IETF language tag, such as "de-DE"	No result to consume
getlocale()	Read the current locale setting	Locale string
normalize(format)	Convert a localized format code to the stored US form using the current locale	Format string

Set the locale before reading files if generated cell text (w) should use it. Locale affects group/decimal separators, month/day names, built-in date format 14, and locale-specific formats. Locale data comes from the host’s Intl, so exact localized text depends on that host’s locale data.

const XLSX = require("@agent-sheet/wasm");
const assert = require("node:assert/strict");
XLSX.SSF.setlocale("de-DE");
assert.equal(XLSX.SSF.getlocale(), "de-DE");
assert.equal(XLSX.SSF.normalize("jjjj-mm-tt"), "yyyy-mm-dd");
assert.equal(XLSX.SSF.normalize("#.##0,00"), "#,##0.00");
XLSX.SSF.setlocale("en-US");

Currency

Signature	Parameters and semantics	Returns
setcurrency(code)	Select an ISO 4217 currency code, such as "EUR"	No result to consume
getcurrency()	Read the selected code	Currency-code string

Currency is independent of locale. Call setlocale first to initialize locale information. On a fresh instance, setcurrency alone can throw Incorrect locale information provided, as in the original package.

const XLSX = require("@agent-sheet/wasm");
const assert = require("node:assert/strict");
XLSX.SSF.setlocale("en-US");
XLSX.SSF.setcurrency("EUR");
assert.equal(XLSX.SSF.getcurrency(), "EUR");
assert.equal(XLSX.SSF.format("$#,##0.00", 5), "€5.00");
XLSX.SSF.setcurrency("USD");

These settings are global to the current JavaScript realm, not per workbook. See Locale support for localized reading examples.

Other exposed properties

_table is the exposed format-table property. vars holds formatter settings. The namespace also exposes underscore-prefixed formatter routines (_general, _general_int, _general_num, _split, and _eval). Prefer the operations above rather than depending on these lower-level routines for application code.