README.md

ts-reflection

Type inspection utilities for TypeScript

ts-reflection allows you to access information about your types in runtime - e.g. get properties of a type or possible values of a union. It is compatible with rollup, webpack, and ttypescript projects and works nicely with jest or ts-node

Motivation | API | Installation | Acknowledgement

Wait what?

As they say an example is worth a thousand API docs so why not start with one.

import { propertiesOf } from 'ts-reflection';

interface MyInterface {
  name: string;
  hobbies: string[];
}

// You can now use propertiesOf utility to get properties of a type
const properties = propertiesOf<MyInterface>(); // ['name', 'hobbies']

Let's do another one!

import { valuesOf } from 'ts-reflection';

type ButtonType = 'primary' | 'secondary' | 'link';

// You can use valuesOf utility to get all the possible union type values
const buttonTypes = valuesOf<ButtonType>(); // ['primary', 'secondary', 'link']

Motivation

I can't count the number of times I needed to type all the possible values of a union type to create e.g. a dropdown with all the button types:

type ButtonType = 'primary' | 'secondary' | 'link';

const buttonTypes: ButtonType[] = ['primary', 'secondary', 'link'];

I was always aware of fragility of such solution and the fact you need to update it by hand every time ButtonType changes. Now I can write just

const buttonTypes: ButtonType[] = valuesOf<ButtonType>;

The same goes for a list of type properties - typing those lists of keyof type values:

interface MyInterface {
  property: number;
  anotherProperty: string;
}

type Key = keyof MyInterface;
const keys: Key[] = ['property', 'anotherProperty']

Which now becomes

const keys: Key[] = propertiesOf<MyInterface>();

API

You can find comprehensive API documentation in the API docs.

ts-reflection exports two functions: valuesOf (for accessing values of union types) and propertiesOf (for accessing properties of types).

valuesOf

valuesOf is a function that returns all the possible literal values of union types:

import { valuesOf } from 'ts-reflection';

type UnionType = 'string value' | 1 | true | Symbol.toStringTag;

// You can use valuesOf utility to get all the possible union type values
const unionTypeValues = valuesOf<UnionType>(); // ['string value', 1, true, Symbol.toStringTag]

Please read the full API docs for more information about valuesOf.

propertiesOf

propertiesOf is a function that returns property names of types:

import { propertiesOf } from 'ts-reflection';

interface MyInterface {
  name: string;
  displayName?: string;
  readonly hobbies: string[];
}

// When called with no arguments, propertiesOf() returns all public properties of a type
const properties = propertiesOf<MyInterface>(); // ['name', 'displayName', 'hobbies']

// You can also call it with "queries" to be more specific about what properties you want to get
const readonlyProperties = propertiesOf<MyInterface>({ readonly: true }); // ['hobbies']
const mutableProperties = propertiesOf<MyInterface>({ readonly: false }); // ['name', 'displayName']
const optionalProperties = propertiesOf<MyInterface>({ optional: true }); // ['displayName']
const requiredProperties = propertiesOf<MyInterface>({ optional: false }); // ['name', 'hobbies']

Please read the full API docs for more information about propertiesOf and the queries it supports.

Installation

You can find comprehensive installation instructions in the installation docs.

Acknowledgement

This idea was inspired by ts-transformer-keys NPM module. The E2E testing infrastructure that ensures compatibility with all minor TypeScript versions is based on my ts-type-checked project.