@seedcord/core 0.1.0-next.5 → 0.1.0-next.7

package/dist/Plugin-Cgp1a0uQ.cjs

@@ -0,0 +1,123 @@
+const require_phases = require('./phases-C_BGNyVo.cjs');
+const require_devChannel = require('./devChannel-CoCmAVDx.cjs');
+let _seedcord_errors = require("@seedcord/errors");
+let _seedcord_errors_internal = require("@seedcord/errors/internal");
+let _seedcord_logger = require("@seedcord/logger");
+
+//#region src/plugin/context.ts
+/** @internal unset until attach installs the built ctx */
+const pluginContextSlot = Symbol("seedcord.plugin.ctx");
+/** @internal */
+function readPluginContext(holder) {
+	const ctx = holder[pluginContextSlot];
+	if (!ctx) throw new _seedcord_errors_internal.SeedcordError(_seedcord_errors.SeedcordErrorCode.PluginContextBeforeInit, [holder.constructor.name]);
+	return ctx;
+}
+/** @internal */
+function finalizePluginContext(holder, ctx) {
+	holder[pluginContextSlot] = ctx;
+}
+
+//#endregion
+//#region src/plugin/lifecycle.ts
+const DEFAULT_INIT_TIMEOUT_MS = 15e3;
+const DEFAULT_READY_TIMEOUT_MS = 15e3;
+const DEFAULT_DISPOSE_TIMEOUT_MS = 1e4;
+function timeoutOf(field, declared, fallback, pluginName) {
+	if (declared === void 0) return fallback;
+	if (!Number.isFinite(declared) || declared <= 0) throw new _seedcord_errors_internal.SeedcordError(_seedcord_errors.SeedcordErrorCode.PluginOptionsRejected, [pluginName, `lifecycle ${field}.timeout must be a positive number of milliseconds`]);
+	return declared;
+}
+/** @internal */
+function resolveLifecycleSpec(spec, pluginName) {
+	return {
+		init: {
+			phase: spec?.init?.phase ?? 1,
+			timeout: timeoutOf("init", spec?.init?.timeout, DEFAULT_INIT_TIMEOUT_MS, pluginName)
+		},
+		ready: { timeout: timeoutOf("ready", spec?.ready?.timeout, DEFAULT_READY_TIMEOUT_MS, pluginName) },
+		dispose: {
+			phase: spec?.dispose?.phase ?? 3,
+			timeout: timeoutOf("dispose", spec?.dispose?.timeout, DEFAULT_DISPOSE_TIMEOUT_MS, pluginName)
+		}
+	};
+}
+
+//#endregion
+//#region src/plugin/Plugin.ts
+/** @internal */
+const resolvedSpecSlot = Symbol("seedcord.plugin.spec");
+/**
+* Base class for Seedcord plugins. A subclass declares its options as the `Opts` type argument,
+* implements `init()`, and reads the framework surface through `this.ctx`.
+*
+* @typeParam Opts - The plugin's declared {@link PluginOptions}.
+* @typeParam TCore - The host type `this.core` resolves to. Each transport binds it to its own `Core`.
+*/
+var Plugin = class {
+	host;
+	/** @internal */
+	[resolvedSpecSlot];
+	/** @internal */
+	[pluginContextSlot];
+	/** Logs under the plugin's class name, on the channel its attach key names. */
+	logger;
+	constructor(host, spec) {
+		this.host = host;
+		this.logger = new _seedcord_logger.Logger(this.constructor.name);
+		this[resolvedSpecSlot] = resolveLifecycleSpec(spec, this.constructor.name);
+	}
+	/** The host, typed to the transport whose `Plugin` base this class extends. */
+	get core() {
+		return this.host;
+	}
+	/** The framework surface, available from `init()` onward. Throws if read before `attach` finalizes it. */
+	get ctx() {
+		return readPluginContext(this);
+	}
+	/**
+	* Rejects the plugin's constructor options with a reason. Throws a `SeedcordError` naming the
+	* plugin class and the reason.
+	*
+	* @param reason - Why the options are invalid.
+	*/
+	rejectOptions(reason) {
+		throw new _seedcord_errors_internal.SeedcordError(_seedcord_errors.SeedcordErrorCode.PluginOptionsRejected, [this.constructor.name, reason]);
+	}
+	/** Override to reload plugin state on an HMR update. */
+	onHmr(_event) {
+		return Promise.resolve();
+	}
+	/**
+	* Registers critical file patterns that should trigger a full restart when changed in Dev HMR.
+	* @param patterns - Glob patterns relative to the project root
+	*/
+	registerCriticalFiles(patterns) {
+		require_devChannel.getDevChannel()?.send("seedcord:register-critical-files", { patterns });
+	}
+};
+/** @internal */
+function resolvedLifecycleSpecOf(plugin) {
+	return plugin[resolvedSpecSlot];
+}
+
+//#endregion
+Object.defineProperty(exports, 'Plugin', {
+  enumerable: true,
+  get: function () {
+    return Plugin;
+  }
+});
+Object.defineProperty(exports, 'finalizePluginContext', {
+  enumerable: true,
+  get: function () {
+    return finalizePluginContext;
+  }
+});
+Object.defineProperty(exports, 'resolvedLifecycleSpecOf', {
+  enumerable: true,
+  get: function () {
+    return resolvedLifecycleSpecOf;
+  }
+});
+//# sourceMappingURL=Plugin-Cgp1a0uQ.cjs.map

