reflect

Runtime introspection of TypeScript classes and their properties, including property types read from TypeScript declaration .d.ts files.

Installation

To use the Reflect API in your project, install the package:

npm i @itrocks/reflect

Basic Usage

The product.ts script:

export class Product
{
	name:     string
	price:    number
	basedOn?: Product
	history:  Product[] = []

	constructor(name: string, price: number)
	{
		this.name  = name
		this.price = price
	}

}

The index.ts main script:

import '@itrocks/class-file/automation'
import { ReflectClass, ReflectProperty } from '@irocks/reflect'
import { Product } from './product'

const product      = new Product('Widget', 10)
const productClass = new ReflectClass(product)

console.log(productClass.name)  // Product
console.log(productClass.propertyNames)  // ['basedOn', 'history', 'name', 'price']
console.log(productClass.propertyTypes)  // { name: String, price: Number, basedOn: class Product, history: { containerType: Array, elementType: class Product } }

const priceProperty = new ReflectProperty(productClass, 'price')

console.log(priceProperty.type)  // Number
console.log(priceProperty.value)  // 10

References

In this documentation, we will refer to the following:

Generics references:

• T extends object: Enables precise type control through reflection class methods and properties. Defined by the constructor parameter object.

Types references:

• PropertyType: Represents any single property type, either primitive or complex.
• PropertyTypes: A mapping of property names to their types.
• Type<T>: A class for objects of type T.
• KeyOf<T>: The string property names in T.

ReflectClass

The ReflectClass class provides utilities for reflecting on a class or an object at runtime.

Constructor

constructor(object: T | Type<T>)

Parameters:

• object: An instance of the class or the class type itself.

Properties

• name: string. The name of the class.

• object: T | undefined. The object instance, or undefined if a class type was provided.

• type: Type<T>. The type information of the class.

• parent: ReflectClass | null. The parent class, or null if no parent exists.

• properties: Record<KeyOf<T>, ReflectProperty<T>>. A map of property names (KeyOf<T>) to ReflectProperty instances.

• propertyNames: SortedArray<KeyOf<T>>. A sorted array of property names.

• propertyTypes: PropertyTypes<T>. A map of property names and their corresponding types.

ReflectProperty

The ReflectProperty class provides utilities for reflecting on a class or object property at runtime.

Constructor

constructor(object: T | ReflectClass<T> | Type<T>, name: KeyOf<T>)

Parameters:

• object: An instance, ReflectClass, or the class type.
• name: The name of the property.

Properties

• name: KeyOf<T>. The name of the property (KeyOf<T>).

• class: ReflectClass<T>. The ReflectClass instance associated with the property.

• collectionType: CollectionType<T>. Similar to type, explicitly returning a CollectionType (throws an error if not a collection).

• object: T | undefined. The object instance associated with the property, or undefined if no object is provided.

• type: PropertyType<T> The type of the property.

• value: any The current value of the property, or undefined if no object is provided.