Registry / serialization / reflect-metadata

reflect-metadata

JSON →
library0.2.2jsnpmunverified

reflect-metadata provides a polyfill for the Metadata Reflection API, a non-standardized API that gained traction through TypeScript's `--experimentalDecorators` feature. The package is currently at version 0.2.2 and sees infrequent but consistent maintenance, with the most recent patch release (0.2.2) addressing minor fixes. While the original TC39 proposal for Decorator Metadata is no longer being considered for standardization, this package continues to be essential for projects that rely on TypeScript's legacy decorator implementation, such as many Angular or older NestJS applications. Its primary differentiator is providing the `Reflect` global object and its methods (`Reflect.defineMetadata`, `Reflect.getMetadata`, etc.) to enable runtime reflection of metadata attached via decorators, which is not natively supported by standard JavaScript or modern decorator proposals. It offers both a full bundle with internal polyfills for `Map`, `Set`, and `WeakMap` for older runtimes, and a lighter `/lite` version without these internal polyfills.

npm install reflect-metadata
INSTALL
IMPORT
SIG · REFLECT-METADATA
R
reflect-metadata
serializationjavascriptv0.2.2
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

(Global side effect)
import "reflect-metadata";
import { Reflect } from 'reflect-metadata';
This import patches the global `Reflect` object. No symbols are directly exported or imported. This is required for TypeScript's `emitDecoratorMetadata` to function with `--experimentalDecorators`.
(Global side effect, lite bundle)
import "reflect-metadata/lite";
import { Reflect } from 'reflect-metadata/lite';
A lighter bundle that omits internal `Map`/`Set`/`WeakMap` polyfills. Use this only if your target environment has native support for these collections or you provide them externally.
(Global side effect, CommonJS)
require("reflect-metadata");
const Reflect = require('reflect-metadata');
CommonJS equivalent to the main ESM import, patches the global `Reflect` object. The `Reflect` object itself is not directly exported.

Demonstrates how to define and retrieve custom metadata using `Reflect.defineMetadata` and `Reflect.getMetadata` with class, method, and property decorators, along with an example of TypeScript's `design:paramtypes` metadata.

