API
@agape/metadata

MetadataDescriptor Class

A descriptor that holds metadata information for classes, properties, methods, and parameters.

API

class MetadataDescriptor {  constructor(name?: string);  description?: string;  example?: any;  label?: string;  labelPlural?: string;  name?: string;  noun?: string;  nounPlural?: string;  sensitive?: boolean;  token?: string;  tokenPlural?: string;  static for(target: object | Class, property?: string, index?: number): MetadataDescriptor;  static get(target: object | Class, property?: string, index?: number): undefined | MetadataDescriptor;}

constructor

MetadataDescriptor

Creates a new MetadataDescriptor instance.

@paramname:  string
Optional name for the decorated element. If not provided, the name can be set later or will be automatically determined when using the `for()` method.
@returnsMetadataDescriptor

description

string

A detailed description of the decorated element. Descriptions provide additional context and information about the purpose and usage of the decorated element.

example

any

An example value for the decorated element. Examples can be used in documentation, validation messages, or as default values in user interfaces.

label

string

A human-readable label for the decorated element. Labels are typically used in user interfaces such as form inputs, tables, and auto-generated documentation.

labelPlural

string

The plural form of the label. Used when displaying multiple instances of the decorated element, such as in table headers or list titles.

name

string

The name of the decorated element. For classes, this is typically the class name. For properties, this is typically the property name. For parameters, this is usually undefined unless explicitly set.

noun

string

A noun that represents the decorated element. Nouns are used for grammatical purposes and can help with generating proper text in documentation or user interfaces.

nounPlural

string

The plural form of the noun. Used when referring to multiple instances of the decorated element.

sensitive

boolean

Indicates whether the decorated element contains sensitive information. When true, this element should be treated with special care in terms of logging, serialization, and display to ensure sensitive data is not inadvertently exposed.

token

string

A token identifier for the decorated element. Tokens are typically used for internal identification and can be used for serialization or other programmatic operations.

tokenPlural

string

The plural form of the token. Used when referring to multiple instances of the decorated element.

for

MetadataDescriptor

Gets or creates a MetadataDescriptor for the specified target.

@paramtarget:  object | Class
The target class constructor or object to get metadata for.
@paramproperty:  string
Optional property name when getting metadata for a property or method.
@paramindex:  number
Optional parameter index when getting metadata for a method parameter.
@returnsMetadataDescriptor

get

undefined | MetadataDescriptor

Retrieves an existing MetadataDescriptor for the specified target.

@paramtarget:  object | Class
The target class constructor or object to get metadata for.
@paramproperty:  string
Optional property name when getting metadata for a property or method.
@paramindex:  number
Optional parameter index when getting metadata for a method parameter.
@returnsundefined | MetadataDescriptor

Description

A descriptor that holds metadata information for classes, properties, methods, and parameters.

The MetadataDescriptor class is used to store and retrieve metadata associated with various elements in your codebase. It supports storing information like names, labelPlural, descriptions, and other metadata that can be used for serialization, validation, documentation generation, and other metadata-driven operations.

Usage

Creating a Descriptor

// create a get descriptor for a class
const descriptor = MetaDataDescriptor.for(MyClass);

// create or get a descriptor for a property or method
const descriptor = MetaDataDescriptor.for(MyClass, 'myProperty');

// create or get adescriptor for a method parameter
const descriptor = MetaDataDescriptor.for(MyClass, 'myMethod', 0);

Retrieving and Existing Descriptor

// get descriptor for a class
const descriptor = MetaDataDescriptor.get(MyClass);

// get descriptor for a property or method
const descriptor = MetaDataDescriptor.get(MyClass, 'myProperty');

// get descriptor for a method parameter
const descriptor = MetaDataDescriptor.get(MyClass, 'myMethod', 0);

Example

class User {
  @Label('Email address')
  @Description('The user\'s email address')
  @Sensitive()
  email: string;

  @Label('Full name')
  fullName: string;
}

// Get metadata for the class
const classDescriptor = MetadataDescriptor.for(User);
console.log(classDescriptor.name); // 'User'

// Get metadata for the email property
const emailDescriptor = MetadataDescriptor.for(User, 'email');
console.log(emailDescriptor.label); // 'Email Address'
console.log(emailDescriptor.sensitive); // true

Resources