Skip to content

bun-types: accept every TextDecoder encoding label the runtime supports #40119

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Jarred-Sumner merged 4 commits into from
Aug 23, 2026
Merged

bun-types: accept every TextDecoder encoding label the runtime supports #40119

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
0f7c804
bun-types: widen Encoding to every label the TextDecoder runtime accepts
robobun Aug 22, 2026
6c40b4f
test: check the fixture encoding labels against the running binary
robobun Aug 22, 2026
ddc0b3b
[autofix.ci] apply automated fixes
autofix-ci[bot] Aug 22, 2026
9f6e8f8
test: assert the fixture encoding labels are unique
robobun Aug 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
272 changes: 271 additions & 1 deletion packages/bun-types/bun.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,277 @@ declare module "bun" {
type ReadableStreamReader<T> = ReadableStreamDefaultReader<T>;
type Transferable = ArrayBuffer | MessagePort;
type MessageEventSource = Bun.__internal.UseLibDomIfAvailable<"MessageEventSource", undefined>;
type Encoding = "utf-8" | "windows-1252" | "utf-16";
/**
* An encoding label from the WHATWG Encoding Standard, as accepted by the
* `TextDecoder` constructor.
*
* The labels of the `replacement` encoding are excluded: the `TextDecoder`
* constructor rejects them with a `RangeError`.
*
* @see https://encoding.spec.whatwg.org/#names-and-labels
*/
type Encoding =
// utf-8
| "unicode-1-1-utf-8"
| "unicode11utf8"
| "unicode20utf8"
| "utf-8"
| "utf8"
| "x-unicode20utf8"
// ibm866
| "866"
| "cp866"
| "csibm866"
| "ibm866"
// iso-8859-2
| "csisolatin2"
| "iso-8859-2"
| "iso-ir-101"
| "iso8859-2"
| "iso88592"
| "iso_8859-2"
| "iso_8859-2:1987"
| "l2"
| "latin2"
// iso-8859-3
| "csisolatin3"
| "iso-8859-3"
| "iso-ir-109"
| "iso8859-3"
| "iso88593"
| "iso_8859-3"
| "iso_8859-3:1988"
| "l3"
| "latin3"
// iso-8859-4
| "csisolatin4"
| "iso-8859-4"
| "iso-ir-110"
| "iso8859-4"
| "iso88594"
| "iso_8859-4"
| "iso_8859-4:1988"
| "l4"
| "latin4"
// iso-8859-5
| "csisolatincyrillic"
| "cyrillic"
| "iso-8859-5"
| "iso-ir-144"
| "iso8859-5"
| "iso88595"
| "iso_8859-5"
| "iso_8859-5:1988"
// iso-8859-6
| "arabic"
| "asmo-708"
| "csiso88596e"
| "csiso88596i"
| "csisolatinarabic"
| "ecma-114"
| "iso-8859-6"
| "iso-8859-6-e"
| "iso-8859-6-i"
| "iso-ir-127"
| "iso8859-6"
| "iso88596"
| "iso_8859-6"
| "iso_8859-6:1987"
// iso-8859-7
| "csisolatingreek"
| "ecma-118"
| "elot_928"
| "greek"
| "greek8"
| "iso-8859-7"
| "iso-ir-126"
| "iso8859-7"
| "iso88597"
| "iso_8859-7"
| "iso_8859-7:1987"
| "sun_eu_greek"
// iso-8859-8
| "csiso88598e"
| "csisolatinhebrew"
| "hebrew"
| "iso-8859-8"
| "iso-8859-8-e"
| "iso-ir-138"
| "iso8859-8"
| "iso88598"
| "iso_8859-8"
| "iso_8859-8:1988"
| "visual"
// iso-8859-8-i
| "csiso88598i"
| "iso-8859-8-i"
| "logical"
// iso-8859-10
| "csisolatin6"
| "iso-8859-10"
| "iso-ir-157"
| "iso8859-10"
| "iso885910"
| "l6"
| "latin6"
// iso-8859-13
| "iso-8859-13"
| "iso8859-13"
| "iso885913"
// iso-8859-14
| "iso-8859-14"
| "iso8859-14"
| "iso885914"
// iso-8859-15
| "csisolatin9"
| "iso-8859-15"
| "iso8859-15"
| "iso885915"
| "iso_8859-15"
| "l9"
// iso-8859-16
| "iso-8859-16"
// koi8-r
| "cskoi8r"
| "koi"
| "koi8"
| "koi8-r"
| "koi8_r"
// koi8-u
| "koi8-ru"
| "koi8-u"
// macintosh
| "csmacintosh"
| "mac"
| "macintosh"
| "x-mac-roman"
// windows-874
| "dos-874"
| "iso-8859-11"
| "iso8859-11"
| "iso885911"
| "tis-620"
| "windows-874"
// windows-1250
| "cp1250"
| "windows-1250"
| "x-cp1250"
// windows-1251
| "cp1251"
| "windows-1251"
| "x-cp1251"
// windows-1252
| "ansi_x3.4-1968"
| "ascii"
| "cp1252"
| "cp819"
| "csisolatin1"
| "ibm819"
| "iso-8859-1"
| "iso-ir-100"
| "iso8859-1"
| "iso88591"
| "iso_8859-1"
| "iso_8859-1:1987"
| "l1"
| "latin1"
| "us-ascii"
| "windows-1252"
| "x-cp1252"
// windows-1253
| "cp1253"
| "windows-1253"
| "x-cp1253"
// windows-1254
| "cp1254"
| "csisolatin5"
| "iso-8859-9"
| "iso-ir-148"
| "iso8859-9"
| "iso88599"
| "iso_8859-9"
| "iso_8859-9:1989"
| "l5"
| "latin5"
| "windows-1254"
| "x-cp1254"
// windows-1255
| "cp1255"
| "windows-1255"
| "x-cp1255"
// windows-1256
| "cp1256"
| "windows-1256"
| "x-cp1256"
// windows-1257
| "cp1257"
| "windows-1257"
| "x-cp1257"
// windows-1258
| "cp1258"
| "windows-1258"
| "x-cp1258"
// x-mac-cyrillic
| "x-mac-cyrillic"
| "x-mac-ukrainian"
// gbk
| "chinese"
| "csgb2312"
| "csiso58gb231280"
| "gb2312"
| "gb_2312"
| "gb_2312-80"
| "gbk"
| "iso-ir-58"
| "x-gbk"
// gb18030
| "gb18030"
// big5
| "big5"
| "big5-hkscs"
| "cn-big5"
| "csbig5"
| "x-x-big5"
// euc-jp
| "cseucpkdfmtjapanese"
| "euc-jp"
| "x-euc-jp"
// iso-2022-jp
| "csiso2022jp"
| "iso-2022-jp"
// shift_jis
| "csshiftjis"
| "ms932"
| "ms_kanji"
| "shift-jis"
| "shift_jis"
| "sjis"
| "windows-31j"
| "x-sjis"
// euc-kr
| "cseuckr"
| "csksc56011987"
| "euc-kr"
| "iso-ir-149"
| "korean"
| "ks_c_5601-1987"
| "ks_c_5601-1989"
| "ksc5601"
| "ksc_5601"
| "windows-949"
// utf-16be
| "unicodefffe"
| "utf-16be"
// utf-16le
| "csunicode"
| "iso-10646-ucs-2"
| "ucs-2"
| "unicode"
| "unicodefeff"
| "utf-16"
| "utf-16le"
// x-user-defined
| "x-user-defined";
Comment thread
coderabbitai[bot] marked this conversation as resolved.
type UncaughtExceptionOrigin = "uncaughtException" | "unhandledRejection";
type MultipleResolveType = "resolve" | "reject";
type BeforeExitListener = (code: number) => void;
Expand Down
5 changes: 3 additions & 2 deletions packages/bun-types/globals.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -252,8 +252,9 @@ declare var TextEncoder: Bun.__internal.UseLibDomIfAvailable<
>;

/**
* An implementation of the [WHATWG Encoding Standard](https://encoding.spec.whatwg.org/) `TextDecoder` API. All
* instances of `TextDecoder` only support UTF-8 decoding.
* An implementation of the [WHATWG Encoding Standard](https://encoding.spec.whatwg.org/) `TextDecoder` API.
* Supports every encoding label the standard defines, except the labels of the
* `replacement` encoding.
*
* ```js
* const decoder = new TextDecoder();
Expand Down
74 changes: 74 additions & 0 deletions test/integration/bun-types/bun-types.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -400,6 +400,80 @@ describe("@types/bun integration test", () => {
});
});

// Runs on debug builds too, same as the Bun.mmap block above.
describe("TextDecoder", () => {
test("accepts the encoding labels the runtime supports", async () => {
const checkDir = join(TEMP_DIR, "text-decoder-encoding-check");
const tsconfig = structuredClone(sourceTsconfig);
tsconfig.include = ["text-decoder-encodings.ts"];
tsconfig.compilerOptions.typeRoots = [join(BASE_FIXTURE_DIR, "node_modules", "@types")];
await mkdir(checkDir, { recursive: true });
await makeTree(checkDir, {
"tsconfig.json": JSON.stringify(tsconfig, null, 2),
"text-decoder-encodings.ts": `new TextDecoder("windows-1251");
new TextDecoder("shift_jis");
new TextDecoder("utf8");
new TextDecoder("latin1");
new TextDecoder("gb18030", { fatal: true, ignoreBOM: true });
// @ts-expect-error - the TextDecoder constructor rejects the replacement encoding
"hz-gb-2312" satisfies Bun.Encoding;
// @ts-expect-error - not a label the Encoding Standard defines
"utf-99" satisfies Bun.Encoding;`,
});

await using proc = Bun.spawn({
cmd: [bunExe(), join(BASE_FIXTURE_DIR, "node_modules", "typescript", "bin", "tsc"), "-p", "."],
env: bunEnv,
cwd: checkDir,
stdout: "pipe",
stderr: "pipe",
});

const [stdout, stderr, exitCode] = await Promise.all([proc.stdout.text(), proc.stderr.text(), proc.exited]);

expect(stderr.trim()).toBe("");
expect(stdout.trim()).toBe("");
expect(exitCode).toBe(0);
});

// tsc cannot read the runtime's label table in
// src/runtime/webcore/EncodingLabel.rs, so the fixture carries a literal
// copy. This check ties that copy to the running binary: every fixture
// label must construct, and the replacement labels must throw.
test("the fixture label table matches the runtime", () => {
const fixture = readFileSync(join(FIXTURE_SOURCE_DIR, "text-encode-decoder.ts"), "utf8");
const arrayStart = fixture.indexOf("const labels = [");
const arrayEnd = fixture.indexOf("] as const;", arrayStart);
expect(arrayStart).toBeGreaterThan(-1);
expect(arrayEnd).toBeGreaterThan(arrayStart);

const labels = [...fixture.slice(arrayStart, arrayEnd).matchAll(/"([^"]+)"/g)].map(m => m[1]);
expect(labels).toHaveLength(222);
Comment thread
coderabbitai[bot] marked this conversation as resolved.
expect(new Set(labels).size).toBe(labels.length);

const rejected = labels.filter(label => {
try {
new TextDecoder(label as Bun.Encoding);
return false;
} catch {
return true;
}
});
expect(rejected).toEqual([]);

for (const label of [
"csiso2022kr",
"hz-gb-2312",
"iso-2022-cn",
"iso-2022-cn-ext",
"iso-2022-kr",
"replacement",
]) {
expect(() => new TextDecoder(label as Bun.Encoding)).toThrow(RangeError);
}
});
});

describe("Test Globals", () => {
const code = `
const test_shouldBeAFunction: Function = test;
Expand Down
Loading