@itrocks/decorator v0.0.12

decorator

A library that simplifies the declaration, persistence, and retrieval of decorator values.

It provides a convenient and consistent way to define decorators on classes and properties, persist their associated metadata values, and retrieve these values later in your application code. It also allows defining decorators with callbacks for dynamic metadata generation.

This library streamlines the process of:

• Defining class-level and property-level decorators that store metadata,
• Retrieving stored metadata values at runtime with default fallbacks,
• Facilitating callback-driven decorators that compute metadata values dynamically.

Installation and Requirements

npm install @itrocks/decorator

To ensure proper behavior, configure your tsconfig.json to enable experimental decorators and metadata emission:

{
	"compilerOptions": {
		"experimentalDecorators": true,
		"emitDecoratorMetadata": true
	}
}

This configuration ensures the decorators and their associated metadata are properly emitted and accessible at runtime.

Getting Started

1. Import the Tools: For class decorators:

   import { decorate, decorateCallback, decoratorOf, decoratorOfCallback } from '@itrocks/reflect-decorator/class'

   For property decorators:

   import { decorate, decorateCallback, decoratorOf, decoratorOfCallback } from '@itrocks/reflect-decorator/property'

2. Define Your Decorator:\ Use decorate or decorateCallback to define a new decorator that sets metadata on a class or property.

3. Apply Your Decorator:\ Attach your decorator to the relevant class or property.

4. Retrieve Decorator values:\ Use decoratorOf or decoratorOfCallback to retrieve access stored values from previously defined decorators. You can also provide a default fallback value or a callback if no data is present.

Example use case

In these example, type helpers from the dependency @itrocks/class-type are used. You can use compatible types from other sources if preferred, but these helpers are provided for convenience.

Class-level example

Define a persistent decorator and its retrieval function:

import { decorate, decoratorOf } from '@itrocks/decorator/class'
import { ObjectOrType }          from '@itrocks/class-type'

const ACTIONS = Symbol('actions')

export function Actions(value: string[] = []) {
	return decorate(ACTIONS, value)
}

export function actionsOf(target: ObjectOrType) {
	return decoratorOf(target, ACTIONS, ['create', 'update', 'delete'])
}

Use your decorators in your classes, or not:

class FullService {}

@Actions(['create', 'update'])
class RestrictedService {}

Retrieve decorator values from anywhere in your code:

console.log(actionsOf(FullService))         // Default: ['create', 'update', 'delete']
console.log(actionsOf(RestrictedService))   // ['create', 'update']

It also works with objects:

console.log(actionsOf(new RestrictedService))   // ['create', 'update']

Property-level example

Define a persistent decorator and its retrieval function:

import { decorate, decoratorOf } from '@itrocks/decorator/property'
import { KeyOf, ObjectOrType }   from '@itrocks/class-type'

const COMPONENT = Symbol('component')

function Component<T extends object>(value = true) {
	return decorate<T>(COMPONENT, value)
}

function componentOf<T extends object>(target: ObjectOrType<T>, property: KeyOf<T>) {
	return decoratorOf(target, property, COMPONENT, false)
}

Use your decorators in your classes, or not:

class Document 
{
	code: number

	@Component()
	components: Object[]
}

Retrieve decorator values from anywhere in your code:

console.log(componentOf(Document, 'code'))         // false
console.log(componentOf(Document, 'components'))   // true

It also works with objects:

console.log(componentOf(new Document, 'components'))   // true

Tips and tricks

Experimental decorators allow you to dynamically apply them after your class or property has been declared. In the examples above, decorators could have been added dynamically while calling:

// Class decorator
Actions(['create', 'update'])(RestrictedService)

// Property decorator
Component<Document>()(Document.prototype, 'components')

Class Decorator API

Import Path: @itrocks/decorator/class

Types

These TypeScript type shortcuts are used to simplify coding and improve readability:

type DecorateCaller<T extends object> = (target: Type<T>) => void

type DecoratorCallback<T extends object, V = any> = (target: Type<T>) => V

type DecoratorOfType<V = any> = (target: ObjectOrType, name: Symbol, undefinedValue: V) => V

The API and the documentation frequently refer to these types.

decorate

function decorate<T extends object>(name: Symbol, value: any): DecorateCaller<T>

Creates a class decorator that persists a value associated with the class.

Parameters:

• name: Symbol – Unique key for storing the decorator data.
• value: any – The value to associate with the class decorator.

Returns:\ A decorator function that can be applied to a class (target: Type<T>) => void.

decorateCallback

function decorateCallback<T extends object>(name: Symbol, callback: DecoratorCallback<T>): DecorateCaller<T>

Similar to decorate, but computes the value dynamically at decoration time using a callback.

Parameters:

• name: Symbol – Unique key for storing the decorator data.
• callback: (target: Type<T>) => any – A function returning the value to store.

Returns:\ A decorator function that can be applied to a class: (target: Type<T>) => void.

Example: Automatically decorates a class using its class name:

import { decorateCallback } from '@itrocks/decorator/class'

const INFO = Symbol('info')

function AutoInfo() {
  return decorateCallback(INFO, target => `Class name: ${target.name}`)
}

@AutoInfo()
class Example {}

decoratorOf

function decoratorOf<V>(target: ObjectOrType, name: Symbol, undefinedValue: V): V

Retrieves the decorator value from a class, returning a default value if none is found.

Parameters:

