DEV Community

Cover image for Improving TypeScript Metadata Type Safety with ts-reflector
e22m4u
e22m4u

Posted on • Edited on

Improving TypeScript Metadata Type Safety with ts-reflector

TypeScript and decorators have become an integral part of modern development. Many frameworks like NestJS, TypeORM, and others actively use metadata through reflect-metadata. However, this approach has a significant drawback - lack of typing.

The Problem

When working directly with reflect-metadata, TypeScript cannot verify type correctness. This can lead to runtime errors.

1. No type validation during storage:

// We can store anything - TypeScript won't object
Reflect.defineMetadata('userAge', 'not a number!', Target);
Reflect.defineMetadata('userInfo', null, Target);
Reflect.defineMetadata('config', undefined, Target);
Enter fullscreen mode Exit fullscreen mode

2. Loss of type information when retrieving data:

// We get 'any', losing all TypeScript benefits
const age = Reflect.getMetadata('userAge', Target);
age.toFixed(2); // No IDE hints or type checking
Enter fullscreen mode Exit fullscreen mode

3. No protection against typos in string keys:

// Key typo - will only be discovered at runtime
Reflect.defineMetadata('userInfo', {name: 'John'}, Target);
const data = Reflect.getMetadata('userXnfo', Target); // Typo!
Enter fullscreen mode Exit fullscreen mode

4. Refactoring challenges:

// When changing data structure, you'll have to manually
// find all usage locations
type UserInfo = {
  name: string;
  age: number;
  // Added new field
  email: string; // IDE won't suggest where structure needs updating
};
Enter fullscreen mode Exit fullscreen mode

These issues are particularly critical in large projects where metadata is heavily used and maintained by multiple developers.

The Solution

The @e22m4u/ts-reflector library provides an elegant solution through the MetadataKey<T> class, which adds strict typing for metadata. This allows TypeScript to verify data correctness at compile time and provides complete type information during retrieval. Instead of working with unsafe string keys and any-typed values, we get full typing and IDE support.

When attempting to store incorrect data, TypeScript will immediately flag the error:

import {Reflector, MetadataKey} from '@e22m4u/ts-reflector';

// Define metadata structure
type UserInfo = {
  name: string;
  age: number;
};

// Create typed key
const USER_INFO = new MetadataKey<UserInfo>();

// TypeScript will highlight the error before compilation
Reflector.defineMetadata(USER_INFO, {
  name: 123,   // Error: number cannot be assigned to string
  age: "30"    // Error: string cannot be assigned to number
}, Target);
Enter fullscreen mode Exit fullscreen mode

When retrieving metadata, we no longer work with the any type - TypeScript knows the exact data structure:

const info = Reflector.getMetadata(USER_INFO, Target); // type: UserInfo

// IDE will provide all string methods
console.log(info.name.toLowerCase());
Enter fullscreen mode Exit fullscreen mode

This is particularly valuable during refactoring - when changing the UserInfo type, TypeScript will immediately show all places where code needs to be updated. And the IDE hint system makes development more convenient and safer.

Additionally, @e22m4u/ts-reflector is fully compatible with existing reflect-metadata projects, allowing for gradual implementation while improving type safety step by step.

Billboard image

The Next Generation Developer Platform

Coherence is the first Platform-as-a-Service you can control. Unlike "black-box" platforms that are opinionated about the infra you can deploy, Coherence is powered by CNC, the open-source IaC framework, which offers limitless customization.

Learn more

Top comments (0)

Heroku

This site is powered by Heroku

Heroku was created by developers, for developers. Get started today and find out why Heroku has been the platform of choice for brands like DEV for over a decade.

Sign Up

👋 Kindness is contagious

Immerse yourself in a wealth of knowledge with this piece, supported by the inclusive DEV Community—every developer, no matter where they are in their journey, is invited to contribute to our collective wisdom.

A simple “thank you” goes a long way—express your gratitude below in the comments!

Gathering insights enriches our journey on DEV and fortifies our community ties. Did you find this article valuable? Taking a moment to thank the author can have a significant impact.

Okay