windows-1252

windows-1252 is a zero-dependency JavaScript library that implements the windows-1252 single-byte character encoding exactly as defined by the WHATWG Encoding Standard. It exposes encode and decode functions that convert between plain-text strings and byte-level representations, plus a labels array of every recognized alias for the encoding (latin1, iso-8859-1, cp1252, ascii, and more) for charset-name detection.

Written by Mathias Bynens, the maintainer behind punycode.js and he.js, the library favors spec-accuracy over convenience: both fatal and replacement error modes are supported for encoding and decoding, matching the WHATWG algorithm’s error-handling model precisely. It ships as native ESM with bundled TypeScript declarations and no runtime dependencies, making it a lightweight drop-in for legacy text processing, email parsing, and file-format handling in Node.js and browser environments.

What You Get

• Spec-accurate encode() and decode() functions implementing the WHATWG Encoding Standard’s single-byte algorithms byte-for-byte
• A labels array covering every recognized alias for the encoding (latin1, iso-8859-1, cp1252, ascii, and more) for encoding-name detection
• Configurable error modes (fatal and replacement) matching the spec’s error-handling semantics for both directions
• Native ESM distribution with bundled TypeScript declarations and zero runtime dependencies

Common Use Cases

• Decoding legacy web content or email bodies served with a windows-1252/latin1 charset label
• Building a general-purpose text-encoding library that needs spec-compliant single-byte codec coverage
• Reading or writing legacy file formats (old CSVs, config files, log exports) authored on Windows systems
• Normalizing user-supplied charset names against the WHATWG label list before choosing a decoder

Under The Hood

Architecture The distributed module (windows-1252.mjs) is a single flat file exporting two pure functions (encode, decode) and a labels array, backed by two static Map lookup tables (INDEX_BY_CODE_POINT, INDEX_BY_POINTER). Those tables aren’t hand-written — they’re generated at build time by scripts/transform-data.js, which reads the WHATWG spec’s own data/index.txt file and renders it into src/windows-1252.src.mjs via a lodash.template template, then minifies the strings with jsesc. There is no layering, no dependency injection, and no abstraction beyond the codec itself; because this is a leaf library with no internal consumers to decouple, that flatness is appropriate rather than a smell. Changing the underlying byte-mapping data means re-running the build against a refreshed spec index file, not editing the shipped module directly.

Tech Stack Plain JavaScript distributed as native ESM (package.json’s exports field points straight at windows-1252.mjs, no bundler or transpilation step for consumers). The only devDependencies are istanbul (coverage), lodash.template and jsesc (both used solely by the code-generation script), so the runtime has zero dependencies. TypeScript consumers get a hand-authored windows-1252.d.ts shipped alongside the JS rather than a tsc-derived one.

Code Quality Tests (tests/tests.mjs, itself generated from tests/tests.src.mjs) use Node’s built-in assert module and exhaustively check every code point in both directions, both error modes (fatal and replacement), case-insensitive mode-name handling, and both accepted decode() input shapes (Uint16Array and byte-string). CI (GitHub Actions, run-checks workflow) runs npm run build && npm test across a Node 12/14/16 matrix on every push and pull request. There is no linter or formatter configuration in the repo, and no tsc typecheck step — types are maintained by hand rather than derived from source. Error handling is explicit and spec-driven throughout (throws or returns a replacement value, never swallows silently).

API Design The public surface is intentionally tiny — three exports (encode, decode, labels) — and mirrors the WHATWG spec’s own vocabulary (fatal/replacement error modes) so behavior maps directly onto the standard instead of inventing bespoke naming. decode() accepts either a Uint16Array or a legacy byte-string, reducing friction for callers coming from either representation. The README documents runnable examples for both directions and both error modes. It deliberately doesn’t attempt to be a general charset-sniffing or streaming decoder, staying narrowly scoped to one legacy encoding — a reasonable trade-off, though not a technically novel one.