fix(transformer/legacy-decorator): emit Array for ReadonlyArray<T> in decorator metadata by kylecannon · Pull Request #22265 · oxc-project/oxc

kylecannon · 2026-05-08T21:46:50Z

Summary

ReadonlyArray<T> is a TypeScript-only utility type with no runtime value. The legacy decorator metadata emit currently wraps it in the runtime guard typeof (_ref = typeof X !== "undefined" && X) === "function" ? _ref : Object, which always falls through to Object because there is no runtime ReadonlyArray binding. tsc resolves this through the checker and emits Array; OXC's existing handling of the short form readonly T[] already emits Array, so the generic form is the only divergent shape.

The bug

class Entity {
  @D() shortForm!: readonly string[];           // tsc: Array, OXC: Array  (already correct)
  @D() genericForm!: ReadonlyArray<string>;     // tsc: Array, OXC: Object (bug)
  @D() nestedReadonly!: ReadonlyArray<ReadonlyArray<number>>; // same
}

The two surface forms describe the same type but produce different runtime metadata. Downstream consumers (TypeORM @Column array inference, NestJS Swagger schema, AutoMapper field detection) rely on the Array constructor; Object causes silent degradation.

Fix

In serialize_type_reference_node, recognize ReadonlyArray by name when the symbol is unresolved or type-only. Emit global_array(ctx) directly, bypassing the wrapper. A user-shadowed class ReadonlyArray {} would have a value symbol and falls through to the normal class-handling path, so the shadow case is preserved.

if ident.name == "ReadonlyArray"
    && symbol_id.is_none_or(|sid| ctx.scoping().symbol_flags(sid).is_type())
{
    return Self::global_array(ctx);
}

Scope

Only ReadonlyArray is handled in this PR. ReadonlyMap, ReadonlySet, WeakMap, WeakSet, and Readonly<Array<T>> peel are left for a follow-up because tsc's spec emit for those is less unambiguous and warrants case-by-case verification. The same predicate-style approach extends naturally if reviewers want them folded in.

Test plan

4 unit tests in decorator_metadata_readonly_array.rs: bare ReadonlyArray, nested ReadonlyArray, regression on readonly T[] short form, and a user-shadowed class ReadonlyArray {} regression
New conformance fixture oxc/metadata/readonly-array/
cargo test -p oxc_transformer passes (31 unit + 9 integration)
cargo run -p oxc_transform_conformance shows 229 OXC fixtures still passing, +1 new fixture (readonly-array); 0 regressions
cargo fmt -p oxc_transformer and cargo clippy -p oxc_transformer --tests --no-deps clean

AI assistance was used in writing this patch and tests; the contributor has reviewed and tested locally.

@d

