npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@itrocks/decorator

v0.0.4

Published

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

Downloads

275

Readme

npm version npm downloads GitHub issues discord

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'
  1. Define Your Decorator:
    Use decorate or decorateCallback to define a new decorator that sets metadata on a class or property.

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

  3. 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.

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.