package/dist/Plugin-Cgp1a0uQ.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Plugin-Cgp1a0uQ.cjs","names":["SeedcordError","SeedcordErrorCode","SeedcordError","SeedcordErrorCode","Logger","SeedcordError","SeedcordErrorCode"],"sources":["../src/plugin/context.ts","../src/plugin/lifecycle.ts","../src/plugin/Plugin.ts"],"sourcesContent":["import { SeedcordErrorCode } from '@seedcord/errors';\nimport { SeedcordError } from '@seedcord/errors/internal';\n\nimport type { PluginNeed } from './options';\nimport type { Config, Store } from '@seedcord/types';\n\n/**\n * The type each `ctx` capability resolves to. Empty in core, each transport augments it through\n * declaration merging.\n *\n * @example\n * ```typescript\n * declare module '@seedcord/core' {\n *   interface PluginCapabilityTypes {\n *     client: Client;\n *     rest: REST;\n *   }\n * }\n * ```\n */\nexport interface PluginCapabilityTypes {}\n\ntype CapabilityType<Key extends PluginNeed, Fallback> = Key extends keyof PluginCapabilityTypes\n    ? PluginCapabilityTypes[Key]\n    : Fallback;\n\ntype CapabilityValue<TNeeds extends PluginNeed, Key extends PluginNeed, Value> = Key extends TNeeds ? Value : never;\n\n/**\n * The framework surface a plugin reads through `this.ctx`, typed by its declared `needs`.\n *\n * Always available: `config` and `store`. Each capability resolves to its value only when\n * the plugin declared that key, otherwise `never`. The logger comes from `this.logger`.\n *\n * @typeParam TNeeds - The plugin's declared `needs` union.\n */\nexport interface PluginContext<TNeeds extends PluginNeed = never> {\n    readonly config: Config;\n    readonly store: Store<'charge'>;\n    readonly client: CapabilityValue<TNeeds, 'client', CapabilityType<'client', unknown>>;\n    readonly token: CapabilityValue<TNeeds, 'token', string>;\n    /**\n     * The REST client. On http, the client has no token until the Ready phase, so a call from\n     * `init()` sends without a token and returns a 401.\n     */\n    readonly rest: CapabilityValue<TNeeds, 'rest', CapabilityType<'rest', unknown>>;\n}\n\n// the conditional capability types make PluginContext<A> and PluginContext<B> mutually unassignable\n/** @internal */\nexport type StoredPluginContext = Pick<PluginContext, 'config' | 'store'> & {\n    client?: unknown;\n    token?: string | undefined;\n    rest?: unknown;\n};\n\n/**\n * The capability arms a transport supplies from its own Bot/client. `attach` merges them into each\n * plugin's ctx.\n *\n * @internal\n */\nexport interface PluginCapabilities {\n    readonly client?: unknown;\n    readonly token?: string | undefined;\n    readonly rest?: unknown;\n}\n\n/** @internal unset until attach installs the built ctx */\nexport const pluginContextSlot = Symbol('seedcord.plugin.ctx');\n\ninterface ContextHolder {\n    [pluginContextSlot]?: StoredPluginContext;\n}\n\n/** @internal */\nexport function readPluginContext<TNeeds extends PluginNeed>(holder: ContextHolder): PluginContext<TNeeds> {\n    const ctx = holder[pluginContextSlot];\n    if (!ctx) throw new SeedcordError(SeedcordErrorCode.PluginContextBeforeInit, [holder.constructor.name]);\n    // safe, finalizePluginContext set the ctx typed for this plugin's declared needs\n    return ctx as PluginContext<TNeeds>;\n}\n\n/** @internal */\nexport function finalizePluginContext<TNeeds extends PluginNeed>(\n    holder: ContextHolder,\n    ctx: PluginContext<TNeeds>\n): void {\n    holder[pluginContextSlot] = ctx;\n}\n","import { SeedcordErrorCode } from '@seedcord/errors';\nimport { SeedcordError } from '@seedcord/errors/internal';\n\nimport { ShutdownPhase, StartupPhase } from '@src/lifecycle/phases';\n\n/**\n * The lifecycle a plugin declares through `super(host, spec)`. Unset fields resolve to the base\n * defaults. `ready` runs at a fixed `StartupPhase.Ready`, so it takes only a timeout.\n */\nexport interface PluginLifecycleSpec {\n    init?: { phase?: StartupPhase; timeout?: number };\n    ready?: { timeout?: number };\n    dispose?: { phase?: ShutdownPhase; timeout?: number };\n}\n\n/** @internal */\nexport interface ResolvedPluginLifecycleSpec {\n    readonly init: { readonly phase: StartupPhase; readonly timeout: number };\n    readonly ready: { readonly timeout: number };\n    readonly dispose: { readonly phase: ShutdownPhase; readonly timeout: number };\n}\n\nconst DEFAULT_INIT_TIMEOUT_MS = 15_000;\nconst DEFAULT_READY_TIMEOUT_MS = 15_000;\nconst DEFAULT_DISPOSE_TIMEOUT_MS = 10_000;\n\nfunction timeoutOf(\n    field: 'init' | 'ready' | 'dispose',\n    declared: number | undefined,\n    fallback: number,\n    pluginName: string\n): number {\n    if (declared === undefined) return fallback;\n    if (!Number.isFinite(declared) || declared <= 0) {\n        throw new SeedcordError(SeedcordErrorCode.PluginOptionsRejected, [\n            pluginName,\n            `lifecycle ${field}.timeout must be a positive number of milliseconds`\n        ]);\n    }\n    return declared;\n}\n\n/** @internal */\nexport function resolveLifecycleSpec(\n    spec: PluginLifecycleSpec | undefined,\n    pluginName: string\n): ResolvedPluginLifecycleSpec {\n    return {\n        init: {\n            phase: spec?.init?.phase ?? StartupPhase.Configuration,\n            timeout: timeoutOf('init', spec?.init?.timeout, DEFAULT_INIT_TIMEOUT_MS, pluginName)\n        },\n        ready: {\n            timeout: timeoutOf('ready', spec?.ready?.timeout, DEFAULT_READY_TIMEOUT_MS, pluginName)\n        },\n        dispose: {\n            phase: spec?.dispose?.phase ?? ShutdownPhase.Disconnect,\n            timeout: timeoutOf('dispose', spec?.dispose?.timeout, DEFAULT_DISPOSE_TIMEOUT_MS, pluginName)\n        }\n    };\n}\n","import { SeedcordErrorCode } from '@seedcord/errors';\nimport { SeedcordError } from '@seedcord/errors/internal';\nimport { Logger } from '@seedcord/logger';\n\nimport { getDevChannel } from '@hmr/devChannel';\n\nimport { pluginContextSlot, readPluginContext } from './context';\nimport { resolveLifecycleSpec } from './lifecycle';\n\nimport type { PluginContext, StoredPluginContext } from './context';\nimport type { ResolvedPluginLifecycleSpec, PluginLifecycleSpec } from './lifecycle';\nimport type { TransportOf, NeedsOf, PluginOptions, RuntimeOf } from './options';\nimport type { CoreBase } from '@interfaces/CoreBase';\nimport type { Tail, HmrAware, HmrUpdateEvent } from '@seedcord/types';\n\nexport interface Initializeable {\n    init(): Promise<void>;\n}\n\n/** @internal */\nconst resolvedSpecSlot = Symbol('seedcord.plugin.spec');\n\n/**\n * Base class for Seedcord plugins. A subclass declares its options as the `Opts` type argument,\n * implements `init()`, and reads the framework surface through `this.ctx`.\n *\n * @typeParam Opts - The plugin's declared {@link PluginOptions}.\n * @typeParam TCore - The host type `this.core` resolves to. Each transport binds it to its own `Core`.\n */\nexport abstract class Plugin<Opts extends PluginOptions = {}, TCore extends CoreBase = CoreBase>\n    implements Initializeable, HmrAware\n{\n    /** @internal phantom, never set at runtime */\n    declare readonly __transport?: TransportOf<Opts>;\n    /** @internal phantom, never set at runtime */\n    declare readonly __runtime?: RuntimeOf<Opts>;\n\n    /** @internal */\n    readonly [resolvedSpecSlot]: ResolvedPluginLifecycleSpec;\n    /** @internal */\n    [pluginContextSlot]?: StoredPluginContext;\n\n    /** Logs under the plugin's class name, on the channel its attach key names. */\n    public readonly logger: Logger;\n\n    // CoreBase here keeps the augmented Core out of ConstructorParameters, which attach reads\n    constructor(\n        private readonly host: CoreBase,\n        spec?: PluginLifecycleSpec\n    ) {\n        this.logger = new Logger(this.constructor.name);\n        this[resolvedSpecSlot] = resolveLifecycleSpec(spec, this.constructor.name);\n    }\n\n    /** The host, typed to the transport whose `Plugin` base this class extends. */\n    protected get core(): TCore {\n        // justified: each transport binds TCore to the Core its own host satisfies\n        return this.host as TCore;\n    }\n\n    /** The framework surface, available from `init()` onward. Throws if read before `attach` finalizes it. */\n    protected get ctx(): PluginContext<NeedsOf<Opts>> {\n        return readPluginContext<NeedsOf<Opts>>(this);\n    }\n\n    abstract init(): Promise<void>;\n\n    /**\n     * Runs in the startup Ready phase, after `init()`. The gateway client is logged in by this phase,\n     * and the http host runs its server-bind and health tasks in the same phase.\n     */\n    ready?(): Promise<void>;\n\n    /** Runs during teardown, only when `init()` resolved. */\n    dispose?(): Promise<void>;\n\n    /**\n     * Rejects the plugin's constructor options with a reason. Throws a `SeedcordError` naming the\n     * plugin class and the reason.\n     *\n     * @param reason - Why the options are invalid.\n     */\n    protected rejectOptions(reason: string): never {\n        throw new SeedcordError(SeedcordErrorCode.PluginOptionsRejected, [this.constructor.name, reason]);\n    }\n\n    /** Override to reload plugin state on an HMR update. */\n    public onHmr(_event: HmrUpdateEvent): Promise<void> {\n        return Promise.resolve();\n    }\n\n    /**\n     * Registers critical file patterns that should trigger a full restart when changed in Dev HMR.\n     * @param patterns - Glob patterns relative to the project root\n     */\n    protected registerCriticalFiles(patterns: string[]): void {\n        getDevChannel()?.send('seedcord:register-critical-files', { patterns });\n    }\n}\n\n/** @internal */\nexport function resolvedLifecycleSpecOf(plugin: PluginLike): ResolvedPluginLifecycleSpec {\n    return plugin[resolvedSpecSlot];\n}\n\nexport type { PluginContext, PluginCapabilityTypes } from './context';\nexport type { PluginLifecycleSpec } from './lifecycle';\nexport type { PluginOptions } from './options';\n\n// a bound of Plugin<{}> rejects every plugin that declares an option, since Plugin<A> and Plugin<B>\n// are mutually unassignable. every member here must stay Opts-independent.\n/** @internal */\nexport type PluginLike = Pick<\n    Plugin,\n    'init' | 'ready' | 'dispose' | 'logger' | 'onHmr' | typeof resolvedSpecSlot | typeof pluginContextSlot\n>;\n\n// a `CoreBase` first parameter rejects a narrowing ctor on its own, and it also collapses\n// `InstanceType<Ctor>` to `PluginLike` at every attach call. CoreParamAssert checks it instead.\n/** @internal */\nexport type PluginCtor<TPlugin extends PluginLike = PluginLike> = new (...args: any[]) => TPlugin;\n\n/** @internal */\nexport type PluginArgs<Ctor extends PluginCtor> = Tail<ConstructorParameters<Ctor>>;\n\ntype CoreParamTooNarrow = Record<\n    'this plugin constructor must take CoreBase as its first parameter and read the transport Core off this.core',\n    never\n>;\n\n// a narrowed first parameter fails `CoreBase extends Param`\n/** @internal */\nexport type CoreParamAssert<Ctor extends PluginCtor> = CoreBase extends ConstructorParameters<Ctor>[0]\n    ? unknown\n    : CoreParamTooNarrow;\n\nexport { finalizePluginContext } from './context';\n"],"mappings":";;;;;;;;AAqEA,MAAa,oBAAoB,OAAO,qBAAqB;;AAO7D,SAAgB,kBAA6C,QAA8C;CACvG,MAAM,MAAM,OAAO;CACnB,IAAI,CAAC,KAAK,MAAM,IAAIA,wCAAcC,mCAAkB,yBAAyB,CAAC,OAAO,YAAY,IAAI,CAAC;CAEtG,OAAO;AACX;;AAGA,SAAgB,sBACZ,QACA,KACI;CACJ,OAAO,qBAAqB;AAChC;;;;ACnEA,MAAM,0BAA0B;AAChC,MAAM,2BAA2B;AACjC,MAAM,6BAA6B;AAEnC,SAAS,UACL,OACA,UACA,UACA,YACM;CACN,IAAI,aAAa,QAAW,OAAO;CACnC,IAAI,CAAC,OAAO,SAAS,QAAQ,KAAK,YAAY,GAC1C,MAAM,IAAIC,wCAAcC,mCAAkB,uBAAuB,CAC7D,YACA,aAAa,MAAM,mDACvB,CAAC;CAEL,OAAO;AACX;;AAGA,SAAgB,qBACZ,MACA,YAC2B;CAC3B,OAAO;EACH,MAAM;GACF,OAAO,MAAM,MAAM;GACnB,SAAS,UAAU,QAAQ,MAAM,MAAM,SAAS,yBAAyB,UAAU;EACvF;EACA,OAAO,EACH,SAAS,UAAU,SAAS,MAAM,OAAO,SAAS,0BAA0B,UAAU,EAC1F;EACA,SAAS;GACL,OAAO,MAAM,SAAS;GACtB,SAAS,UAAU,WAAW,MAAM,SAAS,SAAS,4BAA4B,UAAU;EAChG;CACJ;AACJ;;;;;ACxCA,MAAM,mBAAmB,OAAO,sBAAsB;;;;;;;;AAStD,IAAsB,SAAtB,MAEA;CAgByB;;CATrB,CAAU;;CAEV,CAAC;;CAGD,AAAgB;CAGhB,YACI,AAAiB,MACjB,MACF;EAFmB;EAGjB,KAAK,SAAS,IAAIC,wBAAO,KAAK,YAAY,IAAI;EAC9C,KAAK,oBAAoB,qBAAqB,MAAM,KAAK,YAAY,IAAI;CAC7E;;CAGA,IAAc,OAAc;EAExB,OAAO,KAAK;CAChB;;CAGA,IAAc,MAAoC;EAC9C,OAAO,kBAAiC,IAAI;CAChD;;;;;;;CAmBA,AAAU,cAAc,QAAuB;EAC3C,MAAM,IAAIC,wCAAcC,mCAAkB,uBAAuB,CAAC,KAAK,YAAY,MAAM,MAAM,CAAC;CACpG;;CAGA,AAAO,MAAM,QAAuC;EAChD,OAAO,QAAQ,QAAQ;CAC3B;;;;;CAMA,AAAU,sBAAsB,UAA0B;EACtD,iCAAc,CAAC,EAAE,KAAK,oCAAoC,EAAE,SAAS,CAAC;CAC1E;AACJ;;AAGA,SAAgB,wBAAwB,QAAiD;CACrF,OAAO,OAAO;AAClB"}

