Metattron

Attribute-style metadata helpers for TypeScript decorators. Declare an attribute once, use it as a decorator on classes, constructors, methods, properties, and parameters, then read it back through the generated for helpers without touching Reflect metadata.

Installation

npm install @aliaksandarpratashchyk/metattron

Usage

import {
  buildAttribute,
  FUNCTION,
  METHOD,
  METHOD_PARAMETER,
  PROPERTY,
  tag,
} from '@aliaksandarpratashchyk/metattron';

const role = buildAttribute<string>('role').ofKind(METHOD, PROPERTY);
const required = buildAttribute<boolean>('required').ofKind(METHOD_PARAMETER);

@role('service')
class UserService {
  @role('admin')
  activate(@required(true) userId: string) {}

  @role('config')
  static configPath = '/tmp/users';
}

role.
  for.
  method('activate').
  of(UserService).
  single; // 'admin'

role.
  for.
  ownProperty('configPath').
  of(UserService).
  single; // 'config'

required.
  for.
  methodParameterAt(0).
  ofMethod('activate').
  of(UserService).
  single; // true

tag.
  for.
  methodParameterAt(0).
  ofMethod('activate').
  of(UserService).
  singleOrUndefined; // string | symbol | undefined

Attribute kinds and readers

• FUNCTION: decorators for classes/standalone functions, read via attribute.for.function(Foo).
• FUNCTION_PARAMETER: constructor/standalone function parameters, read via attribute.for.parameterOfFunction(Foo).at(index).
• METHOD: instance/static methods, read via attribute.for.method(name).of(Foo) or attribute.for.ownMethod(name).of(Foo).
• METHOD_PARAMETER: method parameters, read via attribute.for.methodParameterAt(index).ofMethod(name).of(Foo) or attribute.for.methodParameterAt(index).ofOwnMethod(name).of(Foo).
• PROPERTY: instance/static properties, read via attribute.for.property(name).of(Foo) or attribute.for.ownProperty(name).of(Foo).

Every reader returns a MetadataCollection with .all, .single, and .singleOrUndefined helpers.

Built-in tag attribute

Use the bundled tag attribute when you just need to write a string or symbol identifier to any supported target without defining a custom attribute.

Scripts

• npm test — run the Jest suite, regenerate COVERAGE.md, and update coverage.svg.
• npm run build — bundle the library and regenerate API docs (docs/).
• npm run lint / npm run format — lint and format the codebase.

Publishing

GitHub Actions runs tests on pushes/PRs and publishes to npm when the version in package.json changes on main. Set NPM_TOKEN in repository secrets to enable publishing.