reflect-metadata

reflect-metadata is a lightweight, zero-dependency polyfill that adds a Metadata Reflection API to the global Reflect object, letting you attach and read arbitrary metadata on classes and their members. It is the runtime that makes TypeScript’s legacy experimentalDecorators and emitDecoratorMetadata options useful, and it underpins dependency-injection and reflection features in frameworks like Angular, NestJS, TypeORM, and InversifyJS.

The library exposes a small, consistent set of imperative methods (defineMetadata, getMetadata, hasMetadata, and friends) alongside a @Reflect.metadata decorator, works across NodeJS, browsers, and bundlers, and ships CommonJS, ESM, lite, and no-conflict builds to fit different runtime constraints.

What You Get

• A global Reflect polyfill exposing defineMetadata, getMetadata, hasMetadata, getMetadataKeys, deleteMetadata, and their own-property variants.
• A @Reflect.metadata(key, value) decorator for declaratively attaching metadata to classes and members.
• Multiple builds — full (with internal Map/Set/WeakMap polyfills), lite, and no-conflict — plus CommonJS, ESM, and browser <script> distributions.
• First-class TypeScript typings and support for emitDecoratorMetadata, enabling auto-generated design:type, design:paramtypes, and design:returntype metadata.

Common Use Cases

• Powering dependency-injection containers that resolve constructor parameter types from emitted metadata.
• Building runtime type assertions, validation, and serialization from decorator-attached annotations.
• Supporting ORM and framework decorators (entities, routes, DTOs) that need to read type metadata reflectively.

Under The Hood

Architecture - The library is authored as a single TypeScript namespace Reflect in Reflect.ts (~93KB) that installs itself onto the global Reflect object, or creates one on ES5 runtimes. Metadata is stored in a nested WeakMap keyed first by target object, then by property key, then by metadata key, using internal Map/Set/WeakMap polyfills for legacy environments. Parallel ReflectLite.ts and ReflectNoConflict.ts sources produce the lite (no internal polyfills) and no-conflict builds, exposed through package.json exports as ., ./lite, and ./no-conflict.

Tech Stack - Written entirely in TypeScript with zero runtime dependencies, compiled via a gulp build pipeline (gulpfile.js, tsconfig-release.json) that emits CommonJS .js bundles plus .d.ts typings (index.d.ts, standalone.d.ts, no-conflict.d.ts). The ECMAScript specification itself is authored in spec.html with ecmarkup. Tests run on mocha with chai assertions.

Code Quality - The test/ directory holds 28 focused suites, one per public API method (reflect-definemetadata.ts, reflect-getmetadata.ts, reflect-decorate.ts, and so on), giving thorough behavioral coverage of the metadata operations. The source is extensively documented with JSDoc examples on each exported function, and public surfaces are fully typed.

API Design - The public API is small, consistent, and ergonomic: paired hasMetadata/hasOwnMetadata, getMetadata/getOwnMetadata, and prototype-chain vs own-key variants follow a predictable naming scheme. Metadata key and value precede the target argument so the optional propertyKey sits last and the calls curry cleanly with Function#bind. Getting started requires only a single import "reflect-metadata" at the entry point, with rich typings surfacing documentation directly in the editor.