# whatwg-encoding

> Decode strings according to the WHATWG Encoding Standard

Latest version **3.1.1** (published 2023-11-12) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install whatwg-encoding
pnpm add whatwg-encoding
yarn add whatwg-encoding
bun add whatwg-encoding
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 3.1.1 |
| Published | 2023-11-12 |
| First published | 2016-10-16 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/whatwg-encoding) |
| Module format | CommonJS |
| Node | >=18 |
| Dependencies | 1 |
| Unpacked size | 13 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 26 |
| Author | Domenic Denicola |
| Maintainers | timothygu, domenic, sebmaster, zirro, tmpvar, joris-van-der-wel |
| Keywords | encoding, whatwg |

## Links

- npm: https://www.npmjs.com/package/whatwg-encoding
- Repository: https://github.com/jsdom/whatwg-encoding
- Homepage: https://github.com/jsdom/whatwg-encoding#readme
- Issues: https://github.com/jsdom/whatwg-encoding/issues
- npm.io page: https://npm.io/package/whatwg-encoding

## Dependencies (1)

- [iconv-lite](https://npm.io/package/iconv-lite.md) 0.6.3

## Alternatives

- [flatbuffers](https://npm.io/package/flatbuffers.md) — 6.0M weekly downloads
- [jwt-simple](https://npm.io/package/jwt-simple.md) — 259.5K weekly downloads
- [@exodus/patch-broken-hermes-typed-arrays](https://npm.io/package/@exodus/patch-broken-hermes-typed-arrays.md) — 28.5K weekly downloads
- [@native-to-anchor/buffer-layout](https://npm.io/package/@native-to-anchor/buffer-layout.md) — 12.2K weekly downloads
- [binary-parser-encoder](https://npm.io/package/binary-parser-encoder.md) — 5.3K weekly downloads

## Recent versions

- 3.1.1 (latest) — 2023-11-12
- 3.1.0 — 2023-11-12
- 3.0.0 — 2023-11-07
- 2.0.0 — 2021-09-12
- 1.0.5 — 2018-09-30
- 1.0.4 — 2018-08-13
- 1.0.3 — 2017-10-29
- 1.0.2 — 2017-10-23
- 1.0.1 — 2016-10-16
- 1.0.0 — 2016-10-16

## README

# Decode According to the WHATWG Encoding Standard

This package provides a thin layer on top of [iconv-lite](https://github.com/ashtuchkin/iconv-lite) which makes it expose some of the same primitives as the [Encoding Standard](https://encoding.spec.whatwg.org/).

```js
const whatwgEncoding = require("whatwg-encoding");

console.assert(whatwgEncoding.labelToName("latin1") === "windows-1252");
console.assert(whatwgEncoding.labelToName("  CYRILLic ") === "ISO-8859-5");

console.assert(whatwgEncoding.isSupported("IBM866") === true);

// Not supported by the Encoding Standard
console.assert(whatwgEncoding.isSupported("UTF-32") === false);

// In the Encoding Standard, but this package can't decode it
console.assert(whatwgEncoding.isSupported("x-mac-cyrillic") === false);

console.assert(whatwgEncoding.getBOMEncoding(new Uint8Array([0xFE, 0xFF])) === "UTF-16BE");
console.assert(whatwgEncoding.getBOMEncoding(new Uint8Array([0x48, 0x69])) === null);

console.assert(whatwgEncoding.decode(new Uint8Array([0x48, 0x69]), "UTF-8") === "Hi");
```

## API

- `decode(uint8Array, fallbackEncodingName)`: performs the [decode](https://encoding.spec.whatwg.org/#decode) algorithm (in which any BOM will override the passed fallback encoding), and returns the resulting string
- `labelToName(label)`: performs the [get an encoding](https://encoding.spec.whatwg.org/#concept-encoding-get) algorithm and returns the resulting encoding's name, or `null` for failure
- `isSupported(name)`: returns whether the encoding is one of [the encodings](https://encoding.spec.whatwg.org/#names-and-labels) of the Encoding Standard, _and_ is an encoding that this package can decode (via iconv-lite)
- `getBOMEncoding(uint8Array)`: sniffs the first 2–3 bytes of the supplied `Uint8Array`, returning one of the encoding names `"UTF-8"`, `"UTF-16LE"`, or `"UTF-16BE"` if the appropriate BOM is present, or `null` if no BOM is present

## Unsupported encodings

Since we rely on iconv-lite, we are limited to support only the encodings that they support. Currently we are missing support for:

- ISO-2022-JP
- ISO-8859-8-I
- replacement
- x-mac-cyrillic
- x-user-defined

Passing these encoding names will return `false` when calling `isSupported`, and passing any of the possible labels for these encodings to `labelToName` will return `null`.

## Credits

This package was originally based on the excellent work of [@nicolashenry](https://github.com/nicolashenry), [in jsdom](https://github.com/tmpvar/jsdom/blob/7ce11776ce161e8d5921a7a183585327400f786b/lib/jsdom/living/helpers/encoding.js). It has since been pulled out into this separate package.

## Alternatives

If you are looking for a JavaScript implementation of the Encoding Standard's `TextEncoder` and `TextDecoder` APIs, you'll want [@inexorabletash](https://github.com/inexorabletash)'s [text-encoding](https://github.com/inexorabletash/text-encoding) package. Node.js also has them [built-in](https://nodejs.org/dist/latest/docs/api/globals.html#globals_textdecoder).

---
_Source: https://npm.io/package/whatwg-encoding · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._