@seedcord/services 0.1.0 → 0.2.0

package/package.json

@@ -1,23 +1,20 @@
 {
   "name": "@seedcord/services",
   "type": "module",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Services for Seedcord packages",
   "repository": {
     "type": "git",
     "url": "https://github.com/materwelondhruv/seedcord.git",
     "directory": "packages/services"
   },
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": {
-        "types": "./dist/index.d.mts",
-        "default": "./dist/index.mjs"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.mjs"
     }
   },
   "files": [
@@ -31,18 +28,18 @@
   },
   "dependencies": {
     "discord.js": "14.22.1",
-    "chalk": "5.6.0",
-    "envapt": "3.0.0",
+    "chalk": "5.6.2",
+    "envapt": "3.0.2",
     "winston": "^3.17.0",
-    "@seedcord/types": "^0.1.2"
+    "@seedcord/types": "^0.2.0"
   },
   "devDependencies": {
-    "@seedcord/eslint-config": "^1.1.1",
-    "@seedcord/tsup-config": "^1.0.2",
-    "@seedcord/tsconfig": "^1.0.2"
+    "@seedcord/tsup-config": "^1.0.3",
+    "@seedcord/eslint-config": "^1.2.0",
+    "@seedcord/tsconfig": "^1.0.3"
   },
   "scripts": {
-    "build": "tsup && cp dist/index.d.cts dist/index.d.mts",
+    "build": "tsup",
     "clean": "rm -rf dist",
     "lint": "eslint 'src/**/*.{ts,tsx}' --cache",
     "lint:fix": "eslint 'src/**/*.{ts,tsx}' --fix --cache",

package/dist/index.d.mts

@@ -1,406 +0,0 @@
-import { EventEmitter } from 'node:events';
-import { LifecycleTask, PhaseEvents, UnionToTuple } from '@seedcord/types';
-
-/**
- * Logging service with console and file output support
- *
- * Provides structured logging with timestamps, levels, and labels.
- * Instances are cached by transport name for consistent formatting.
- */
-declare class Logger {
-    private logger;
-    private static readonly instances;
-    private static instance;
-    constructor(transportName: string);
-    private getFormatCustomizations;
-    private createConsoleTransport;
-    private initializeLogger;
-    /**
-     * Logs an error message with optional additional data.
-     *
-     * @param msg - The error message to log
-     * @param args - Additional data to include in the log entry
-     */
-    error(msg: string, ...args: unknown[]): void;
-    /**
-     * Logs a warning message with optional additional data.
-     *
-     * @param msg - The warning message to log
-     * @param args - Additional data to include in the log entry
-     */
-    warn(msg: string, ...args: unknown[]): void;
-    /**
-     * Logs an informational message with optional additional data.
-     *
-     * @param msg - The informational message to log
-     * @param args - Additional data to include in the log entry
-     */
-    info(msg: string, ...args: unknown[]): void;
-    /**
-     * Logs an HTTP-related message with optional additional data.
-     *
-     * @param msg - The HTTP message to log
-     * @param args - Additional data to include in the log entry
-     */
-    http(msg: string, ...args: unknown[]): void;
-    /**
-     * Logs a verbose message with optional additional data.
-     *
-     * @param msg - The verbose message to log
-     * @param args - Additional data to include in the log entry
-     */
-    verbose(msg: string, ...args: unknown[]): void;
-    /**
-     * Logs a debug message with optional additional data.
-     *
-     * @param msg - The debug message to log
-     * @param args - Additional data to include in the log entry
-     */
-    debug(msg: string, ...args: unknown[]): void;
-    /**
-     * Logs a silly/trace level message with optional additional data.
-     *
-     * @param msg - The silly message to log
-     * @param args - Additional data to include in the log entry
-     */
-    silly(msg: string, ...args: unknown[]): void;
-    /**
-     * Static method to log an error message with a specific prefix.
-     * Creates or retrieves a logger instance for the given prefix.
-     *
-     * @param prefix - The logger prefix/label to use
-     * @param msg - The error message to log
-     * @param args - Additional data to include in the log entry
-     */
-    static Error(prefix: string, msg: string, ...args: unknown[]): void;
-    /**
-     * Static method to log an informational message with a specific prefix.
-     * Creates or retrieves a logger instance for the given prefix.
-     *
-     * @param prefix - The logger prefix/label to use
-     * @param msg - The informational message to log
-     * @param args - Additional data to include in the log entry
-     */
-    static Info(prefix: string, msg: string, ...args: unknown[]): void;
-    /**
-     * Static method to log a warning message with a specific prefix.
-     * Creates or retrieves a logger instance for the given prefix.
-     *
-     * @param prefix - The logger prefix/label to use
-     * @param msg - The warning message to log
-     * @param args - Additional data to include in the log entry
-     */
-    static Warn(prefix: string, msg: string, ...args: unknown[]): void;
-    /**
-     * Static method to log a debug message with a specific prefix.
-     * Creates or retrieves a logger instance for the given prefix.
-     *
-     * @param prefix - The logger prefix/label to use
-     * @param msg - The debug message to log
-     * @param args - Additional data to include in the log entry
-     */
-    static Debug(prefix: string, msg: string, ...args: unknown[]): void;
-    /**
-     * Static method to log a silly/trace level message with a specific prefix.
-     * Creates or retrieves a logger instance for the given prefix.
-     *
-     * @param prefix - The logger prefix/label to use
-     * @param msg - The silly message to log
-     * @param args - Additional data to include in the log entry
-     */
-    static Silly(prefix: string, msg: string, ...args: unknown[]): void;
-}
-
-/**
- * Abstract base class for coordinated lifecycle management (startup/shutdown)
- */
-declare abstract class CoordinatedLifecycle<TPhase extends number> {
-    protected readonly phaseOrder: TPhase[];
-    protected readonly phaseEnum: Record<number, string>;
-    protected readonly logger: Logger;
-    protected readonly events: EventEmitter<[never]>;
-    protected readonly tasksMap: Map<TPhase, LifecycleTask[]>;
-    protected constructor(loggerName: string, phaseOrder: TPhase[], phaseEnum: Record<number, string>);
-    /**
-     * Adds a lifecycle task to a specific phase.
-     *
-     * Tasks are executed in phase order during lifecycle operations.
-     * Each task has a timeout to prevent hanging operations.
-     *
-     * @param phase - The lifecycle phase to add the task to
-     * @param taskName - Unique name for the task (used for logging and removal)
-     * @param task - Async function to execute during the phase
-     * @param timeoutMs - Maximum time allowed for task execution in milliseconds
-     * @example
-     * ```typescript
-     * lifecycle.addTask(StartupPhase.Services, 'start-database', async () => {
-     *   await database.connect();
-     * }, 10000);
-     * ```
-     */
-    addTask(phase: TPhase, taskName: string, task: () => Promise<void>, timeoutMs: number): void;
-    /**
-     * Removes a lifecycle task from a specific phase.
-     *
-     * @param phase - The lifecycle phase to remove the task from
-     * @param taskName - Name of the task to remove
-     * @returns True if the task was found and removed, false otherwise
-     */
-    removeTask(phase: TPhase, taskName: string): boolean;
-    /**
-     * Run all tasks in a specific phase
-     */
-    protected runPhase(phase: TPhase): Promise<void>;
-    /**
-     * Run a single task with timeout
-     */
-    protected runTaskWithTimeout(phase: TPhase, task: LifecycleTask): Promise<void>;
-    /**
-     * Subscribe to lifecycle events
-     */
-    on(event: string, listener: (...args: unknown[]) => void): void;
-    /**
-     * Unsubscribe from lifecycle events
-     */
-    off(event: string, listener: (...args: unknown[]) => void): void;
-    protected emit(event: string, ...args: unknown[]): boolean;
-    protected abstract canAddTask(): boolean;
-    protected abstract canRemoveTask(): boolean;
-    protected abstract getTaskType(): string;
-    protected abstract executeTasksInPhase(phase: TPhase, tasks: LifecycleTask[]): Promise<PromiseSettledResult<void>[]>;
-}
-
-/**
- * Shutdown phases for coordinated application shutdown.
- */
-declare enum ShutdownPhase {
-    /** Stop accepting new requests/interactions */
-    StopAcceptingRequests = 1,
-    /** Stop background services (health checks, etc.) */
-    StopServices = 2,
-    /** Disconnect from external resources (database, APIs) */
-    ExternalResources = 3,
-    /** Disconnect from Discord */
-    DiscordCleanup = 4,
-    /** Final cleanup tasks */
-    FinalCleanup = 5
-}
-type CoordinatedShutdownEventKey = PhaseEvents<'shutdown', UnionToTuple<ShutdownPhase>>;
-declare class CoordinatedShutdown extends CoordinatedLifecycle<ShutdownPhase> {
-    private readonly isShutdownEnabled;
-    private isShuttingDown;
-    private exitCode;
-    constructor();
-    protected canAddTask(): boolean;
-    protected canRemoveTask(): boolean;
-    protected getTaskType(): string;
-    protected executeTasksInPhase(phase: ShutdownPhase, tasks: LifecycleTask[]): Promise<PromiseSettledResult<void>[]>;
-    private registerSignalHandlers;
-    /**
-     * Adds a task to a specific shutdown phase with timeout.
-     *
-     * @param phase - The shutdown phase from {@link ShutdownPhase}
-     * @param taskName - Unique identifier for the task
-     * @param task - Async function to execute
-     * @param timeoutMs - Task timeout in milliseconds (default: 5000)
-     */
-    addTask(phase: ShutdownPhase, taskName: string, task: () => Promise<void>, timeoutMs?: number): void;
-    /**
-     * Removes a task from a specific shutdown phase.
-     *
-     * @param phase - The shutdown phase to remove from
-     * @param taskName - Name of the task to remove
-     * @returns True if task was found and removed
-     */
-    removeTask(phase: ShutdownPhase, taskName: string): boolean;
-    /**
-     * Executes the coordinated shutdown sequence.
-     *
-     * Runs all registered tasks across shutdown phases in reverse order.
-     * Tasks within each phase are executed in parallel for faster shutdown.
-     * Process exits with the specified code when complete.
-     *
-     * @param exitCode - Process exit code (default: 0)
-     * @returns Promise that resolves when shutdown is complete
-     * @example
-     * ```typescript
-     * shutdown.addTask(ShutdownPhase.Services, 'database', () => db.disconnect(), 5000);
-     * await shutdown.run(0); // Graceful shutdown
-     * ```
-     */
-    run(exitCode?: number): Promise<void>;
-    /**
-     * Subscribe to shutdown events
-     */
-    on(event: CoordinatedShutdownEventKey, listener: (...args: unknown[]) => void): void;
-    /**
-     * Unsubscribe from shutdown events
-     */
-    off(event: CoordinatedShutdownEventKey, listener: (...args: unknown[]) => void): void;
-}
-
-/**
- * HTTP health check service for monitoring bot status.
- *
- * Provides a simple HTTP endpoint that responds with JSON status
- * information, useful for container orchestration and monitoring.
- */
-declare class HealthCheck {
-    readonly logger: Logger;
-    readonly port: number;
-    readonly path: string;
-    private server?;
-    constructor(shutdown: CoordinatedShutdown);
-    /**
-     * Starts the health check server.
-     * @returns Promise that resolves when the server is listening
-     */
-    init(): Promise<void>;
-    /**
-     * Stops the health check server.
-     *
-     * @returns Promise that resolves when the server is closed
-     */
-    stop(): Promise<void>;
-}
-
-/**
- * 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;
-}
-
-/**
- * Startup phases for coordinated initialization
- *
- * Defines the order in which different components are initialized during bot startup.
- */
-declare enum StartupPhase {
-    /** Validate environment variables and config files */
-    Validation = 1,
-    /** Discover plugin constructors via decorators or registry */
-    Discovery = 2,
-    /** Register plugin metadata and declared dependencies */
-    Registration = 3,
-    /** Inject and validate plugin-specific configuration */
-    Configuration = 4,
-    /** Instantiate plugin classes with Core and arguments */
-    Instantiation = 5,
-    /** Activate plugins by calling their init/setup effects */
-    Activation = 6,
-    /** Mark seedcord as ready and start handling interactions */
-    Ready = 7
-}
-type CoordinatedStartupEventKey = PhaseEvents<'startup', UnionToTuple<StartupPhase>>;
-/**
- * Manages bot startup lifecycle with ordered phases
- *
- * Coordinates initialization of all bot components in a predictable sequence.
- * Tasks are executed within their designated phases to ensure proper dependency order.
- */
-declare class CoordinatedStartup extends CoordinatedLifecycle<StartupPhase> {
-    private isStartingUp;
-    private hasStarted;
-    constructor();
-    /**
-     * Adds a task to a specific startup phase with timeout.
-     *
-     * @param phase - The startup phase from {@link StartupPhase}
-     * @param taskName - Unique identifier for the task
-     * @param task - Async function to execute
-     * @param timeoutMs - Task timeout in milliseconds (default: 10000)
-     */
-    addTask(phase: StartupPhase, taskName: string, task: () => Promise<void>, timeoutMs?: number): void;
-    protected canAddTask(): boolean;
-    protected canRemoveTask(): boolean;
-    protected getTaskType(): string;
-    protected executeTasksInPhase(phase: StartupPhase, tasks: LifecycleTask[]): Promise<PromiseSettledResult<void>[]>;
-    /**
-     * Executes the coordinated startup sequence.
-     *
-     * Runs all registered tasks across startup phases in the correct order.
-     * Each phase completes before the next phase begins. Tasks within a phase
-     * are executed sequentially to maintain predictable initialization.
-     *
-     * @returns Promise that resolves when startup is complete
-     * @throws An {@link Error} If startup fails or is called multiple times
-     * @example
-     * ```typescript
-     * const startup = new CoordinatedStartup();
-     * startup.addTask(StartupPhase.Services, 'database', () => db.connect(), 10000);
-     * await startup.run();
-     * ```
-     */
-    run(): Promise<void>;
-    /**
-     * Subscribe to startup events
-     */
-    on(event: CoordinatedStartupEventKey, listener: (...args: unknown[]) => void): void;
-    /**
-     * Unsubscribe from startup events
-     */
-    off(event: CoordinatedStartupEventKey, listener: (...args: unknown[]) => void): void;
-    /**
-     * Check if startup has completed
-     */
-    get isReady(): boolean;
-    /**
-     * Check if startup is currently running
-     */
-    get isRunning(): boolean;
-}
-
-export { CooldownManager, type CooldownOptions, CoordinatedLifecycle, CoordinatedShutdown, CoordinatedStartup, HealthCheck, Logger, ShutdownPhase, StartupPhase };