• target: ObjectOrType – The class or an instance of the class.
• name: Symbol – The key of the decorator to retrieve.
• undefinedValue: V – A fallback value to return if no value is stored for this decorator.

Returns:\ The stored decorator value or the fallback value.

Example:

Defines a retrieval function for the previously defined AutoInfo decorator (see example above):

import { decoratorOf } from '@itrocks/decorator/class'

function autoInfoOf(target: ObjectOrType) {
	return decoratorOf(target, INFO, 'no info')
}

If no decorator is found, 'no info' is returned.

decoratorOfCallback

function decoratorOfCallback<T extends object, V>(target: ObjectOrType<T>, name: Symbol, undefinedCallback?: DecoratorCallback<T, V>): V

Retrieves the decorator value from a class. If no value is defined, computes one using a fallback callback function.

Parameters:

• target: ObjectOrType<T> - The class or an instance of the class.
• name: Symbol - The key of the decorator to retrieve.
• undefinedCallback?: (target: Type<T>) => V - A function computing a fallback value if none is found.

Returns:\ The stored value or the computed value from the callback.

Example:

Defines a retrieval function for the previously defined AutoInfo decorator (see example above):

import { decoratorOf } from '@itrocks/decorator/class'

function autoInfoOf<T extends object>(target: ObjectOrType) {
	return decoratorOfCallback<T, string>(target, INFO, target => `Class name: ${target.name}`)
}

If no decorator is found, the fallback dynamically computes 'Class name:' followed by the class name.

ownDecoratorOf

function ownDecoratorOf<V>(target: ObjectOrType, name: Symbol, undefinedValue: V): V

Similar to decoratorOf, without traversing the prototype chain.

ownDecoratorOfCallback

function ownDecoratorOfCallback<V>(target: ObjectOrType, name: Symbol, undefinedValue: V): V

Similar to decoratorOfCallback, without traversing the prototype chain.

Property Decorator API

Import Path: @itrocks/decorator/property

Types

These TypeScript type shortcuts are used to simplify coding and improve readability:

type DecorateCaller<T extends object> = (target: T, property: KeyOf<T>) => void

type DecoratorCallback<T extends object, V = any> = (target: T, property: KeyOf<T>) => V

The API and the documentation frequently refer to these types.

decorate

function decorate<T extends object>(name: Symbol, value: any): DecorateCaller<T>

Defines a decorator for class properties, assigning a fixed value to the property’s metadata.

Parameters:

• name: Symbol - Unique key used for storing the decorator data.
• value: any - The value to associate with the property.

Returns:\ A decorator function to be applied to a property.

decorateCallback

function decorateCallback<T extends object>(name: Symbol, callback: DecoratorCallback<T>): DecorateCaller<T>

Similar to decorate, but computes the value dynamically at decoration time using a callback.

Parameters:

• name: Symbol - Unique key used for storing the decorator data.
• callback: (target: T, property: KeyOf<T>) => any - A function returning the value to store.

Returns:\ A decorator function to be applied on a property: (target: T, property: KeyOf<T>) => void.

Example: Automatically computes display names for properties:

import { decorateCallback } from '@itrocks/decorator/property'
import { toDisplay }        from '@itrocks/rename'

const DISPLAY = Symbol('display')

function Display<T extends object>(name = '') {
	return decorateCallback<T>(DISPLAY, (target, property) => name.length ? name : toDisplay(property))
}

class Example {
	@Display('forced display')
	aPropertyName = ''
	@Display() // automatic calculated display
	anotherPropertyName = ''
}

decoratorOf

function decoratorOf<V, T extends object>(target: ObjectOrType<T>, property: KeyOf<T>, name: Symbol, undefinedValue?: V): V

Retrieves the decorator value from a class property, returning a default value if none is found.

Parameters:

• target: ObjectOrType<T> – The class or an instance of the class.
• property: KeyOf<T> – The name of the class property to retrieve decorator value from.
• name: Symbol – The key of the decorator to retrieve.
• undefinedValue: V – A fallback value to return if no value is stored for this decorator.

Returns:\ The stored decorator value or the fallback value.

Example:

Defines a retrieval function for the previously defined Display decorator (see example above):

import { decoratorOf } from '@itrocks/decorator/property'

function displayOf<T extends object>(target: ObjectOrType<T>, property: KeyOf<T>)
{
	return decoratorOf(target, property, DISPLAY)
}

If no decorator is found, this will return undefined.

decoratorOfCallback

function decoratorOfCallback<V, T extends object>(target: ObjectOrType<T>, property: KeyOf<T>, name: Symbol, undefinedCallback: DecoratorCallback<T, V>): V

Retrieves the decorator value from a class property. If no value is defined, computes one using a fallback callback function.

Parameters:

• target: ObjectOrType<T> – The class or an instance of the class.
• property: KeyOf<T> – The name of the property to retrieve decorator value from.
• name: Symbol – The key of the decorator to retrieve.
• undefinedCallback?: (target: T, property: KeyOf<T>) => V – A function computing a fallback value if no value is found.

Returns:\ The stored value or computed value from the callback.

Example:

Defines a retrieval function for the previously defined Display decorator (see example above):

import { decoratorOfCallback } from '@itrocks/decorator/property'
import { toDisplay }           from '@itrocks/rename'

function displayOf<T extends object>(target: ObjectOrType<T>, property: KeyOf<T>)
{
	return decoratorOfCallback<string, T>(target, property, DISPLAY, (_, property) => toDisplay(property))
}

If no decorator is found, the fallback dynamically computes a display name based on the property name.