Metadata
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');
const stored = .();
// Throws if no value was set
const forced = .(, true);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);
// 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 client = .();const logger = .();
// The identifier of this object execution, which is a Symbol containing some debugable information.
const id = ..(, true);
// The creation date of this meta, can be used as the execution start time.
const creationDate = ..(, true);
// Only for event middlewares and subscribers, whether the event was marked as handled by a subscriber.
const handled = ..(, true);
// Only for event middlewares and subscribers, the EventBus that dispatched the event.
const eventBus = ..(, true);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).