… decorator metadata `ReadonlyArray<T>` is a TypeScript-only utility type with no runtime value. The legacy decorator metadata emit currently wraps it in the runtime guard `typeof (_ref = typeof X !== "undefined" && X) === "function" ? _ref : Object`, which always falls through to `Object` because there is no runtime `ReadonlyArray` binding. tsc resolves this through the checker and emits `Array`; OXC's existing handling of the short form `readonly T[]` already emits `Array`, so the generic form is the only divergent shape. ```ts class Entity { @d() shortForm!: readonly string[]; // tsc: Array, OXC: Array (already correct) @d() genericForm!: ReadonlyArray<string>; // tsc: Array, OXC: Object (bug) @d() nestedReadonly!: ReadonlyArray<ReadonlyArray<number>>; // same } ``` The two surface forms describe the same type but produce different runtime metadata. Downstream consumers (TypeORM `@Column` array inference, NestJS Swagger schema, AutoMapper field detection) rely on the `Array` constructor; `Object` causes silent degradation. In `serialize_type_reference_node`, recognize `ReadonlyArray` by name when the symbol is unresolved or type-only. Emit `global_array(ctx)` directly, bypassing the wrapper. A user-shadowed `class ReadonlyArray {}` would have a value symbol and falls through to the normal class-handling path, so the shadow case is preserved. ```rust if ident.name == "ReadonlyArray" && symbol_id.is_none_or(|sid| ctx.scoping().symbol_flags(sid).is_type()) { return Self::global_array(ctx); } ``` Only `ReadonlyArray` is handled in this PR. `ReadonlyMap`, `ReadonlySet`, `WeakMap`, `WeakSet`, and `Readonly<Array<T>>` peel are left for a follow-up because tsc's spec emit for those is less unambiguous and warrants case-by-case verification. The same predicate-style approach extends naturally if reviewers want them folded in. - [x] 4 unit tests in `tests/integrations/decorator_metadata.rs`: bare ReadonlyArray, nested ReadonlyArray, regression on `readonly T[]` short form, and a user-shadowed `class ReadonlyArray {}` regression - [x] New conformance fixture `oxc/metadata/readonly-array/` - [x] `cargo test -p oxc_transformer` passes - [x] `cargo run -p oxc_transform_conformance` shows 0 regressions; 229 OXC fixtures still pass, plus the new `readonly-array` fixture - [x] `cargo fmt -p oxc_transformer` and `cargo clippy -p oxc_transformer --tests --no-deps` clean AI assistance was used in writing this patch and tests; the contributor has reviewed and tested locally.

…e to unresolved refs Only treat `ReadonlyArray` as the global lib type when the reference is truly unresolved (`symbol_id.is_none()`). The previous `is_type()` predicate also matched locally-declared `interface ReadonlyArray` and `type ReadonlyArray = …`, miscompiling them to `Array` despite the user's clearly-different local type. The `class ReadonlyArray {}` case continues to fall through (Class symbols have `is_type() == false`) and is covered by Kyle's existing test. Adds a conformance fixture for the interface-shadow case.

codspeed-hq · 2026-05-21T10:17:00Z

Merging this PR will not alter performance

✅ 52 untouched benchmarks
⏩ 8 skipped benchmarks¹

_{Comparing kylecannon:fix/decorator-metadata-readonly-array (485def7) with main (e421ef0)}

8 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