package/dist/Plugin-j9GYdroS.mjs

@@ -0,0 +1,106 @@
+import { n as StartupPhase, t as ShutdownPhase } from "./phases-BfpAG6w3.mjs";
+import { t as getDevChannel } from "./devChannel-CQU7hq7Q.mjs";
+import { SeedcordErrorCode } from "@seedcord/errors";
+import { SeedcordError } from "@seedcord/errors/internal";
+import { Logger } from "@seedcord/logger";
+
+//#region src/plugin/context.ts
+/** @internal unset until attach installs the built ctx */
+const pluginContextSlot = Symbol("seedcord.plugin.ctx");
+/** @internal */
+function readPluginContext(holder) {
+	const ctx = holder[pluginContextSlot];
+	if (!ctx) throw new SeedcordError(SeedcordErrorCode.PluginContextBeforeInit, [holder.constructor.name]);
+	return ctx;
+}
+/** @internal */
+function finalizePluginContext(holder, ctx) {
+	holder[pluginContextSlot] = ctx;
+}
+
+//#endregion
+//#region src/plugin/lifecycle.ts
+const DEFAULT_INIT_TIMEOUT_MS = 15e3;
+const DEFAULT_READY_TIMEOUT_MS = 15e3;
+const DEFAULT_DISPOSE_TIMEOUT_MS = 1e4;
+function timeoutOf(field, declared, fallback, pluginName) {
+	if (declared === void 0) return fallback;
+	if (!Number.isFinite(declared) || declared <= 0) throw new SeedcordError(SeedcordErrorCode.PluginOptionsRejected, [pluginName, `lifecycle ${field}.timeout must be a positive number of milliseconds`]);
+	return declared;
+}
+/** @internal */
+function resolveLifecycleSpec(spec, pluginName) {
+	return {
+		init: {
+			phase: spec?.init?.phase ?? 1,
+			timeout: timeoutOf("init", spec?.init?.timeout, DEFAULT_INIT_TIMEOUT_MS, pluginName)
+		},
+		ready: { timeout: timeoutOf("ready", spec?.ready?.timeout, DEFAULT_READY_TIMEOUT_MS, pluginName) },
+		dispose: {
+			phase: spec?.dispose?.phase ?? 3,
+			timeout: timeoutOf("dispose", spec?.dispose?.timeout, DEFAULT_DISPOSE_TIMEOUT_MS, pluginName)
+		}
+	};
+}
+
+//#endregion
+//#region src/plugin/Plugin.ts
+/** @internal */
+const resolvedSpecSlot = Symbol("seedcord.plugin.spec");
+/**
+* Base class for Seedcord plugins. A subclass declares its options as the `Opts` type argument,
+* implements `init()`, and reads the framework surface through `this.ctx`.
+*
+* @typeParam Opts - The plugin's declared {@link PluginOptions}.
+* @typeParam TCore - The host type `this.core` resolves to. Each transport binds it to its own `Core`.
+*/
+var Plugin = class {
+	host;
+	/** @internal */
+	[resolvedSpecSlot];
+	/** @internal */
+	[pluginContextSlot];
+	/** Logs under the plugin's class name, on the channel its attach key names. */
+	logger;
+	constructor(host, spec) {
+		this.host = host;
+		this.logger = new Logger(this.constructor.name);
+		this[resolvedSpecSlot] = resolveLifecycleSpec(spec, this.constructor.name);
+	}
+	/** The host, typed to the transport whose `Plugin` base this class extends. */
+	get core() {
+		return this.host;
+	}
+	/** The framework surface, available from `init()` onward. Throws if read before `attach` finalizes it. */
+	get ctx() {
+		return readPluginContext(this);
+	}
+	/**
+	* Rejects the plugin's constructor options with a reason. Throws a `SeedcordError` naming the
+	* plugin class and the reason.
+	*
+	* @param reason - Why the options are invalid.
+	*/
+	rejectOptions(reason) {
+		throw new SeedcordError(SeedcordErrorCode.PluginOptionsRejected, [this.constructor.name, reason]);
+	}
+	/** Override to reload plugin state on an HMR update. */
+	onHmr(_event) {
+		return Promise.resolve();
+	}
+	/**
+	* Registers critical file patterns that should trigger a full restart when changed in Dev HMR.
+	* @param patterns - Glob patterns relative to the project root
+	*/
+	registerCriticalFiles(patterns) {
+		getDevChannel()?.send("seedcord:register-critical-files", { patterns });
+	}
+};
+/** @internal */
+function resolvedLifecycleSpecOf(plugin) {
+	return plugin[resolvedSpecSlot];
+}
+
+//#endregion
+export { resolvedLifecycleSpecOf as n, finalizePluginContext as r, Plugin as t };
+//# sourceMappingURL=Plugin-j9GYdroS.mjs.map

