@seedcord/services 0.3.3 → 0.4.0

package/dist/index.d.cts

@@ -1,7 +1,168 @@
-import { ILogger, TypedExclude } from '@seedcord/types';
 import { EventEmitter } from 'node:events';
+import { ILogger, TypedExclude } from '@seedcord/types';
 import { IntClosedRange, UnionToTuple } from 'type-fest';
 
+/**
+ * Configuration options for CooldownManager.
+ */
+interface CooldownOptions {
+    /** Cooldown window in milliseconds (default 1000) */
+    cooldown?: number;
+    /** Custom error class to throw when a key is still cooling down */
+    err?: new (msg: string, ...args: any[]) => Error;
+    /** Message passed to the error constructor (default "Cooldown active") */
+    message?: string;
+}
+/**
+ * Lightweight utility for per-key cooldowns.
+ *
+ * Manages time-based restrictions on operations by key,
+ * useful for rate limiting, command cooldowns, and spam prevention.
+ */
+declare class CooldownManager {
+    private readonly window;
+    private readonly Err;
+    private readonly msg;
+    private readonly map;
+    /**
+     * Creates a new CooldownManager instance.
+     *
+     * @param opts - Configuration options for the cooldown behavior
+     */
+    constructor(opts?: CooldownOptions);
+    /**
+     * Records usage timestamp for a key without any cooldown checks.
+     *
+     * @param key - The unique identifier for the cooldown entry
+     */
+    set(key: string): void;
+    /**
+     * Verifies cooldown status for a key and updates timestamp if not active.
+     *
+     * If the cooldown is still active, throws the configured error.
+     * If not active, updates the timestamp and returns successfully.
+     *
+     * @param key - The unique identifier to check cooldown for
+     * @throws An {@link Err} When the cooldown is still active for the given key
+     */
+    check(key: string): void;
+    /**
+     * Checks if a key is currently cooling down without updating timestamp.
+     *
+     * @param key - The unique identifier to check
+     * @returns True if the key is still cooling down, false otherwise
+     */
+    isActive(key: string): boolean;
+    /**
+     * Removes a key from the cooldown map.
+     *
+     * @param key - The unique identifier to remove (useful for manual resets)
+     */
+    clear(key: string): void;
+}
+
+declare enum SeedcordErrorCode {
+    ConfigMissingDiscordToken = 1001,
+    ConfigUnknownExceptionWebhookMissing = 1002,
+    ConfigUnknownExceptionWebhookInvalid = 1003,
+    LifecycleAddAfterCompletion = 1101,
+    LifecycleAddDuringRun = 1102,
+    LifecycleRemoveDuringRun = 1103,
+    LifecycleUnknownPhase = 1104,
+    LifecyclePhaseFailures = 1105,
+    LifecycleTaskTimeout = 1106,
+    CoreSingletonViolation = 1201,
+    CorePluginAfterInit = 1202,
+    CorePluginKeyExists = 1203,
+    CoreClientUserUnavailable = 1204,
+    CoreBotRoleMissing = 1205,
+    DecoratorInteractionEventFilter = 1301,
+    DecoratorMethodNotFound = 1302,
+    DecoratorCommandAlreadyRegistered = 1303,
+    DecoratorCommandGlobalWithGuilds = 1304,
+    DecoratorCommandGuildWithoutGuilds = 1305,
+    DecoratorInvalidMiddlewarePriority = 1306,
+    UtilHexInputType = 1401,
+    UtilHexInvalid = 1402,
+    UtilInvalidSlashRouteArgument = 1403,
+    PluginMongoServiceDecoratorMissing = 2101,
+    PluginMongoModelDecoratorMissing = 2102,
+    PluginMongoConnectionFailed = 2103,
+    PluginKpgServiceDecoratorMissing = 2201,
+    PluginKpgServiceTableMissing = 2202,
+    PluginKpgInvalidStepCount = 2203,
+    PluginKpgUnknownDirection = 2204,
+    PluginKpgUnresolvedMigrationsPath = 2205,
+    PluginKpgNoMigrationFiles = 2206,
+    PluginKpgInvalidMigrationModule = 2207,
+    PluginKpgNonErrorFailure = 2208
+}
+
+declare const messages: {
+    readonly 1001: () => string;
+    readonly 1002: () => string;
+    readonly 1003: () => string;
+    readonly 1101: () => string;
+    readonly 1102: () => string;
+    readonly 1103: () => string;
+    readonly 1104: (phase: unknown) => string;
+    readonly 1105: (phase: string, failures: number) => string;
+    readonly 1106: (taskName: string, timeout: number) => string;
+    readonly 1201: () => string;
+    readonly 1202: () => string;
+    readonly 1203: (key: string) => string;
+    readonly 1204: () => string;
+    readonly 1205: (guildId?: string) => string;
+    readonly 1301: () => string;
+    readonly 1302: () => string;
+    readonly 1303: (commandName: string, existingScope: string, requestedScope: string) => string;
+    readonly 1304: () => string;
+    readonly 1305: () => string;
+    readonly 1306: () => string;
+    readonly 1401: () => string;
+    readonly 1402: () => string;
+    readonly 1403: () => string;
+    readonly 2101: (className: string) => string;
+    readonly 2102: (className: string) => string;
+    readonly 2103: (databaseName?: string) => string;
+    readonly 2201: (className: string) => string;
+    readonly 2202: (className: string) => string;
+    readonly 2203: () => string;
+    readonly 2204: (direction: unknown) => string;
+    readonly 2205: (label: string) => string;
+    readonly 2206: () => string;
+    readonly 2207: (filePath: string) => string;
+    readonly 2208: (message: string) => string;
+};
+type SeedcordErrorArguments<TCode extends SeedcordErrorCode> = Parameters<(typeof messages)[TCode]>;
+declare function formatSeedcordErrorMessage<TCode extends SeedcordErrorCode>(code: TCode, args?: SeedcordErrorArguments<TCode>): string;
+
+type SeedcordErrorIdentifier = keyof typeof SeedcordErrorCode;
+interface SeedcordErrorOptions extends ErrorOptions {
+}
+declare class SeedcordError extends Error {
+    readonly code: SeedcordErrorCode;
+    readonly identifier: SeedcordErrorIdentifier;
+    constructor(code: SeedcordErrorCode, args?: SeedcordErrorArguments<SeedcordErrorCode>, options?: SeedcordErrorOptions);
+}
+declare class SeedcordTypeError extends TypeError {
+    readonly code: SeedcordErrorCode;
+    readonly identifier: SeedcordErrorIdentifier;
+    constructor(code: SeedcordErrorCode, args?: SeedcordErrorArguments<SeedcordErrorCode>, options?: SeedcordErrorOptions);
+}
+declare class SeedcordRangeError extends RangeError {
+    readonly code: SeedcordErrorCode;
+    readonly identifier: SeedcordErrorIdentifier;
+    constructor(code: SeedcordErrorCode, args?: SeedcordErrorArguments<SeedcordErrorCode>, options?: SeedcordErrorOptions);
+}
+declare const SeedcordErrors: {
+    readonly Error: typeof SeedcordError;
+    readonly TypeError: typeof SeedcordTypeError;
+    readonly RangeError: typeof SeedcordRangeError;
+};
+type AnySeedcordError = SeedcordError | SeedcordTypeError | SeedcordRangeError;
+declare function isSeedcordError(error: unknown): error is AnySeedcordError;
+
 /**
  * Logging service with console and file output support
  *
@@ -304,63 +465,111 @@ declare class HealthCheck {
     stop(): Promise<void>;
 }
 
+/** Tuple type used for all event payloads. */
+type SEArgsTuple = readonly unknown[];
+/** Convenience map for emitters that intentionally expose no events. */
+type SENoEvents = Record<never, SEArgsTuple>;
 /**
- * Configuration options for CooldownManager.
+ * Accepts any object type and constrains every value to be a tuple.
+ *
+ * @typeParam TEvents - Map of event names to readonly tuple payloads
  */
