class-transformer

class-transformer converts plain JavaScript objects (the kind you get back from JSON.parse, an HTTP body, or a database driver) into instances of your TypeScript classes, and back again, using decorators like @Type() and @Expose()/@Exclude() to describe the desired shape. Because the output is a real class instance rather than a plain object, methods, getters, and instanceof checks all work correctly on transformed data — something plain object literals can’t provide.

It’s a core building block of the TypeStack ecosystem, most commonly paired with class-validator and used heavily inside NestJS for request DTO transformation and response serialization, but it works standalone in any TypeScript codebase that needs to move data between wire format and typed class instances.

What You Get

• plainToInstance() / instanceToPlain() for converting between plain objects and class instances
• @Type() decorator for declaring nested class types so nested objects/arrays transform correctly
• @Expose() / @Exclude() decorators for controlling which properties appear in serialized output, including per-group and per-version control
• @Transform() for fully custom per-property transformation logic
• Circular-reference handling and depth limits for complex object graphs

Common Use Cases

• Converting incoming HTTP request bodies into typed DTO class instances in NestJS or Express applications
• Serializing class instances (e.g. entity models) into plain objects for JSON API responses, excluding internal-only fields
• Pairing with class-validator so class-validator’s decorators run against transformed class instances rather than plain objects
• Version- or group-scoped serialization, exposing different property sets to different API consumers

Under The Hood

Architecture - The library centers on MetadataStorage (src/MetadataStorage.ts), a singleton registry populated at decoration time by @Type/@Expose/@Exclude/@Transform, and TransformOperationExecutor (src/TransformOperationExecutor.ts, ~555 lines), which walks a source object recursively, consults the stored metadata for each property to decide whether to recurse into a nested @Type-annotated class, apply an exposure/exclusion rule, or run a custom @Transform function, and assembles the resulting plain object or class instance; ClassTransformer.ts exposes the public plainToInstance/instanceToPlain/instanceToInstance entry points over that executor. Tech Stack - Pure TypeScript with reflect-metadata-based decorator support (a peer dependency, not bundled), built to multiple output targets (CJS, ESM5, ES2015, UMD) via separate tsconfig.prod.*.json configs and a Rollup build for the UMD bundle, with zero runtime dependencies beyond reflect-metadata at the consumer’s discretion. Code Quality - test/functional/ contains an extensive suite of scenario tests (nested types, circular references, groups/versions, custom transformers) run via Jest with coverage reporting (codecov.yml), and the codebase is lint-enforced (eslint --max-warnings 0); however GitHub activity data shows the project in a low-commit-frequency, moderately maintained state relative to its very high download volume. API Design - The API surface is small and declarative — a handful of decorators plus two or three top-level functions — which keeps the learning curve low, though correctly wiring @Type() on every nested class property is a common source of confusing bugs for newcomers since it’s easy to forget on deeply nested structures.