@itrocks/reflect

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.