-interface CooldownOptions {
-    /** Cooldown window in milliseconds (default 1000) */
-    cooldown?: number;
-    /** Custom error class to throw when a key is still cooling down */
-    err?: new (msg: string, ...args: any[]) => Error;
-    /** Message passed to the error constructor (default "Cooldown active") */
-    message?: string;
-}
+type SEEventMapLike<TEvents extends object> = {
+    [K in keyof TEvents]: SEArgsTuple;
+};
 /**
- * Lightweight utility for per-key cooldowns.
+ * Narrows a provided event map to the keys that can be emitted or listened for.
  *
- * Manages time-based restrictions on operations by key,
- * useful for rate limiting, command cooldowns, and spam prevention.
+ * @typeParam TEvents - Map of event names to readonly tuple payloads
+ * @internal
  */
-declare class CooldownManager {
-    private readonly window;
-    private readonly Err;
-    private readonly msg;
-    private readonly map;
+type SEEventKey<TEvents extends object> = Extract<keyof TEvents, string | symbol>;
+/**
+ * Typed wrapper around Node.js {@link EventEmitter} enforcing tuple payloads per event name.
+ *
+ * @typeParam TEvents - Map of event names to readonly tuple payloads
+ */
+declare class StrictEventEmitter<TEvents extends SEEventMapLike<TEvents>> extends EventEmitter {
     /**
-     * Creates a new CooldownManager instance.
+     * Registers a persistent listener with tuple-safe arguments for the given event.
      *
-     * @param opts - Configuration options for the cooldown behavior
+     * @param event - The event name to attach to
+     * @param listener - Callback operating on the typed argument tuple for the event
+     * @returns This emitter instance for chaining
      */
-    constructor(opts?: CooldownOptions);
+    on<TEventKey extends SEEventKey<TEvents>>(event: TEventKey, listener: (...args: TEvents[TEventKey]) => void): this;
     /**
-     * Records usage timestamp for a key without any cooldown checks.
+     * Registers a one time listener that is removed after the first invocation.
      *
-     * @param key - The unique identifier for the cooldown entry
+     * @param event - The event name to attach to
+     * @param listener - Callback operating on the typed argument tuple for the event
+     * @returns This emitter instance for chaining
      */
-    set(key: string): void;
+    once<TEventKey extends SEEventKey<TEvents>>(event: TEventKey, listener: (...args: TEvents[TEventKey]) => void): this;
     /**
-     * Verifies cooldown status for a key and updates timestamp if not active.
+     * Removes a previously registered listener for the given event.
      *
-     * If the cooldown is still active, throws the configured error.
-     * If not active, updates the timestamp and returns successfully.
+     * @param event - The event name whose listener should be removed
+     * @param listener - Callback originally registered for the event
+     * @returns This emitter instance for chaining
+     */
+    off<TEventKey extends SEEventKey<TEvents>>(event: TEventKey, listener: (...args: TEvents[TEventKey]) => void): this;
+    /**
+     * Alias of {@link StrictEventEmitter.on} for compatibility with Node.js EventEmitter APIs.
      *
-     * @param key - The unique identifier to check cooldown for
-     * @throws An {@link Err} When the cooldown is still active for the given key
+     * @param event - The event name to attach to
+     * @param listener - Callback operating on the typed argument tuple for the event
+     * @returns This emitter instance for chaining
      */
-    check(key: string): void;
+    addListener<TEventKey extends SEEventKey<TEvents>>(event: TEventKey, listener: (...args: TEvents[TEventKey]) => void): this;
     /**
-     * Checks if a key is currently cooling down without updating timestamp.
+     * Alias of {@link StrictEventEmitter.off} for compatibility with Node.js EventEmitter APIs.
      *
-     * @param key - The unique identifier to check
-     * @returns True if the key is still cooling down, false otherwise
+     * @param event - The event name whose listener should be removed
+     * @param listener - Callback originally registered for the event
+     * @returns This emitter instance for chaining
      */
-    isActive(key: string): boolean;
+    removeListener<TEventKey extends SEEventKey<TEvents>>(event: TEventKey, listener: (...args: TEvents[TEventKey]) => void): this;
     /**
-     * Removes a key from the cooldown map.
+     * Emits an event with the strictly typed argument tuple for the event name.
      *
-     * @param key - The unique identifier to remove (useful for manual resets)
+     * @param event - The event name to emit
+     * @param args - Tuple payload for the event
+     * @returns True when the event had listeners, false otherwise
      */
-    clear(key: string): void;
+    emit<TEventKey extends SEEventKey<TEvents>>(event: TEventKey, ...args: TEvents[TEventKey]): boolean;
+    /**
+     * Retrieves the listener list for a given event with the correct tuple signature.
+     *
+     * @param event - The event name to inspect
+     * @returns Array of listeners registered for the event
+     */
+    listeners<TEventKey extends SEEventKey<TEvents>>(event: TEventKey): ((...args: TEvents[TEventKey]) => void)[];
+    /**
+     * Counts listeners for an event without widening the return type of {@link EventEmitter.listenerCount}.
+     *
+     * @param event - The event name to inspect
+     * @returns The total number of listeners registered for the event
+     */
+    listenerCountTyped<TEventKey extends SEEventKey<TEvents>>(event: TEventKey): number;
+    /**
+     * Returns the list of event names known to the emitter with the mapped key type.
+     *
+     * @returns Array of event keys supported by the emitter
+     */
+    eventNamesTyped(): SEEventKey<TEvents>[];
+    /**
+     * Waits for an event to be emitted, resolving with the listener arguments tuple once triggered.
+     * Supports optional abort signals and timeouts for cancellation semantics.
+     *
+     * @param event - The event name to wait for
+     * @param opts - Optional abort signal or timeout in milliseconds
+     * @returns Promise resolving with the emitted argument tuple; rejects when aborted or timed out
+     */
+    waitFor<TEventKey extends SEEventKey<TEvents>>(event: TEventKey, opts?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<TEvents[TEventKey]>;
 }
 
 /**
@@ -446,4 +655,4 @@ declare class CoordinatedStartup extends CoordinatedLifecycle<StartupPhase> {
     get isRunning(): boolean;
 }
 
-export { CooldownManager, type CooldownOptions, CoordinatedLifecycle, CoordinatedShutdown, type CoordinatedShutdownEventKey, CoordinatedStartup, type CoordinatedStartupEventKey, HealthCheck, type LifecycleAction, type LifecycleTask, Logger, type PhaseEvents, ShutdownPhase, StartupPhase };
+export { type AnySeedcordError, CooldownManager, type CooldownOptions, CoordinatedLifecycle, CoordinatedShutdown, type CoordinatedShutdownEventKey, CoordinatedStartup, type CoordinatedStartupEventKey, HealthCheck, type LifecycleAction, type LifecycleTask, Logger, type PhaseEvents, type SEArgsTuple, type SEEventKey, type SEEventMapLike, type SENoEvents, SeedcordError, type SeedcordErrorArguments, SeedcordErrorCode, type SeedcordErrorIdentifier, type SeedcordErrorOptions, SeedcordErrors, SeedcordRangeError, SeedcordTypeError, ShutdownPhase, StartupPhase, StrictEventEmitter, formatSeedcordErrorMessage, isSeedcordError, messages as seedcordErrorMessages };

package/dist/index.d.ts

@@ -1,7 +1,168 @@
-import { ILogger, TypedExclude } from '@seedcord/types';
 import { EventEmitter } from 'node:events';
+import { ILogger, TypedExclude } from '@seedcord/types';
 import { IntClosedRange, UnionToTuple } from 'type-fest';
 
+/**
+ * Configuration options for CooldownManager.
+ */
+interface CooldownOptions {
+    /** Cooldown window in milliseconds (default 1000) */
+    cooldown?: number;
+    /** Custom error class to throw when a key is still cooling down */
+    err?: new (msg: string, ...args: any[]) => Error;
+    /** Message passed to the error constructor (default "Cooldown active") */
+    message?: string;
+}
+/**
+ * Lightweight utility for per-key cooldowns.
+ *
+ * Manages time-based restrictions on operations by key,
+ * useful for rate limiting, command cooldowns, and spam prevention.
+ */
+declare class CooldownManager {
+    private readonly window;
+    private readonly Err;
+    private readonly msg;
+    private readonly map;
+    /**
+     * Creates a new CooldownManager instance.
+     *
+     * @param opts - Configuration options for the cooldown behavior
+     */
+    constructor(opts?: CooldownOptions);
+    /**
+     * Records usage timestamp for a key without any cooldown checks.
+     *
+     * @param key - The unique identifier for the cooldown entry
+     */
+    set(key: string): void;
+    /**
+     * Verifies cooldown status for a key and updates timestamp if not active.
+     *
+     * If the cooldown is still active, throws the configured error.
+     * If not active, updates the timestamp and returns successfully.
+     *
+     * @param key - The unique identifier to check cooldown for
+     * @throws An {@link Err} When the cooldown is still active for the given key
+     */
+    check(key: string): void;
+    /**
+     * Checks if a key is currently cooling down without updating timestamp.
+     *
+     * @param key - The unique identifier to check
+     * @returns True if the key is still cooling down, false otherwise
+     */
+    isActive(key: string): boolean;
+    /**
+     * Removes a key from the cooldown map.
+     *
+     * @param key - The unique identifier to remove (useful for manual resets)
+     */
+    clear(key: string): void;
+}
+
+declare enum SeedcordErrorCode {
+    ConfigMissingDiscordToken = 1001,
+    ConfigUnknownExceptionWebhookMissing = 1002,
+    ConfigUnknownExceptionWebhookInvalid = 1003,
+    LifecycleAddAfterCompletion = 1101,
+    LifecycleAddDuringRun = 1102,
+    LifecycleRemoveDuringRun = 1103,
+    LifecycleUnknownPhase = 1104,
+    LifecyclePhaseFailures = 1105,
+    LifecycleTaskTimeout = 1106,
+    CoreSingletonViolation = 1201,
+    CorePluginAfterInit = 1202,
+    CorePluginKeyExists = 1203,
+    CoreClientUserUnavailable = 1204,
+    CoreBotRoleMissing = 1205,
+    DecoratorInteractionEventFilter = 1301,
+    DecoratorMethodNotFound = 1302,
+    DecoratorCommandAlreadyRegistered = 1303,
+    DecoratorCommandGlobalWithGuilds = 1304,
+    DecoratorCommandGuildWithoutGuilds = 1305,
+    DecoratorInvalidMiddlewarePriority = 1306,
+    UtilHexInputType = 1401,
+    UtilHexInvalid = 1402,
+    UtilInvalidSlashRouteArgument = 1403,
+    PluginMongoServiceDecoratorMissing = 2101,
+    PluginMongoModelDecoratorMissing = 2102,
+    PluginMongoConnectionFailed = 2103,
+    PluginKpgServiceDecoratorMissing = 2201,
+    PluginKpgServiceTableMissing = 2202,
+    PluginKpgInvalidStepCount = 2203,
+    PluginKpgUnknownDirection = 2204,
+    PluginKpgUnresolvedMigrationsPath = 2205,
+    PluginKpgNoMigrationFiles = 2206,
+    PluginKpgInvalidMigrationModule = 2207,
+    PluginKpgNonErrorFailure = 2208
+}
+
+declare const messages: {
+    readonly 1001: () => string;
+    readonly 1002: () => string;
+    readonly 1003: () => string;
+    readonly 1101: () => string;
+    readonly 1102: () => string;
+    readonly 1103: () => string;
+    readonly 1104: (phase: unknown) => string;
+    readonly 1105: (phase: string, failures: number) => string;
+    readonly 1106: (taskName: string, timeout: number) => string;
+    readonly 1201: () => string;
+    readonly 1202: () => string;
+    readonly 1203: (key: string) => string;
+    readonly 1204: () => string;
+    readonly 1205: (guildId?: string) => string;
+    readonly 1301: () => string;
+    readonly 1302: () => string;
+    readonly 1303: (commandName: string, existingScope: string, requestedScope: string) => string;
+    readonly 1304: () => string;
+    readonly 1305: () => string;
+    readonly 1306: () => string;
+    readonly 1401: () => string;
+    readonly 1402: () => string;
+    readonly 1403: () => string;
+    readonly 2101: (className: string) => string;
+    readonly 2102: (className: string) => string;
+    readonly 2103: (databaseName?: string) => string;
+    readonly 2201: (className: string) => string;
+    readonly 2202: (className: string) => string;
+    readonly 2203: () => string;
+    readonly 2204: (direction: unknown) => string;
+    readonly 2205: (label: string) => string;
+    readonly 2206: () => string;
+    readonly 2207: (filePath: string) => string;
+    readonly 2208: (message: string) => string;
+};
+type SeedcordErrorArguments<TCode extends SeedcordErrorCode> = Parameters<(typeof messages)[TCode]>;
+declare function formatSeedcordErrorMessage<TCode extends SeedcordErrorCode>(code: TCode, args?: SeedcordErrorArguments<TCode>): string;
+
+type SeedcordErrorIdentifier = keyof typeof SeedcordErrorCode;
+interface SeedcordErrorOptions extends ErrorOptions {
+}
+declare class SeedcordError extends Error {
+    readonly code: SeedcordErrorCode;
+    readonly identifier: SeedcordErrorIdentifier;
+    constructor(code: SeedcordErrorCode, args?: SeedcordErrorArguments<SeedcordErrorCode>, options?: SeedcordErrorOptions);
+}
+declare class SeedcordTypeError extends TypeError {
+    readonly code: SeedcordErrorCode;
+    readonly identifier: SeedcordErrorIdentifier;
+    constructor(code: SeedcordErrorCode, args?: SeedcordErrorArguments<SeedcordErrorCode>, options?: SeedcordErrorOptions);
+}
+declare class SeedcordRangeError extends RangeError {
+    readonly code: SeedcordErrorCode;
+    readonly identifier: SeedcordErrorIdentifier;
+    constructor(code: SeedcordErrorCode, args?: SeedcordErrorArguments<SeedcordErrorCode>, options?: SeedcordErrorOptions);
+}
+declare const SeedcordErrors: {
+    readonly Error: typeof SeedcordError;
+    readonly TypeError: typeof SeedcordTypeError;
+    readonly RangeError: typeof SeedcordRangeError;
+};
+type AnySeedcordError = SeedcordError | SeedcordTypeError | SeedcordRangeError;
+declare function isSeedcordError(error: unknown): error is AnySeedcordError;
+
 /**
  * Logging service with console and file output support
  *
@@ -304,63 +465,111 @@ declare class HealthCheck {
     stop(): Promise<void>;
 }
 
+/** Tuple type used for all event payloads. */
+type SEArgsTuple = readonly unknown[];
+/** Convenience map for emitters that intentionally expose no events. */
+type SENoEvents = Record<never, SEArgsTuple>;
 /**
- * Configuration options for CooldownManager.
+ * Accepts any object type and constrains every value to be a tuple.
+ *
+ * @typeParam TEvents - Map of event names to readonly tuple payloads
  */
-interface CooldownOptions {
-    /** Cooldown window in milliseconds (default 1000) */
-    cooldown?: number;
-    /** Custom error class to throw when a key is still cooling down */
-    err?: new (msg: string, ...args: any[]) => Error;
-    /** Message passed to the error constructor (default "Cooldown active") */
-    message?: string;
-}
+type SEEventMapLike<TEvents extends object> = {
+    [K in keyof TEvents]: SEArgsTuple;
+};
 /**
- * Lightweight utility for per-key cooldowns.
+ * Narrows a provided event map to the keys that can be emitted or listened for.
  *
- * Manages time-based restrictions on operations by key,
- * useful for rate limiting, command cooldowns, and spam prevention.
+ * @typeParam TEvents - Map of event names to readonly tuple payloads
+ * @internal
  */
-declare class CooldownManager {
-    private readonly window;
-    private readonly Err;
-    private readonly msg;
-    private readonly map;
+type SEEventKey<TEvents extends object> = Extract<keyof TEvents, string | symbol>;
+/**
+ * Typed wrapper around Node.js {@link EventEmitter} enforcing tuple payloads per event name.
+ *
+ * @typeParam TEvents - Map of event names to readonly tuple payloads
+ */
+declare class StrictEventEmitter<TEvents extends SEEventMapLike<TEvents>> extends EventEmitter {
     /**
-     * Creates a new CooldownManager instance.
+     * Registers a persistent listener with tuple-safe arguments for the given event.
      *
-     * @param opts - Configuration options for the cooldown behavior
+     * @param event - The event name to attach to
+     * @param listener - Callback operating on the typed argument tuple for the event
+     * @returns This emitter instance for chaining
      */
-    constructor(opts?: CooldownOptions);
+    on<TEventKey extends SEEventKey<TEvents>>(event: TEventKey, listener: (...args: TEvents[TEventKey]) => void): this;
     /**
-     * Records usage timestamp for a key without any cooldown checks.
+     * Registers a one time listener that is removed after the first invocation.
      *
-     * @param key - The unique identifier for the cooldown entry
+     * @param event - The event name to attach to
+     * @param listener - Callback operating on the typed argument tuple for the event
+     * @returns This emitter instance for chaining
      */
-    set(key: string): void;
+    once<TEventKey extends SEEventKey<TEvents>>(event: TEventKey, listener: (...args: TEvents[TEventKey]) => void): this;
     /**
-     * Verifies cooldown status for a key and updates timestamp if not active.
+     * Removes a previously registered listener for the given event.
      *
-     * If the cooldown is still active, throws the configured error.
-     * If not active, updates the timestamp and returns successfully.
+     * @param event - The event name whose listener should be removed
+     * @param listener - Callback originally registered for the event
+     * @returns This emitter instance for chaining
+     */
+    off<TEventKey extends SEEventKey<TEvents>>(event: TEventKey, listener: (...args: TEvents[TEventKey]) => void): this;
+    /**
+     * Alias of {@link StrictEventEmitter.on} for compatibility with Node.js EventEmitter APIs.
      *
-     * @param key - The unique identifier to check cooldown for
-     * @throws An {@link Err} When the cooldown is still active for the given key
+     * @param event - The event name to attach to
+     * @param listener - Callback operating on the typed argument tuple for the event
+     * @returns This emitter instance for chaining
      */
-    check(key: string): void;
+    addListener<TEventKey extends SEEventKey<TEvents>>(event: TEventKey, listener: (...args: TEvents[TEventKey]) => void): this;
     /**
-     * Checks if a key is currently cooling down without updating timestamp.
+     * Alias of {@link StrictEventEmitter.off} for compatibility with Node.js EventEmitter APIs.
      *
-     * @param key - The unique identifier to check
-     * @returns True if the key is still cooling down, false otherwise
+     * @param event - The event name whose listener should be removed
+     * @param listener - Callback originally registered for the event
+     * @returns This emitter instance for chaining
      */
-    isActive(key: string): boolean;
+    removeListener<TEventKey extends SEEventKey<TEvents>>(event: TEventKey, listener: (...args: TEvents[TEventKey]) => void): this;
     /**
-     * Removes a key from the cooldown map.
+     * Emits an event with the strictly typed argument tuple for the event name.
      *
-     * @param key - The unique identifier to remove (useful for manual resets)
+     * @param event - The event name to emit
+     * @param args - Tuple payload for the event
+     * @returns True when the event had listeners, false otherwise
      */
-    clear(key: string): void;
+    emit<TEventKey extends SEEventKey<TEvents>>(event: TEventKey, ...args: TEvents[TEventKey]): boolean;
+    /**
+     * Retrieves the listener list for a given event with the correct tuple signature.
+     *
+     * @param event - The event name to inspect
+     * @returns Array of listeners registered for the event
+     */
+    listeners<TEventKey extends SEEventKey<TEvents>>(event: TEventKey): ((...args: TEvents[TEventKey]) => void)[];
+    /**
+     * Counts listeners for an event without widening the return type of {@link EventEmitter.listenerCount}.
+     *
+     * @param event - The event name to inspect
+     * @returns The total number of listeners registered for the event
+     */
+    listenerCountTyped<TEventKey extends SEEventKey<TEvents>>(event: TEventKey): number;
+    /**
+     * Returns the list of event names known to the emitter with the mapped key type.
+     *
+     * @returns Array of event keys supported by the emitter
+     */
+    eventNamesTyped(): SEEventKey<TEvents>[];
+    /**
+     * Waits for an event to be emitted, resolving with the listener arguments tuple once triggered.
+     * Supports optional abort signals and timeouts for cancellation semantics.
+     *
+     * @param event - The event name to wait for
+     * @param opts - Optional abort signal or timeout in milliseconds
+     * @returns Promise resolving with the emitted argument tuple; rejects when aborted or timed out
+     */
+    waitFor<TEventKey extends SEEventKey<TEvents>>(event: TEventKey, opts?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<TEvents[TEventKey]>;
 }
 
 /**
@@ -446,4 +655,4 @@ declare class CoordinatedStartup extends CoordinatedLifecycle<StartupPhase> {
     get isRunning(): boolean;
 }
 
-export { CooldownManager, type CooldownOptions, CoordinatedLifecycle, CoordinatedShutdown, type CoordinatedShutdownEventKey, CoordinatedStartup, type CoordinatedStartupEventKey, HealthCheck, type LifecycleAction, type LifecycleTask, Logger, type PhaseEvents, ShutdownPhase, StartupPhase };
+export { type AnySeedcordError, CooldownManager, type CooldownOptions, CoordinatedLifecycle, CoordinatedShutdown, type CoordinatedShutdownEventKey, CoordinatedStartup, type CoordinatedStartupEventKey, HealthCheck, type LifecycleAction, type LifecycleTask, Logger, type PhaseEvents, type SEArgsTuple, type SEEventKey, type SEEventMapLike, type SENoEvents, SeedcordError, type SeedcordErrorArguments, SeedcordErrorCode, type SeedcordErrorIdentifier, type SeedcordErrorOptions, SeedcordErrors, SeedcordRangeError, SeedcordTypeError, ShutdownPhase, StartupPhase, StrictEventEmitter, formatSeedcordErrorMessage, isSeedcordError, messages as seedcordErrorMessages };