import "reflect-metadata"; // Must be at the top of your entry file. const classMetadataKey = Symbol("classMetadata"); const methodMetadataKey = Symbol("methodMetadata"); const propertyMetadataKey = Symbol("propertyMetadata"); // Custom decorator to define class-level metadata function ClassMetadata(value: string) { return function <T extends { new (...args: any[]): {} }>(constructor: T) { Reflect.defineMetadata(classMetadataKey, value, constructor); }; } // Custom decorator to define method-level metadata function MethodMetadata(value: string) { return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) { Reflect.defineMetadata(methodMetadataKey, value, target, propertyKey); }; } // Custom decorator to define property-level metadata function PropertyMetadata(value: string) { return function (target: any, propertyKey: string | symbol) { Reflect.defineMetadata(propertyMetadataKey, value, target, propertyKey); }; } @ClassMetadata("MyClassValue") class MyService { @PropertyMetadata("MyPropertyValue") public someProperty: string = "hello"; constructor() { // console.log("MyService instantiated."); } @MethodMetadata("MyMethodValue") public doSomething(arg: string): string { return `Doing something with ${arg}`; } } // --- Reflection to retrieve metadata --- // Get class metadata const classMeta = Reflect.getMetadata(classMetadataKey, MyService); console.log(`Class Metadata: ${classMeta}`); // Get property metadata (on the prototype for instance properties/methods) const propertyMeta = Reflect.getMetadata(propertyMetadataKey, MyService.prototype, "someProperty"); console.log(`Property Metadata (someProperty): ${propertyMeta}`); // Get method metadata const methodMeta = Reflect.getMetadata(methodMetadataKey, MyService.prototype, "doSomething"); console.log(`Method Metadata (doSomething): ${methodMeta}`); // Example of built-in TypeScript design-time type metadata (requires tsconfig.json: "emitDecoratorMetadata": true) // For a method parameter's type function logParameterType(target: any, propertyKey: string, parameterIndex: number) { const paramTypes = Reflect.getMetadata("design:paramtypes", target, propertyKey); if (paramTypes) { console.log(`Parameter types for method '${String(propertyKey)}':`, paramTypes.map(t => t.name)); } else { console.log(`No design:paramtypes metadata found for '${String(propertyKey)}'. Ensure emitDecoratorMetadata is true.`); } } class AnotherService { public greet(@logParameterType name: string, @logParameterType age: number): string { return `Hello ${name}, you are ${age} years old.` } } const anotherService = new AnotherService(); anotherService.greet("Alice", 30);
Debug
Known issues
breakingThe Metadata Reflection API, as implemented by `reflect-metadata` and utilized by TypeScript's `--experimentalDecorators`, is based on a TC39 proposal that has been abandoned in favor of a new decorators proposal. This means the API is not standard ECMAScript and may not be compatible with future native decorator implementations.
fix
Projects relying on this API should be aware of its non-standard status and consider migration to standard decorators if possible. This package will continue to support legacy usage.
affects: >=0.1.0
gotcha`reflect-metadata` functions as a global polyfill and does not export any named symbols. Attempting to import `Reflect` as a named or default export (e.g., `import { Reflect } from 'reflect-metadata';`) will result in `undefined` or a module resolution error.
fix
Always import `reflect-metadata` for its side effects to patch the global `Reflect` object: `import "reflect-metadata";` or `require("reflect-metadata");`. Ensure this import occurs before any code that uses decorators or `Reflect` methods.
affects: >=0.1.0
breakingVersion 0.1.11 contained a critical issue that prevented the library from loading or functioning correctly, making it unusable.
fix
Upgrade immediately to `0.1.12` or later.
affects: 0.1.11
gotchaThe main `reflect-metadata` bundle includes internal polyfills for `Map`, `Set`, and `WeakMap` for older JavaScript environments. The `/lite` export, however, does not include these polyfills, potentially leading to runtime errors in environments lacking native support for these collections.
fix
Use `import "reflect-metadata/lite";` only if you are targeting environments with native `Map`, `Set`, and `WeakMap` support, or if you are providing these polyfills through another means (e.g., `core-js`). Otherwise, use the standard `import "reflect-metadata";`.
affects: >=0.2.0
gotchaTo enable TypeScript to emit design-time type metadata (e.g., `design:type`, `design:paramtypes`, `design:returntype`), the `emitDecoratorMetadata` compiler option must be set to `true` in your `tsconfig.json`. Without this, `Reflect.getMetadata('design:...')` calls will return `undefined`.
fix
Add both `"experimentalDecorators": true` and `"emitDecoratorMetadata": true` to the `"compilerOptions"` section of your `tsconfig.json`.
affects: >=0.1.0
Errors
Common errors & fixes
ReferenceError: Reflect is not defined
The `reflect-metadata` polyfill has not been loaded or executed in the current JavaScript environment.
fix
Ensure `import "reflect-metadata";` (or `require("reflect-metadata");`) is at the very top of your application's entry point, or linked as a `<script>` tag for browser environments, *before* any code that uses decorators or `Reflect` methods.
TypeError: Reflect.getMetadata is not a function
The global `Reflect` object exists but does not contain the metadata methods, often due to an incomplete or incorrect polyfill setup, or calling it before the polyfill is active.
fix
Verify that `import "reflect-metadata";` is the *first* statement in your main application file. If using bundlers, ensure it's not tree-shaken away or executed out of order.
TypeError: Cannot read properties of undefined (reading 'constructor')
This often occurs when decorators are used in TypeScript/Babel but the `experimentalDecorators` compiler option is not enabled, leading to syntax errors or incorrect transpilation.
fix
In `tsconfig.json`, ensure `"experimentalDecorators": true` is set under `"compilerOptions"`.
Metadata for "design:paramtypes" is undefined
TypeScript's `emitDecoratorMetadata` compiler option is not enabled, preventing the compiler from generating the necessary design-time type metadata.
fix
In `tsconfig.json`, ensure `"emitDecoratorMetadata": true` is set under `"compilerOptions"`.
Upgrade
Version history
0.2.2latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
6 hits · last 30 days
node
6
Resources