reflect-metadata: a withdrawn ECMAScript proposal kept alive as a polyfill for TypeScript's legacy decorators
Prototype for a Metadata Reflection API for ECMAScript
At a glance
- What is it?
- microsoft/reflect-metadata polyfills a Metadata Reflection API on the global Reflect object. The TC39 route it was written for has been dropped in favour of standard decorators, so the package now exists to serve code that still uses TypeScript's experimentalDecorators option.
- Who is it for?
- Install reflect-metadata if your project depends on TypeScript's experimentalDecorators and a framework that reads design-time metadata. For new code on standard decorators, the README says the proposed API is no longer being considered for standardization, so look to Decorator Metadata instead.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 83 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- microsoft/reflect-metadata3,359 ★ · -2
| Repository | 2026-09-24 | 2026-11-15 |
|---|---|---|
| microsoft/reflect-metadata | 3.4k | 3.4k |
-2 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The standardization path ended when decorators reached Stage 3
The first thing in the README is a notice. Both Decorators and Decorator Metadata have reached Stage 3 within TC39, and so the API proposed in this repository is no longer being considered for standardization.
The package is still supported, though only for a specific audience: projects that use TypeScript's legacy --experimentalDecorators option and cannot migrate to standard decorators. That is a narrow promise. It means you should not choose reflect-metadata as the foundation of a new design, since the language committee has moved on to a different mechanism.
The consequence for an existing codebase is that the dependency is stable but terminal. It will keep working for the legacy decorator workflow, but the long-term direction is away from it. Plan a migration to standard decorators and Decorator Metadata when your tooling allows, rather than assuming this API will one day appear natively.
Two entry points differ in whether they carry their own Map, Set and WeakMap
Installation is one command:
npm install reflect-metadataThe main entry is `import "reflect-metadata";`, which modifies the global Reflect object, or defines one in ES5 runtimes, supports ESM and CommonJS, and contains internal polyfills for Map, Set and WeakMap for older runtimes. The second entry is `import "reflect-metadata/lite";`, which also modifies the global Reflect, but requires runtime support for "exports" in package.json and does not include the internal polyfills.
CommonJS has the same pair with require. For a browser script tag there is Reflect.js with polyfills and ReflectLite.js without, and standalone.d.ts can be referenced to make types available in an editor.
The tradeoff is bundle size against reach. Lite is for modern runtimes, and on an old runtime without those collections it will not have a fallback.
Importing it changes the global Reflect object
Every documented entry point is described as modifying the global Reflect object, or defining one when the runtime is ES5. There is no variant in the usage section that avoids touching the global.
That is a side effect with real consequences. Two copies of the package in one process both patch the same global, and code that checks for Reflect.getMetadata at import time depends on the order of imports. A decorator that reads metadata before the import has run will find nothing.
The package.json also exposes a ./no-conflict path pointing at ReflectNoConflict.js with its own no-conflict.d.ts, and the repository contains ReflectNoConflict.ts. The usage section does not explain that variant, so read the docs folder or the source before choosing it. Whichever you use, import the package once, at the very start of your application.
Key and value come first so the optional property key can sit last
The API surface is small. Reflect.defineMetadata(metadataKey, metadataValue, target) and the form with a propertyKey add metadata. Reflect.hasMetadata checks the prototype chain of an object or property, while Reflect.hasOwnMetadata checks only own metadata. Reflect.getMetadata(metadataKey, obj, "method") reads it back, and the decorator form is @Reflect.metadata(metadataKey, metadataValue).
The parameter order looks backwards. The notes explain it: the propertyKey is the only optional parameter, so placing metadata key and value before the target keeps it last. It also makes methods easier to curry with Function#bind and reduces the footprint of a decorator that can target either a class or a property.
The cost is a habit one. If you expect target first, as in many reflection APIs, you will pass arguments in the wrong order and get silent misses rather than an error.
Metadata hangs off an internal slot, with undefined as the class-level key
The semantics section describes a new [[Metadata]] internal property on Object. It holds a Map from property keys, or undefined, to Maps of metadata keys to metadata values. Internal methods such as [[DefineOwnMetadata]], [[GetOwnMetadata]] and [[HasOwnMetadata]] can be overridden by a Proxy, which is how the proposal planned to support extra traps.
Where things are stored follows from that. Metadata on class declaration C goes in C.[[Metadata]] with undefined as the key. Metadata on static members goes in the same place under the property key. Metadata on instance members goes in C.prototype.[[Metadata]] under the property key.
The consequence is that you must pass the right target. Reading instance member metadata from the constructor, or class metadata from the prototype, returns nothing, and the polyfill cannot tell you that you asked in the wrong place.
The alternative is plain properties, and the README admits it is verbose
The Alternatives section considers skipping a separate API and using properties. Its own verdict is that the obvious downside is a lot of code. The example decorator ParamTypes writes types to a symbol key Symbol.for("design:paramtypes") on the target, and for property keys it creates a design:properties symbol object, guarded by Object.prototype.hasOwnProperty.call checks.
The goals list explains why the project preferred an API: use cases such as dependency injection, runtime type assertions, reflection and testing all want metadata added to a class consistently, tools need a shared way to reason over it, and metadata-producing decorators should compose with mutating ones.
If you want no dependency, the manual symbol approach works, but each library then invents its own convention. That is the very problem a shared Reflect API was meant to remove.
Version 0.2.1 is the latest release, while package.json says 0.2.2
Three releases are listed: v0.2.0-pre.0 on 2023-12-13, reflect-metadata 0.2.0 on the same day and v0.2.1 on 2023-12-14. The package.json in the repository reads version 0.2.2, so the main branch is ahead of the newest listed release. The last push was on 2026-08-24 and the repository is not archived. It is licensed Apache-2.0.
The build tooling is dated. Dev dependencies include gulp ^3.9.1, mocha ^3.2.0, typescript ^2.1.4, chai ^3.5.0 and @types/node ^10.17.60, with scripts build, test and start all running gulp. There are no runtime dependencies. Building from source on a modern Node may need those old versions, though consuming the package from npm does not.
Pin the version you tested, and check the changelog for 0.2.2 before relying on anything beyond 0.2.1.
Editorial conclusion
Install reflect-metadata if your project depends on TypeScript's experimentalDecorators and a framework that reads design-time metadata. For new code on standard decorators, the README says the proposed API is no longer being considered for standardization, so look to Decorator Metadata instead. Before upgrading, note that package.json says 0.2.2 while the newest listed release is v0.2.1, and check which entry point your runtime supports.
Frequently asked questions
What is reflect-metadata?
It is a polyfill for the Metadata Reflection API that adds Reflect.defineMetadata, getMetadata and the @Reflect.metadata decorator, kept for TypeScript's legacy experimentalDecorators projects.
What does reflect metadata do?
It lets decorators and code attach metadata keys and values to classes and properties, then read them back with calls such as Reflect.getMetadata(metadataKey, obj, "method").
What is an alternative to reflect metadata?
The README lists plain properties as an alternative but notes it takes a lot of code. Standard decorators with Decorator Metadata reached Stage 3 and replace the proposal.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/microsoft-reflect-metadata)Star history chart for your README
[](https://hysenlabs.com/projects/microsoft-reflect-metadata)Was this useful?