@qiwi/decorator-utils

decorator-utils

Universal decorator factories made from scratch

Install

yarn add @qiwi/decorator-utils

Notes

• There's no right way to support both decorator types: with @parentheses() and @plain. Holy War thread: wycats/javascript-decorators/issues/23
• TypeScript 5 decorators: announcing-typescript-5-0, TS/issues/52435, nestjs/issues/10959
• TC39 stage-3 proposal decorators

Usage

Method

import {constructDecorator} from '@qiwi/decorator-utils'

const decorator = constructDecorator((targetType, target, param) => {
  if (targetType === METHOD) {
    return value => param || 'qux'
  }
})

class Foo {
  @decorator()
  foo () { return 'bar' }
  @decorator('BAZ')
  baz () { return 'baz' }
}

Class

const decorator = constructDecorator((targetType, target) => {
  if (targetType === CLASS) {
    return class Bar extends target {
      constructor (name, age) {
        super(name)
        this.age = age
      }
    }
  }
})

@decorator()
class Foo {
  constructor (name) {
    this.name = name
  }
  foo () { return 'bar' }
}

Field & Param

import {createDecorator, FIELD, PARAM} from '@qiwi/decorator-utils'

const meta: any = {}
const decorator = constructDecorator(({
  propName,
  paramIndex,
  targetType,
  target,
  args: [param]
}: IDecoratorHandlerContext) => {
  if (targetType === PARAM) {
    if (propName && typeof paramIndex === 'number') {
      meta[propName] = meta[propName] || {}
      meta[propName][paramIndex] = target
    }
  }

  if (targetType === FIELD) {
    if (propName) {
      meta[propName] = param
    }
  }
})

class Foo {
  @decorator('arg')
  foo = 'bar'

  bar(one: any, @decorator() two: any) {
    return 'bar'
  }
}

/**
    Now `meta` is smth like:
    {
      foo: 'arg',
      bar: {
        1: Foo.prototype.bar,
      },
    }
*/

You may also apply the decorator to the class, but decorate its methods:

const decorator = constructDecorator((targetType, target) => {
  if (targetType === METHOD) {
    return () => {
      return target().toUpperCase()
    }
  }
})

@decorator()
class Foo {
  foo () { return 'bar' }
  baz () { return 'baz' }
}

Context

constructDecorator factory provides the handler access to the decorator context. This data describes the specifics of the decorated target, decorator arguments and so on.

type IDecoratorHandlerContext = {
  args: IDecoratorArgs
  kind: ITargetType | null        // targetType alias
  targetType: ITargetType | null
  target: ITarget
  proto: IProto
  ctor: Function
  name?: IPropName                // propName alias
  propName?: IPropName
  paramIndex?: IParamIndex
  descriptor?: IDescriptor
}

Options

You may set additional options to apply some decorator asserts: allowed target types, repeatable or not.

const plus = constructDecorator(
  ({ targetType, target, args: [param] }) => {
    return (value: number) => target(value) + param
  },
  {
    allowedTypes: METHOD, // string | string[]
    repeatable: true,
  },
)

class Foo {
  @plus(2)
  @plus(1)
  bar(v: number) {
    return v
  }
}

reflect-metadata

If the global Reflect provides getMetadataKeys, getMetadata and defineMetadata methods, they will be used to attach corresponding data to the decorated targets. To enable, just add reflect-metadata to your dependencies and load it.

import 'reflect-metadata'
import {constructDecorator} from '@qiwi/decorator-utils'
// ...

Refs

• JS decorators by Axel Rauschmayer
• "aspect" syntax for JS
• Exploring es7 decorators by Addy Osmany
• core-decorators
• lodash-decorators
• decorator-utils
• Netanel Basal's decorator tips

License

MIT