Skip to Content
nyx logonyx guide

Metadata

Reading time:2 min read

Many parts of the framework introduce the concept of a Metadata, which can store metadata about a given object, or about a given execution.

Type Safety

Since a metadata object is just a record of unknown values, it's inherently unsafe by itself.

For that reason, nyx uses the typed-field package, which creates a unique key, and only lets you set/get with a given type.

The typed-field package is re-exported in TypedFields.create() method, so you don't need to install it separately.

import {  } from '@nyx-discord/djs';

const : <string | symbol, unknown> = .(null);

// Fields with the same description won't collide
const  = .<number>('someDescription');

.(, 42);
.(, 'foo');
Argument of type 'string' is not assignable to parameter of type 'number'.
const stored = .();
const stored: number | undefined
// Throws if no value was set const forced = .(, true);
const forced: number

Object Metadata

Most nyx objects implement a getMeta(): ReadonlyMetadata method. When creating your class, you can fill this with your own metadata, which can then be read by plugins or other entities to extract extra information about your object.

As a plugin developer, you may also choose to use the TypedFields API to create and expose a field:

import {  } from '@nyx-discord/djs';

type  = {
  : string;
}
export const  = .<>('myPluginData');

Then, a consumer of your plugin can use it to decorate their objects' metadata:

import {  } from '@nyx-discord/djs';
import {  } from 'my-nyx-plugin';

class  extends  {
  constructor() {
    super();
    .(this., { : 'someValue' });

    // In case they use it wrongly, it'll error:
    .(this., 42);
  }
}

Which then you'll be able to read with MyCommand#getMeta() and your field, safely.

Execution Metadata

Every "executable" object includes in its arguments an instance of a Metadata, which is passed around to middlewares and filters, so they can share data between them, and to your executed object.

Additionally, the TypedFields class contains constant fields that the framework uses to store framework-specific data.

import {  } from '@nyx-discord/djs';

// The bot who triggered the object (command, event, etc).
const bot = ..(, true);
const bot: NyxBot<InjectableBotDependencies<any, NyxClient<EventEmitterLike>, any, any>>
// Shorthands for the bot typed for this adapter, its discord.js Client and its logger, which throw if the meta has no bot. const typedBot = .();
const typedBot: DjsBot<DjsBotDependencies>
const client = .();
const client: Client<boolean>
const logger = .();
const logger: NyxLogger
// The identifier of this object execution, which is a Symbol containing some debugable information. const id = ..(, true);
const id: Identifier
// The creation date of this meta, can be used as the execution start time. const creationDate = ..(, true);
const creationDate: Date
// Only for event middlewares and subscribers, whether the event was marked as handled by a subscriber. const handled = ..(, true);
const handled: boolean
// Only for event middlewares and subscribers, the EventBus that dispatched the event. const eventBus = ..(, true);
const eventBus: AnyEventBus

Forcing these reads is safe for metadatas created inside the framework, but not for user-created metadatas, including those created by external EventBuses (since they're bot-independent).

On this page