### 🚀 Features - e857b0c napi/minify: Expose legalComments option and result (#20370) (Boshen) - 661132d parser: More friendly error messages for rest assignment target and rest binding element (#22719) (sapphi-red) - ee659b6 transformer/legacy-decorator: Add `strictNullChecks` option for nullable-union design:type (#22266) (Kyle Cannon) ### 🐛 Bug Fixes - e1d064e transformer/class-properties: Reparent lifted private method helpers (#22716) (Cameron) - 4ac0fca minifier: Preserve `0 && (module.exports = { ... })` cjs-module-lexer hint (#22729) (Dunqing) - 40ff611 minifier: Mark peephole loop changed when dropping dead-after-throw statement (#22722) (Dunqing) - 2f7b210 codegen: Emit pife-arrow/function leading comments inside the wrap (#22720) (Dunqing) - e184f74 parser: Improve invalid `import` property access diagnostic (#22693) (camc314) - 7baed9c transformer/private-method: Clear inherited strict flags (#22508) (camc314) - a9ad27e parser: Keep annotation comments leading without preceding newline (#22711) (Dunqing) - 9ea4d64 minifier: Re-evaluate pure/no-side-effects flags after peephole inlining (#22595) (Dunqing) - 07afbb6 minifier: Drop empty-body IIFE wrapper when called with arguments (#22589) (Dunqing) - fa7c463 semantic: Correct TS enum member symbol spans (#22689) (camc314) - 26b9396 semantic: Resolve parameter decorators outside parameter scope (#22623) (camc314) - b284045 parser: Switch to module goal eagerly on `export` (#22684) (Boshen) - dfa931d semantic: Propagate unresolved auto-increment enum value instead of defaulting to 0 (#22646) (Dunqing) - 69a6ba6 transformer/legacy-decorator: Emit Array for ReadonlyArray<T> in decorator metadata (#22265) (Kyle Cannon) - e421ef0 transformer/legacy-decorator: Return runtime binding for design:type (#22640) (Dunqing) - d61e1d7 codegen: Preserve verbatim text of pure/no-side-effects comments (#22525) (Dunqing) - 702b14e minifier: Preserve IIFE structure in DCE-only mode (#22547) (Dunqing) - 917da24 parser: Apply PURE comment through member-access chains (#22566) (Dunqing) - a069b1c codegen: Preserve quotes for cjs-module-lexer equality strings (#22551) (Dunqing) ### ⚡ Performance - 2f623b0 semantic: Skip unresolved checks for re-exports (#22660) (camc314) - 0d9553d semantic: Early-exit `check_object_expression` for objects with <2 properties (#22668) (Dunqing) - d721ad9 semantic: Use direct grandparent lookup for TS type parameters (#22658) (camc314) - 0aff288 semantic: Reorder numeric literal strict mode checks (#22657) (camc314) - 4d5ddb1 semantic: Reorder binding identifier checks (#22656) (camc314) - e32acd8 semantic: Reorder identifier ambient binding check (#22653) (camc314) - 09fe178 semantic: Reorder ident reference strict mode check (#22652) (camc314) - 4b6add2 semantic: Avoid duplicate ident clone for bindings (#22663) (camc314) - 82f9662 parser: Check identifier kind before context flag (#22662) (camc314) - d7cd951 parser: Fast path identifier parsing and inline operator helpers (#22650) (Boshen) - 7b84314 semantic: Use direct byte access for numeric leading-zero check (#22642) (camc314) - 0345a31 semantic: Pre-size class elements hash map (#22618) (camc314) - 04d3065 minifier: Drop per-call buffers in try_fold_concat (#22596) (Dunqing) - 4f289f1 semantic: Resolve_references_for_current_scope without a temp Vec (#22599) (Dunqing) - e862c15 semantic: Avoid heap alloc for var hoist scope ids (#22603) (Dunqing) - 8ff8674 semantic: Early return if `excess` is `0` in `Stats::increase_by` (#22616) (camc314) - 7a4120e semantic: Pre-reserve unresolved_references using Stats::references (#22580) (Dunqing) Co-authored-by: Dunqing <[email protected]>

kylecannon requested review from Dunqing and overlookmotel as code owners May 8, 2026 21:46

kylecannon force-pushed the fix/decorator-metadata-readonly-array branch 2 times, most recently from 7bbfc9b to 7d1252a Compare May 8, 2026 22:33

camc314 assigned Dunqing May 9, 2026

camc314 added the A-transformer Area - Transformer / Transpiler label May 9, 2026

kylecannon force-pushed the fix/decorator-metadata-readonly-array branch from 7d1252a to 802f7c3 Compare May 11, 2026 16:33

kylecannon and others added 2 commits May 21, 2026 17:56

Dunqing force-pushed the fix/decorator-metadata-readonly-array branch from 802f7c3 to 485def7 Compare May 21, 2026 09:59

Dunqing merged commit 69a6ba6 into oxc-project:main May 21, 2026
36 checks passed

oxc-guard Bot mentioned this pull request May 26, 2026

release(crates): oxc v0.133.0 #22734

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(transformer/legacy-decorator): emit Array for ReadonlyArray<T> in decorator metadata#22265

fix(transformer/legacy-decorator): emit Array for ReadonlyArray<T> in decorator metadata#22265
Dunqing merged 2 commits into
oxc-project:mainfrom
kylecannon:fix/decorator-metadata-readonly-array

kylecannon commented May 8, 2026 •

edited

Loading

Uh oh!

codspeed-hq Bot commented May 21, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

kylecannon commented May 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

The bug

Fix

Scope

Test plan

Uh oh!

codspeed-hq Bot commented May 21, 2026

Merging this PR will not alter performance

Footnotes

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

kylecannon commented May 8, 2026 •

edited

Loading