@seedcord/services 0.6.0 → 0.7.0-next.0

package/README.md

@@ -10,4 +10,4 @@ _This repository is a work in progress._
 - Till a major v1.0.0 release for seedcord, expect breaking changes in minor versions.
 - Documentation will come soon as well!
 
-I'm planning to release the first major version by the end of 2025, or Jan 2026. But till then, if you'd like to try using it, you can check out the code in `packages/mock`
+I'm planning to release the first major version by Q1 2026. But till then, if you'd like to try using it, you can check out the code in `mock`

package/dist/SeedcordError-BuWVIe6m.d.mts

@@ -0,0 +1,302 @@
+//#region src/Errors/ErrorCodes.d.ts
+/**
+ * All Seedcord error codes.
+ */
+declare enum SeedcordErrorCode {
+  /** DISCORD_BOT_TOKEN is not present in the environment. */
+  ConfigMissingDiscordToken = 1001,
+  /** DISCORD_BOT_TOKEN is present but fails validation. */
+  ConfigIncorrectDiscordToken = 1004,
+  /** UNKNOWN_EXCEPTION_WEBHOOK_URL is missing when configuring the reporter. */
+  ConfigUnknownExceptionWebhookMissing = 1002,
+  /** UNKNOWN_EXCEPTION_WEBHOOK_URL is present but fails URL validation. */
+  ConfigUnknownExceptionWebhookInvalid = 1003,
+  /** Attempted to add lifecycle tasks after startup already completed. */
+  LifecycleAddAfterCompletion = 1101,
+  /** Attempted to add lifecycle tasks while startup is still running. */
+  LifecycleAddDuringRun = 1102,
+  /** Attempted to remove lifecycle tasks while startup is still running. */
+  LifecycleRemoveDuringRun = 1103,
+  /** Provided lifecycle phase identifier is not recognized. */
+  LifecycleUnknownPhase = 1104,
+  /** Startup phase completed with one or more task failures. */
+  LifecyclePhaseFailures = 1105,
+  /** A lifecycle task exceeded its configured timeout. */
+  LifecycleTaskTimeout = 1106,
+  /** Multiple Seedcord instances were created simultaneously. */
+  CoreSingletonViolation = 1201,
+  /** Plugins cannot be mutated after the core has finished initializing. */
+  CorePluginAfterInit = 1202,
+  /** A plugin tried to register with a key that already exists. */
+  CorePluginKeyExists = 1203,
+  /** Bot role lookup failed within the provided guild. */
+  CoreBotRoleMissing = 1204,
+  /** A bot controller was constructed without its required handlers directory. */
+  CoreControllerPathMissing = 1205,
+  /** Interaction middleware decorated with disallowed event filters. */
+  DecoratorInteractionEventFilter = 1301,
+  /** A decorator could not find the original method being decorated. */
+  DecoratorMethodNotFound = 1302,
+  /** A command decorator attempted to re-register an existing command scope. */
+  DecoratorCommandAlreadyRegistered = 1303,
+  /** A global command decorator specified guild IDs, which is not allowed. */
+  DecoratorCommandGlobalWithGuilds = 1304,
+  /** A guild command decorator omitted the required guild ID list. */
+  DecoratorCommandGuildWithoutGuilds = 1305,
+  /** Middleware priority provided by the decorator was not a finite number. */
+  DecoratorInvalidMiddlewarePriority = 1306,
+  /** buildSlashRoute received an invalid argument. */
+  UtilInvalidSlashRouteArgument = 1403,
+  /** StrictEventEmitter.waitFor was aborted via its AbortSignal. */
+  EventEmitterWaitForAborted = 1501,
+  /** StrictEventEmitter.waitFor exceeded its configured timeout. */
+  EventEmitterWaitForTimeout = 1502,
+  /** Mongo service class is missing the `@RegisterMongoService` decorator. */
+  PluginMongoServiceDecoratorMissing = 2101,
+  /** Mongo model class is missing the `@RegisterMongoModel` decorator. */
+  PluginMongoModelDecoratorMissing = 2102,
+  /** Mongo client failed to establish a connection. */
+  PluginMongoConnectionFailed = 2103,
+  /** Mongo client failed to disconnect cleanly during shutdown. */
+  PluginMongoDisconnectFailed = 2104,
+  /** Mongo `services` was accessed before the plugin finished initializing. */
+  PluginMongoServicesNotReady = 2105,
+  /** KPG service class is missing the `@RegisterKpgService` decorator. */
+  PluginKpgServiceDecoratorMissing = 2201,
+  /** KPG service class is missing its table metadata. */
+  PluginKpgServiceTableMissing = 2202,
+  /** Migration manager received an invalid step count. */
+  PluginKpgInvalidStepCount = 2203,
+  /** Migration direction was not recognized. */
+  PluginKpgUnknownDirection = 2204,
+  /** Provided migrations path could not be resolved. */
+  PluginKpgUnresolvedMigrationsPath = 2205,
+  /** No migration files were found for execution. */
+  PluginKpgNoMigrationFiles = 2206,
+  /** A migration module failed to export the expected functions. */
+  PluginKpgInvalidMigrationModule = 2207,
+  /** An arbitrary (non-Error) failure was reported by a migration. */
+  PluginKpgNonErrorFailure = 2208,
+  /** Postgres pool failed to close cleanly during shutdown. */
+  PluginKpgDisconnectFailed = 2209,
+  /** KPG `services` was accessed before the plugin finished initializing. */
+  PluginKpgServicesNotReady = 2210,
+  /** Config file default export was not an object. */
+  CliConfigInvalidExport = 3101,
+  /** Config is missing the required instance string. */
+  CliConfigMissingInstance = 3102,
+  /** Config root was provided but not a string. */
+  CliConfigInvalidRoot = 3103,
+  /** Unable to locate a Seedcord config file. */
+  CliConfigNotFound = 3104,
+  /** CLI entry file does not exist. */
+  CliEntryNotFound = 3105,
+  /** tsx failed to import the provided entry file. */
+  CliTsxImportFailed = 3106,
+  /** Native import and jiti fallback both failed. */
+  CliImportFailed = 3107,
+  /** Seedcord instance export is missing a start() method. */
+  CliInstanceInvalid = 3108,
+  /** Seedcord instance threw during startup. */
+  CliStartFailed = 3109,
+  /** Config is missing the required entry string. */
+  CliConfigMissingEntry = 3110,
+  /** Config build options must be an object when provided. */
+  CliConfigInvalidBuild = 3111,
+  /** Config build outDir must be a string when provided. */
+  CliConfigInvalidBuildOutDir = 3112,
+  /** Config build tsconfig must be a string when provided. */
+  CliConfigInvalidBuildTsconfig = 3113,
+  /** Config build bootstrap must be a string when provided. */
+  CliConfigInvalidBuildBootstrap = 3114,
+  /** Entry file must be inside the configured root directory. */
+  CliConfigEntryOutsideRoot = 3115,
+  /** Unable to locate a TypeScript config file for builds. */
+  CliBuildTsconfigNotFound = 3116,
+  /** TypeScript reported diagnostics during emit. */
+  CliBuildFailed = 3117,
+  /** Unable to write the generated bootstrap file. */
+  CliBootstrapWriteFailed = 3118,
+  /** Config tsconfig must be a string when provided. */
+  CliConfigInvalidTsconfig = 3119,
+  /** Config hmr options must be an object when provided. */
+  CliConfigInvalidHmr = 3120,
+  /** Config hmr restart patterns must be an array of strings when provided. */
+  CliConfigInvalidHmrRestart = 3121
+}
+//#endregion
+//#region src/Errors/ErrorMessages.d.ts
+/**
+ * Mapping of Seedcord error codes to their corresponding message formatters.
+ *
+ * @internal
+ */
+declare const messages: {
+  1001: () => string;
+  1004: () => string;
+  1002: () => string;
+  1003: () => string;
+  1101: () => string;
+  1102: () => string;
+  1103: () => string;
+  1104: (phase: unknown) => string;
+  1105: (phase: string, failures: number) => string;
+  1106: (taskName: string, timeout: number) => string;
+  1201: () => string;
+  1202: () => string;
+  1203: (key: string) => string;
+  1204: (guildId?: string) => string;
+  1205: (controllerName: string, pathKind: string) => string;
+  1301: () => string;
+  1302: () => string;
+  1303: (commandName: string, existingScope: string, requestedScope: string) => string;
+  1304: () => string;
+  1305: () => string;
+  1306: () => string;
+  1403: () => string;
+  1501: () => string;
+  1502: (timeout: number) => string;
+  2101: (className: string) => string;
+  2102: (className: string) => string;
+  2103: (databaseName?: string) => string;
+  2104: () => string;
+  2105: () => string;
+  2201: (className: string) => string;
+  2202: (className: string) => string;
+  2203: () => string;
+  2204: (direction: unknown) => string;
+  2205: (label: string) => string;
+  2206: () => string;
+  2207: (filePath: string) => string;
+  2208: (message: string) => string;
+  2209: () => string;
+  2210: () => string;
+  3101: () => string;
+  3102: () => string;
+  3103: () => string;
+  3104: (baseDir: string, candidates: readonly string[]) => string;
+  3110: () => string;
+  3111: () => string;
+  3112: () => string;
+  3113: () => string;
+  3114: () => string;
+  3115: (entryPath: string, root: string) => string;
+  3105: (entryPath: string) => string;
+  3106: (entryPath: string, reason: string) => string;
+  3107: (entryPath: string, nativeReason: string, fallbackReason: string) => string;
+  3108: () => string;
+  3109: (instancePath: string, reason: string) => string;
+  3116: (hint: string) => string;
+  3117: (diagnostics: string) => string;
+  3118: (targetPath: string, reason: string) => string;
+  3119: () => string;
+  3120: () => string;
+  3121: () => string;
+};
+/**
+ * Argument types for Seedcord error messages.
+ *
+ * @internal
+ */
+type SeedcordErrorArguments<Code extends SeedcordErrorCode> = Parameters<(typeof messages)[Code]>;
+//#endregion
+//#region src/Errors/SeedcordError.d.ts
+/**
+ * String literal type for Seedcord error identifiers.
+ *
+ * @internal
+ */
+type SeedcordErrorIdentifier = keyof typeof SeedcordErrorCode;
+/**
+ * Options for Seedcord errors.
+ *
+ * @internal
+ */
+interface SeedcordErrorOptions extends ErrorOptions {}
+type SeedcordErrorCtorRest<Code extends SeedcordErrorCode> = SeedcordErrorArguments<Code> extends [] ? [options?: SeedcordErrorOptions] : [args: SeedcordErrorArguments<Code>, options?: SeedcordErrorOptions];
+/**
+ * String literal type for Seedcord error class names.
+ *
+ * @internal
+ */
+type SeedcordErrorTypeString = `Seedcord${'Error' | 'TypeError' | 'RangeError'}`;
+/**
+ * Base interface for Seedcord error instances.
+ *
+ * @internal
+ */
+interface BaseSeedcordError {
+  readonly code: SeedcordErrorCode;
+  readonly identifier: SeedcordErrorIdentifier;
+  readonly type: SeedcordErrorTypeString;
+}
+/**
+ * Base class for Seedcord errors.
+ *
+ * @internal
+ */
+declare class SeedcordError<Code extends SeedcordErrorCode = SeedcordErrorCode> extends Error implements BaseSeedcordError {
+  readonly code: Code;
+  readonly identifier: SeedcordErrorIdentifier;
+  readonly type = "SeedcordError";
+  constructor(code: Code, ...rest: SeedcordErrorCtorRest<Code>);
+}
+/**
+ * TypeError class for Seedcord errors.
+ *
+ * @internal
+ */
+declare class SeedcordTypeError<Code extends SeedcordErrorCode = SeedcordErrorCode> extends TypeError implements BaseSeedcordError {
+  readonly code: Code;
+  readonly identifier: SeedcordErrorIdentifier;
+  readonly type = "SeedcordTypeError";
+  constructor(code: Code, ...rest: SeedcordErrorCtorRest<Code>);
+}
+/**
+ * RangeError class for Seedcord errors.
+ *
+ * @internal
+ */
+declare class SeedcordRangeError<Code extends SeedcordErrorCode = SeedcordErrorCode> extends RangeError implements BaseSeedcordError {
+  readonly code: Code;
+  readonly identifier: SeedcordErrorIdentifier;
+  readonly type = "SeedcordRangeError";
+  constructor(code: Code, ...rest: SeedcordErrorCtorRest<Code>);
+}
+/**
+ * Variant type for Seedcord error classes.
+ *
+ * @internal
+ */
+type SeedcordErrorVariant<Type extends SeedcordErrorTypeString, Code extends SeedcordErrorCode> = Type extends 'SeedcordError' ? SeedcordError<Code> : Type extends 'SeedcordTypeError' ? SeedcordTypeError<Code> : SeedcordRangeError<Code>;
+/**
+ * Union type of all Seedcord error variants for a specific error code.
+ *
+ * @internal
+ */
+type AnySeedcordErrorForCode<Code extends SeedcordErrorCode> = { [Variant in SeedcordErrorTypeString]: SeedcordErrorVariant<Variant, Code> }[SeedcordErrorTypeString];
+/**
+ * Union type of all Seedcord errors filtered by error class.
+ *
+ * @internal
+ */
+type ErrorTypeFilter<Type extends SeedcordErrorTypeString | undefined> = Type extends SeedcordErrorTypeString ? { [Code in SeedcordErrorCode]: SeedcordErrorVariant<Type, Code> }[SeedcordErrorCode] : AnySeedcordErrorForCode<SeedcordErrorCode>;
+/**
+ * Union type of all Seedcord errors filtered by error class and error code.
+ *
+ * @internal
+ */
+type ErrorCodeFilter<Type extends SeedcordErrorTypeString | undefined, Code extends SeedcordErrorCode | undefined> = Code extends SeedcordErrorCode ? Type extends SeedcordErrorTypeString ? SeedcordErrorVariant<Type, Code> : AnySeedcordErrorForCode<Code> : ErrorTypeFilter<Type>;
+/**
+ * Determines whether an unknown value is a Seedcord error, with optional narrowing by class and error code.
+ *
+ * @param error - The value to inspect.
+ * @param type - Optional error class discriminator (Error, TypeError, or RangeError).
+ * @param code - Optional {@link SeedcordErrorCode} discriminator to narrow by code.
+ * @typeParam Type - What kind of {@link SeedcordErrorTypeString} to filter by.
+ * @typeParam Code - The specific {@link SeedcordErrorCode} to filter by.
+ */
+declare function isSeedcordError<Type extends SeedcordErrorTypeString | undefined, Code extends SeedcordErrorCode | undefined>(error: unknown, type?: Type, code?: Code): error is ErrorCodeFilter<Type, Code>;
+//#endregion
+export { SeedcordTypeError as a, SeedcordRangeError as i, SeedcordError as n, isSeedcordError as o, SeedcordErrorTypeString as r, SeedcordErrorCode as s, BaseSeedcordError as t };
+//# sourceMappingURL=SeedcordError-BuWVIe6m.d.mts.map