package/dist/Plugin-j9GYdroS.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Plugin-j9GYdroS.mjs","names":[],"sources":["../src/plugin/context.ts","../src/plugin/lifecycle.ts","../src/plugin/Plugin.ts"],"sourcesContent":["import { SeedcordErrorCode } from '@seedcord/errors';\nimport { SeedcordError } from '@seedcord/errors/internal';\n\nimport type { PluginNeed } from './options';\nimport type { Config, Store } from '@seedcord/types';\n\n/**\n * The type each `ctx` capability resolves to. Empty in core, each transport augments it through\n * declaration merging.\n *\n * @example\n * ```typescript\n * declare module '@seedcord/core' {\n *   interface PluginCapabilityTypes {\n *     client: Client;\n *     rest: REST;\n *   }\n * }\n * ```\n */\nexport interface PluginCapabilityTypes {}\n\ntype CapabilityType<Key extends PluginNeed, Fallback> = Key extends keyof PluginCapabilityTypes\n    ? PluginCapabilityTypes[Key]\n    : Fallback;\n\ntype CapabilityValue<TNeeds extends PluginNeed, Key extends PluginNeed, Value> = Key extends TNeeds ? Value : never;\n\n/**\n * The framework surface a plugin reads through `this.ctx`, typed by its declared `needs`.\n *\n * Always available: `config` and `store`. Each capability resolves to its value only when\n * the plugin declared that key, otherwise `never`. The logger comes from `this.logger`.\n *\n * @typeParam TNeeds - The plugin's declared `needs` union.\n */\nexport interface PluginContext<TNeeds extends PluginNeed = never> {\n    readonly config: Config;\n    readonly store: Store<'charge'>;\n    readonly client: CapabilityValue<TNeeds, 'client', CapabilityType<'client', unknown>>;\n    readonly token: CapabilityValue<TNeeds, 'token', string>;\n    /**\n     * The REST client. On http, the client has no token until the Ready phase, so a call from\n     * `init()` sends without a token and returns a 401.\n     */\n    readonly rest: CapabilityValue<TNeeds, 'rest', CapabilityType<'rest', unknown>>;\n}\n\n// the conditional capability types make PluginContext<A> and PluginContext<B> mutually unassignable\n/** @internal */\nexport type StoredPluginContext = Pick<PluginContext, 'config' | 'store'> & {\n    client?: unknown;\n    token?: string | undefined;\n    rest?: unknown;\n};\n\n/**\n * The capability arms a transport supplies from its own Bot/client. `attach` merges them into each\n * plugin's ctx.\n *\n * @internal\n */\nexport interface PluginCapabilities {\n    readonly client?: unknown;\n    readonly token?: string | undefined;\n    readonly rest?: unknown;\n}\n\n/** @internal unset until attach installs the built ctx */\nexport const pluginContextSlot = Symbol('seedcord.plugin.ctx');\n\ninterface ContextHolder {\n    [pluginContextSlot]?: StoredPluginContext;\n}\n\n/** @internal */\nexport function readPluginContext<TNeeds extends PluginNeed>(holder: ContextHolder): PluginContext<TNeeds> {\n    const ctx = holder[pluginContextSlot];\n    if (!ctx) throw new SeedcordError(SeedcordErrorCode.PluginContextBeforeInit, [holder.constructor.name]);\n    // safe, finalizePluginContext set the ctx typed for this plugin's declared needs\n    return ctx as PluginContext<TNeeds>;\n}\n\n/** @internal */\nexport function finalizePluginContext<TNeeds extends PluginNeed>(\n    holder: ContextHolder,\n    ctx: PluginContext<TNeeds>\n): void {\n    holder[pluginContextSlot] = ctx;\n}\n","import { SeedcordErrorCode } from '@seedcord/errors';\nimport { SeedcordError } from '@seedcord/errors/internal';\n\nimport { ShutdownPhase, StartupPhase } from '@src/lifecycle/phases';\n\n/**\n * The lifecycle a plugin declares through `super(host, spec)`. Unset fields resolve to the base\n * defaults. `ready` runs at a fixed `StartupPhase.Ready`, so it takes only a timeout.\n */\nexport interface PluginLifecycleSpec {\n    init?: { phase?: StartupPhase; timeout?: number };\n    ready?: { timeout?: number };\n    dispose?: { phase?: ShutdownPhase; timeout?: number };\n}\n\n/** @internal */\nexport interface ResolvedPluginLifecycleSpec {\n    readonly init: { readonly phase: StartupPhase; readonly timeout: number };\n    readonly ready: { readonly timeout: number };\n    readonly dispose: { readonly phase: ShutdownPhase; readonly timeout: number };\n}\n\nconst DEFAULT_INIT_TIMEOUT_MS = 15_000;\nconst DEFAULT_READY_TIMEOUT_MS = 15_000;\nconst DEFAULT_DISPOSE_TIMEOUT_MS = 10_000;\n\nfunction timeoutOf(\n    field: 'init' | 'ready' | 'dispose',\n    declared: number | undefined,\n    fallback: number,\n    pluginName: string\n): number {\n    if (declared === undefined) return fallback;\n    if (!Number.isFinite(declared) || declared <= 0) {\n        throw new SeedcordError(SeedcordErrorCode.PluginOptionsRejected, [\n            pluginName,\n            `lifecycle ${field}.timeout must be a positive number of milliseconds`\n        ]);\n    }\n    return declared;\n}\n\n/** @internal */\nexport function resolveLifecycleSpec(\n    spec: PluginLifecycleSpec | undefined,\n    pluginName: string\n): ResolvedPluginLifecycleSpec {\n    return {\n        init: {\n            phase: spec?.init?.phase ?? StartupPhase.Configuration,\n            timeout: timeoutOf('init', spec?.init?.timeout, DEFAULT_INIT_TIMEOUT_MS, pluginName)\n        },\n        ready: {\n            timeout: timeoutOf('ready', spec?.ready?.timeout, DEFAULT_READY_TIMEOUT_MS, pluginName)\n        },\n        dispose: {\n            phase: spec?.dispose?.phase ?? ShutdownPhase.Disconnect,\n            timeout: timeoutOf('dispose', spec?.dispose?.timeout, DEFAULT_DISPOSE_TIMEOUT_MS, pluginName)\n        }\n    };\n}\n","import { SeedcordErrorCode } from '@seedcord/errors';\nimport { SeedcordError } from '@seedcord/errors/internal';\nimport { Logger } from '@seedcord/logger';\n\nimport { getDevChannel } from '@hmr/devChannel';\n\nimport { pluginContextSlot, readPluginContext } from './context';\nimport { resolveLifecycleSpec } from './lifecycle';\n\nimport type { PluginContext, StoredPluginContext } from './context';\nimport type { ResolvedPluginLifecycleSpec, PluginLifecycleSpec } from './lifecycle';\nimport type { TransportOf, NeedsOf, PluginOptions, RuntimeOf } from './options';\nimport type { CoreBase } from '@interfaces/CoreBase';\nimport type { Tail, HmrAware, HmrUpdateEvent } from '@seedcord/types';\n\nexport interface Initializeable {\n    init(): Promise<void>;\n}\n\n/** @internal */\nconst resolvedSpecSlot = Symbol('seedcord.plugin.spec');\n\n/**\n * Base class for Seedcord plugins. A subclass declares its options as the `Opts` type argument,\n * implements `init()`, and reads the framework surface through `this.ctx`.\n *\n * @typeParam Opts - The plugin's declared {@link PluginOptions}.\n * @typeParam TCore - The host type `this.core` resolves to. Each transport binds it to its own `Core`.\n */\nexport abstract class Plugin<Opts extends PluginOptions = {}, TCore extends CoreBase = CoreBase>\n    implements Initializeable, HmrAware\n{\n    /** @internal phantom, never set at runtime */\n    declare readonly __transport?: TransportOf<Opts>;\n    /** @internal phantom, never set at runtime */\n    declare readonly __runtime?: RuntimeOf<Opts>;\n\n    /** @internal */\n    readonly [resolvedSpecSlot]: ResolvedPluginLifecycleSpec;\n    /** @internal */\n    [pluginContextSlot]?: StoredPluginContext;\n\n    /** Logs under the plugin's class name, on the channel its attach key names. */\n    public readonly logger: Logger;\n\n    // CoreBase here keeps the augmented Core out of ConstructorParameters, which attach reads\n    constructor(\n        private readonly host: CoreBase,\n        spec?: PluginLifecycleSpec\n    ) {\n        this.logger = new Logger(this.constructor.name);\n        this[resolvedSpecSlot] = resolveLifecycleSpec(spec, this.constructor.name);\n    }\n\n    /** The host, typed to the transport whose `Plugin` base this class extends. */\n    protected get core(): TCore {\n        // justified: each transport binds TCore to the Core its own host satisfies\n        return this.host as TCore;\n    }\n\n    /** The framework surface, available from `init()` onward. Throws if read before `attach` finalizes it. */\n    protected get ctx(): PluginContext<NeedsOf<Opts>> {\n        return readPluginContext<NeedsOf<Opts>>(this);\n    }\n\n    abstract init(): Promise<void>;\n\n    /**\n     * Runs in the startup Ready phase, after `init()`. The gateway client is logged in by this phase,\n     * and the http host runs its server-bind and health tasks in the same phase.\n     */\n    ready?(): Promise<void>;\n\n    /** Runs during teardown, only when `init()` resolved. */\n    dispose?(): Promise<void>;\n\n    /**\n     * Rejects the plugin's constructor options with a reason. Throws a `SeedcordError` naming the\n     * plugin class and the reason.\n     *\n     * @param reason - Why the options are invalid.\n     */\n    protected rejectOptions(reason: string): never {\n        throw new SeedcordError(SeedcordErrorCode.PluginOptionsRejected, [this.constructor.name, reason]);\n    }\n\n    /** Override to reload plugin state on an HMR update. */\n    public onHmr(_event: HmrUpdateEvent): Promise<void> {\n        return Promise.resolve();\n    }\n\n    /**\n     * Registers critical file patterns that should trigger a full restart when changed in Dev HMR.\n     * @param patterns - Glob patterns relative to the project root\n     */\n    protected registerCriticalFiles(patterns: string[]): void {\n        getDevChannel()?.send('seedcord:register-critical-files', { patterns });\n    }\n}\n\n/** @internal */\nexport function resolvedLifecycleSpecOf(plugin: PluginLike): ResolvedPluginLifecycleSpec {\n    return plugin[resolvedSpecSlot];\n}\n\nexport type { PluginContext, PluginCapabilityTypes } from './context';\nexport type { PluginLifecycleSpec } from './lifecycle';\nexport type { PluginOptions } from './options';\n\n// a bound of Plugin<{}> rejects every plugin that declares an option, since Plugin<A> and Plugin<B>\n// are mutually unassignable. every member here must stay Opts-independent.\n/** @internal */\nexport type PluginLike = Pick<\n    Plugin,\n    'init' | 'ready' | 'dispose' | 'logger' | 'onHmr' | typeof resolvedSpecSlot | typeof pluginContextSlot\n>;\n\n// a `CoreBase` first parameter rejects a narrowing ctor on its own, and it also collapses\n// `InstanceType<Ctor>` to `PluginLike` at every attach call. CoreParamAssert checks it instead.\n/** @internal */\nexport type PluginCtor<TPlugin extends PluginLike = PluginLike> = new (...args: any[]) => TPlugin;\n\n/** @internal */\nexport type PluginArgs<Ctor extends PluginCtor> = Tail<ConstructorParameters<Ctor>>;\n\ntype CoreParamTooNarrow = Record<\n    'this plugin constructor must take CoreBase as its first parameter and read the transport Core off this.core',\n    never\n>;\n\n// a narrowed first parameter fails `CoreBase extends Param`\n/** @internal */\nexport type CoreParamAssert<Ctor extends PluginCtor> = CoreBase extends ConstructorParameters<Ctor>[0]\n    ? unknown\n    : CoreParamTooNarrow;\n\nexport { finalizePluginContext } from './context';\n"],"mappings":";;;;;;;;AAqEA,MAAa,oBAAoB,OAAO,qBAAqB;;AAO7D,SAAgB,kBAA6C,QAA8C;CACvG,MAAM,MAAM,OAAO;CACnB,IAAI,CAAC,KAAK,MAAM,IAAI,cAAc,kBAAkB,yBAAyB,CAAC,OAAO,YAAY,IAAI,CAAC;CAEtG,OAAO;AACX;;AAGA,SAAgB,sBACZ,QACA,KACI;CACJ,OAAO,qBAAqB;AAChC;;;;ACnEA,MAAM,0BAA0B;AAChC,MAAM,2BAA2B;AACjC,MAAM,6BAA6B;AAEnC,SAAS,UACL,OACA,UACA,UACA,YACM;CACN,IAAI,aAAa,QAAW,OAAO;CACnC,IAAI,CAAC,OAAO,SAAS,QAAQ,KAAK,YAAY,GAC1C,MAAM,IAAI,cAAc,kBAAkB,uBAAuB,CAC7D,YACA,aAAa,MAAM,mDACvB,CAAC;CAEL,OAAO;AACX;;AAGA,SAAgB,qBACZ,MACA,YAC2B;CAC3B,OAAO;EACH,MAAM;GACF,OAAO,MAAM,MAAM;GACnB,SAAS,UAAU,QAAQ,MAAM,MAAM,SAAS,yBAAyB,UAAU;EACvF;EACA,OAAO,EACH,SAAS,UAAU,SAAS,MAAM,OAAO,SAAS,0BAA0B,UAAU,EAC1F;EACA,SAAS;GACL,OAAO,MAAM,SAAS;GACtB,SAAS,UAAU,WAAW,MAAM,SAAS,SAAS,4BAA4B,UAAU;EAChG;CACJ;AACJ;;;;;ACxCA,MAAM,mBAAmB,OAAO,sBAAsB;;;;;;;;AAStD,IAAsB,SAAtB,MAEA;CAgByB;;CATrB,CAAU;;CAEV,CAAC;;CAGD,AAAgB;CAGhB,YACI,AAAiB,MACjB,MACF;EAFmB;EAGjB,KAAK,SAAS,IAAI,OAAO,KAAK,YAAY,IAAI;EAC9C,KAAK,oBAAoB,qBAAqB,MAAM,KAAK,YAAY,IAAI;CAC7E;;CAGA,IAAc,OAAc;EAExB,OAAO,KAAK;CAChB;;CAGA,IAAc,MAAoC;EAC9C,OAAO,kBAAiC,IAAI;CAChD;;;;;;;CAmBA,AAAU,cAAc,QAAuB;EAC3C,MAAM,IAAI,cAAc,kBAAkB,uBAAuB,CAAC,KAAK,YAAY,MAAM,MAAM,CAAC;CACpG;;CAGA,AAAO,MAAM,QAAuC;EAChD,OAAO,QAAQ,QAAQ;CAC3B;;;;;CAMA,AAAU,sBAAsB,UAA0B;EACtD,cAAc,CAAC,EAAE,KAAK,oCAAoC,EAAE,SAAS,CAAC;CAC1E;AACJ;;AAGA,SAAgB,wBAAwB,QAAiD;CACrF,OAAO,OAAO;AAClB"}