@neontechspace/fluxerly 1000.0.0-nightly.12

package/dist/api/default/bot.js

@@ -0,0 +1,309 @@
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import { errAsync, okAsync, ResultAsync } from "neverthrow";
+import { CriticalWorkerStoppedError } from "#sdk/bot-runner";
+import { readIgnoreBots, reportBotFailure, runBotCore, skipsBotMessage, snapshotBotCommandDelivery, snapshotBotEvents, standaloneBotLogger, validateBotClientOptions, validateRunOptions, } from "#sdk/internal/bot-runner";
+import { clientServices } from "#sdk/internal/client-registry";
+import { throwIfErr } from "#sdk/internal/failures";
+import { defectReason } from "#sdk/internal/defects";
+import { ApplicationError, CancelledError, ConfigurationError, SdkDefect } from "#sdk/errors";
+import { EventOverflowError } from "#sdk/message-errors";
+import { botRouter, boundDefaultReply, } from "#sdk/default-commands";
+import {} from "./events.js";
+import { createClient } from "./client.js";
+import { fromExit } from "#sdk/internal/binding/execute";
+/**
+ * Read or validate runBot options. Misuse, SDK defects and register-callback failures keep their errors, and any other
+ * throw, such as from an option getter, is an application fault reported as an SdkDefect for runBot
+ */
+function readBotOptions(read) {
+    try {
+        return read();
+    }
+    catch (error) {
+        if (error instanceof ConfigurationError || error instanceof SdkDefect || error instanceof ApplicationError)
+            throw error;
+        throw new SdkDefect("runBot", [defectReason(error, "application")]);
+    }
+}
+function restoreTrustedSdkDefect(effect) {
+    return effect.pipe(Effect.catchCause((cause) => {
+        const reason = cause.reasons.length === 1 ? cause.reasons[0] : undefined;
+        if (reason?._tag !== "Die" || !(reason.defect instanceof SdkDefect))
+            return Effect.failCause(cause);
+        if (reason.defect.reasons.length === 0)
+            return Effect.failCause(Cause.die(reason.defect));
+        const restored = reason.defect.reasons.reduce((combined, detail) => Cause.combine(combined, detail.kind === "Failure"
+            ? Cause.fail(detail.failure)
+            : detail.kind === "Interruption"
+                ? Cause.interrupt()
+                : Cause.die(detail.defect)), Cause.empty);
+        return Effect.failCause(restored);
+    }));
+}
+function botOperation(start, trustedSdkDefects = false) {
+    const controller = new AbortController();
+    const operation = Promise.resolve(start(controller.signal));
+    const awaited = Effect.promise(() => operation);
+    const observed = trustedSdkDefects ? restoreTrustedSdkDefect(awaited) : awaited;
+    return observed.pipe(Effect.flatMap((result) => (result.isErr() ? Effect.fail(result.error) : Effect.succeed(result.value))), Effect.onInterrupt(() => Effect.sync(() => controller.abort()).pipe(Effect.andThen(observed), Effect.flatMap((result) => result.isErr() &&
+        result.error._tag !== "CancelledError" &&
+        result.error._tag !== "ClientClosedError"
+        ? Effect.fail(result.error)
+        : Effect.void))));
+}
+/**
+ * Start a bot from event handlers and prefix commands, and watch its connection and subscriptions.
+ * The client is created and every handler and command is registered synchronously, before this function returns and
+ * before the gateway connects, so no event is missed and no handler runs before registration and setup complete.
+ * Invalid options, such as a misspelled option key, an unknown event name, invalid delivery settings or an invalid
+ * command, throw ConfigurationError at once. Every option is checked before any client, signal listener or request
+ * exists, even when the signal is already aborted, so misuse leaves nothing to clean up.
+ * A missing or empty token, usually from an unset environment variable, is reported like a failed run instead: Once
+ * every other option is valid, runBot returns an Err ConfigurationError with field token before any client exists.
+ * The returned ResultAsync then runs the bot until it stops.
+ * Handler contexts expose the full client. Message-create contexts also expose message and a cancellation-aware reply.
+ * Handler and command failures are reported to onError, or logged in full, without restarting them or stopping the bot.
+ * By default, SIGINT and SIGTERM request a normal stop and messages written by bots skip the events handlers and
+ * prefix commands. Set processSignals or ignoreBots to false to opt out. Stopping waits for SDK cleanup, not unrelated application Promises.
+ * Expected runner failures return Err, including ApplicationError when the setup callback or a commands register
+ * callback fails and ConfigurationError for a missing token, and SDK defects reject with SdkDefect.
+ * By default a failed run is also logged once, with code lifecycle.botFailed unless the client already logged that
+ * error, and sets process.exitCode to 1, so `await runBot({...})` needs no further handling.
+ * Set reportFailure to false when the application handles the returned failure and exit status itself.
+ * A missing token or a commands-registration failure reported before client creation uses the configured logging
+ * settings, prints no stack for the missing token and masks the token after removing surrounding whitespace and one pair
+ * of matching quotes. Unusable logging settings are misuse.
+ * An option getter that throws while the options are checked throws SdkDefect with code application.defect and the
+ * thrown value as the cause, before any client exists. Other misuse and option-getter failures throw synchronously
+ * without a runner report or exit-status change, regardless of reportFailure
+ *
+ * @remarks
+ * Aborting the optional signal requests a normal stop, not a cancellation Err. A requested stop first stops accepting
+ * events and lets running handlers, scheduled tasks and their requests finish for up to drainMs, default 5,000 ms. Success means the client has
+ * stopped and cleanup has finished. The runner always shuts down its client, including after a failure.
+ * If an event or command subscription closes while the bot is still running, the result fails with
+ * CriticalWorkerStoppedError. That includes a handler or command router set to overflow "stop" whose queue overflows.
+ * The overflow is still reported to onError or logged, and the error names the event and the exceeded capacity, with
+ * the EventOverflowError as its cause.
+ * Process signal listeners are removed when the run finishes, and the runner never exits the process
+ *
+ * @example
+ * ```ts
+ * import { runBot } from "@neontechspace/fluxerly"
+ *
+ * export function pingBot(token: string | undefined) {
+ *     return runBot({
+ *         token,
+ *         commands: {
+ *             prefix: "!",
+ *             commands: {
+ *                 ping: { execute: ({ reply }) => reply("Pong!") },
+ *                 roll: {
+ *                     arguments: { sides: { type: "integer", min: 2, max: 100, default: 6 } },
+ *                     execute: ({ reply, values }) => reply(`${1 + Math.floor(Math.random() * values.sides)}`),
+ *                 },
+ *             },
+ *         },
+ *     })
+ * }
+ * ```
+ *
+ * @category Client and lifecycle
+ */
+export function runBot(options) {
+    try {
+        return startBot(options);
+    }
+    catch (error) {
+        // Misuse is found inside validation, so the stack starts at the caller's line instead, as in createClient
+        if (error instanceof ConfigurationError)
+            Error.captureStackTrace(error, runBot);
+        throw error;
+    }
+}
+function startBot(options) {
+    if (typeof options !== "object" || options === null || Array.isArray(options))
+        throw new ConfigurationError("configuration", "The runBot options must be an object");
+    const { events, ignoreBots, commands, setup, signal, processSignals, reportFailure, drainMs, clientOptions } = readBotOptions(() => {
+        const { events, ignoreBots, commands, setup, signal, processSignals, reportFailure, drainMs, ...clientOptions } = options;
+        return {
+            events,
+            ignoreBots,
+            commands,
+            setup,
+            signal,
+            processSignals,
+            reportFailure,
+            drainMs,
+            clientOptions,
+        };
+    });
+    readBotOptions(() => validateRunOptions({ signal, processSignals, reportFailure, drainMs }));
+    const runOptions = {
+        ...(signal === undefined ? {} : { signal }),
+        // The default API handles process signals unless the application opts out
+        processSignals: processSignals !== false,
+        ...(reportFailure === undefined ? {} : { reportFailure }),
+        ...(drainMs === undefined ? {} : { drainMs }),
+    };
+    // All configuration is checked before any client, listener or request exists, so misuse has no side effects.
+    // An already aborted signal still reports misuse rather than hiding it
+    const { entries, skipBots, router, commandHook, commandDelivery, commandsFailure } = prepareBot(events, ignoreBots, commands, setup);
+    // A missing token and the callback's failure are returned even when the signal is already aborted
+    const failure = readBotOptions(() => validateBotClientOptions(clientOptions, false)) ?? commandsFailure;
+    if (failure !== undefined) {
+        Effect.runSync(reportBotFailure(Exit.fail(failure), standaloneBotLogger(clientOptions, false), runOptions));
+        return errAsync(failure);
+    }
+    if (readBotOptions(() => signal?.aborted))
+        return okAsync(undefined);
+    const client = createClient(clientOptions);
+    let subscriptions;
+    try {
+        subscriptions = registerBot(client, { entries, skipBots, router, commandHook, commandDelivery });
+    }
+    catch (error) {
+        // Validated registration cannot be misuse here, so this is a defect. The unused client owns no socket yet,
+        // and its cleanup failure is logged by the client
+        void client
+            .shutdown()
+            .then(undefined, (defect) => clientServices(client)?.logging.outputFailure(defect));
+        throw error;
+    }
+    const shutdownClient = (options) => restoreTrustedSdkDefect(Effect.promise(() => client.shutdown(options))).pipe(Effect.asVoid);
+    // Every way the runner stops shuts its client down, so aborting there tells setup work that the bot is stopping
+    const stopping = new AbortController();
+    // The client exists before the runner starts, so the runner owns its shutdown only once it takes the client
+    let taken = false;
+    const program = runBotCore(Effect.sync(() => {
+        taken = true;
+        return {
+            source: client,
+            logger: clientServices(client)?.logging,
+            get state() {
+                return client.state;
+            },
+            run: () => botOperation((signal) => client.run({ signal }), true),
+            shutdown: (options) => Effect.sync(() => stopping.abort()).pipe(Effect.andThen(shutdownClient(options))),
+        };
+    }), () => (setup === undefined
+        ? Effect.void
+        : // @effect-diagnostics-next-line unknownInEffectCatch:off
+            Effect.tryPromise({
+                try: () => runBotSetup(setup, client, stopping.signal),
+                catch: (error) => error,
+            }).pipe(
+            // Setup failures, such as a failed read, are application outcomes. An SDK defect stays a defect
+            Effect.catch((error) => error instanceof ApplicationError ? Effect.fail(error) : Effect.die(error)))).pipe(Effect.as(subscriptions.map((subscription, index) => ({
+        // A subscription stopped by overflow "stop" stops the bot, naming its event and capacity
+        waitForClose: () => botOperation((signal) => subscription.waitForClose({ signal })).pipe(Effect.mapError((error) => error instanceof EventOverflowError
+            ? new CriticalWorkerStoppedError(index, {
+                // The command router follows the event handlers and receives messageCreate
+                event: entries[index]?.event ?? "messageCreate",
+                error,
+            })
+            : error)),
+    })))), runOptions).pipe(Effect.ensuring(Effect.suspend(() => (taken ? Effect.void : shutdownClient()))));
+    // fromExit returns a single failure unchanged, including the setup ApplicationError that no client operation returns
+    return new ResultAsync(Effect.runPromiseExit(program).then((exit) => fromExit(exit, "runBot")));
+}
+/**
+ * Read and check a bot's event handlers, commands and setup callback before any client exists. Misuse throws
+ * ConfigurationError. A commands register callback's own failure is returned as commandsFailure, so the caller can
+ * finish checking the other options first
+ */
+function prepareBot(events, ignoreBots, commands, setup) {
+    if (setup !== undefined && typeof setup !== "function")
+        throw new ConfigurationError("configuration", 'The option "setup" must be a function');
+    const entries = readBotOptions(() => snapshotBotEvents(events));
+    const skipBots = readIgnoreBots(ignoreBots);
+    let router;
+    let commandsFailure;
+    try {
+        router = commands === undefined ? undefined : readBotOptions(() => botRouter(commands, skipBots));
+    }
+    catch (error) {
+        // A register callback's own failure is an application outcome, returned once the other options are checked
+        if (!(error instanceof ApplicationError))
+            throw error;
+        commandsFailure = error;
+    }
+    const commandHook = readBotOptions(() => commands?.onError);
+    if (commandHook !== undefined && typeof commandHook !== "function")
+        throw new ConfigurationError("onError", 'The option "commands.onError" must be a function');
+    const commandDelivery = commands === undefined ? undefined : readBotOptions(() => snapshotBotCommandDelivery(commands));
+    return { entries, skipBots, router, commandHook, commandDelivery, commandsFailure };
+}
+/**
+ * Run a bot's setup callback once with the signal that aborts when the bot begins stopping. A throw, rejection or
+ * returned Err rejects with ApplicationError whose source is "runBot setup" and whose cause is the original value.
+ * A thrown SdkDefect rejects unchanged
+ */
+async function runBotSetup(setup, client, signal) {
+    try {
+        throwIfErr(await setup(client, Object.freeze({ signal })));
+    }
+    catch (error) {
+        throw error instanceof SdkDefect ? error : new ApplicationError("runBot setup", error);
+    }
+}
+/**
+ * Register runBot events and commands on a test client with the same checks, contexts and registration as runBot,
+ * returning the setup work that the test client runs before it connects, given the signal that aborts when the test
+ * client stops. Used by the testing entry point.
+ * Misuse throws ConfigurationError, and a commands register callback's own failure throws its ApplicationError
+ */
+export function installTestBot(client, options) {
+    const { events, ignoreBots, commands, setup } = readBotOptions(() => ({
+        events: options.events,
+        ignoreBots: options.ignoreBots,
+        commands: options.commands,
+        setup: options.setup,
+    }));
+    const prepared = prepareBot(events, ignoreBots, commands, setup);
+    if (prepared.commandsFailure !== undefined)
+        throw prepared.commandsFailure;
+    registerBot(client, prepared);
+    return setup === undefined
+        ? async () => undefined
+        : (signal) => runBotSetup(setup, client, signal);
+}
+/** Register the bot's event handlers and command router synchronously, returning the subscriptions to supervise */
+function registerBot(client, { entries, skipBots, router, commandHook, commandDelivery, }) {
+    const subscriptions = [];
+    try {
+        for (const { event, handler, options } of entries) {
+            // The snapshot validates functions, and client.on validates event names and delivery settings
+            const callback = handler;
+            subscriptions.push(client.on(event, (payload, signal) => skipsBotMessage(event, payload, skipBots)
+                ? undefined
+                : callback(Object.freeze({
+                    event: payload,
+                    client,
+                    signal,
+                    ...(event === "messageCreate"
+                        ? {
+                            message: payload,
+                            reply: boundDefaultReply(client, payload, signal),
+                        }
+                        : {}),
+                })), options));
+        }
+        if (router !== undefined)
+            subscriptions.push(router.attach(client, {
+                ...commandDelivery,
+                ...(commandHook === undefined ? {} : { onError: commandHook }),
+            }));
+        return subscriptions;
+    }
+    catch (error) {
+        for (const subscription of subscriptions)
+            subscription.close();
+        if (error instanceof ConfigurationError)
+            throw error;
+        throw new SdkDefect("runBot", [defectReason(error)]);
+    }
+}
+//# sourceMappingURL=bot.js.map

package/dist/api/default/bot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bot.js","sourceRoot":"","sources":["../../../src/api/default/bot.ts"],"names":[],"mappings":"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"}

package/dist/api/default/cache.d.ts

@@ -0,0 +1,105 @@
+import type { CacheChange, CacheObserverOptions } from "#sdk/cache";
+import type { CacheEntriesOptions, CachedResources, CacheKind } from "#sdk/client";
+import type { Message, MessageCore } from "#sdk/messages";
+/**
+ * Stop receiving cache changes from client.cache.onChange.
+ * Use `using` to close the observer when the enclosing block ends
+ *
+ * @category Caching
+ */
+export interface CacheObserver {
+    /** Identifier of this observer, such as cacheChange#3, used in its log records */
+    readonly id: string;
+    /** Stop delivering changes, including changes recorded or waiting but not yet delivered. Listener work already started is not cancelled. Repeated calls do nothing */
+    close(): void;
+    /** Close this observer, as `using` does at the end of a block */
+    [Symbol.dispose](): void;
+}
+/**
+ * Inspect, clear or remove data already held in this client's caches.
+ * These methods do not fetch, refresh or change remote resources
+ *
+ * @category Caching
+ */
+export interface ClientCache<M extends MessageCore = Message> {
+    /**
+     * Return frozen snapshots from one configured cache category, ordered least to most recently used.
+     * The limit option defaults to 100 and accepts a positive safe integer from 1 through 1,000. It is read once, so the
+     * validated limit is the one applied.
+     * Expired entries are released first.
+     * Enumeration neither refreshes them nor changes eviction order, while local lookups do promote recency.
+     * Unlike diagnostics, the array contains actual cached resource data, and no network request or remote completeness claim is made.
+     * It may be partial because cache limits, expiry, conflicts, gateway gaps, clear or shutdown can discard entries.
+     * A closed client produces an empty array.
+     * Invalid kind or limit is misuse: The default API throws ConfigurationError without exposing the rejected value, and the native API dies with it
+     *
+     * @remarks
+     * Returns the array synchronously and takes no signal. Misuse throws ConfigurationError, and a throwing limit getter
+     * throws SdkDefect with code application.defect and the thrown value as its cause
+     */
+    entries<K extends CacheKind>(kind: K, options?: CacheEntriesOptions): readonly CachedResources<M>[K][];
+    /**
+     * Release data held by this client's caches without changing which caches are enabled.
+     * Pass a kind to release only that category, or omit it to release every category.
+     * Objects already returned to the caller, requests and remote resources stay unchanged.
+     * Older in-flight reads cannot refill the cleared entries and may skip caching their results, while later reads can cache normally.
+     * Existing write-related invalidation remains in effect.
+     * Each category that held entries reports one clear change to cache.onChange listeners, and a disabled category is left as is.
+     * This runs immediately, takes no signal and can be repeated, including after closure.
+     * An invalid kind is misuse: Both APIs throw ConfigurationError without exposing the rejected value
+     */
+    clear(kind?: CacheKind): void;
+    /**
+     * Remove one entry from a cache category by its key, without fetching, refreshing or changing the remote resource.
+     * The key uses the format described on CacheChange: `channelId:messageId` for messages, `guildId:userId` for members,
+     * `guildId:id` for roles, emojis and stickers, and the resource ID alone for communities, channels, users and direct messages.
+     * Objects already returned to the caller stay unchanged.
+     * Reads of this category already in flight cannot restore the removed entry and some may skip caching their other results,
+     * while later reads and events can cache it again.
+     * A removed entry reports one delete change to cache.onChange listeners, and a missing entry or disabled category is left as is.
+     * This runs immediately, takes no signal and can be repeated, including after closure.
+     * An invalid kind or key is misuse: Both APIs throw ConfigurationError without exposing the rejected value
+     *
+     * @example
+     * ```ts
+     * import type { Client } from "@neontechspace/fluxerly"
+     * export function forgetMember(client: Client, guildId: string, userId: string) {
+     *     client.cache.delete("members", `${guildId}:${userId}`)
+     * }
+     * ```
+     */
+    delete(kind: CacheKind, key: string): void;
+    /**
+     * Observe every later change to this client's local caches: Stored or replaced entries, removed entries and whole-category clears.
+     * Changes are delivered in the order they were applied, from a microtask after the cache work that produced them, so a listener never runs inside a cache operation and can read or clear the cache itself.
+     * Lookups, enumeration and diagnostics are not changes, and a clear is reported only for a category that held at least one entry.
+     * No change is recorded while no listener is registered, and a new listener receives no earlier changes or current contents.
+     * Delivery has no ordering relative to event handlers, and listener work never changes a cache result, a REST outcome or event delivery.
+     * A failing listener is reported as a cache failure to the client-level onError, or logged at Error, and keeps receiving later changes.
+     * Client shutdown records its final clears, then closes every observer without waiting for unfinished listener calls.
+     * A listener with a free call receives those clears, and changes still waiting for a busy listener are dropped with a cache.changesDropped Warn.
+     * Registering after shutdown returns an observer that never receives a change.
+     * A listener that is not a function, or invalid options, is misuse: The default API throws ConfigurationError, and the native API dies with it
+     *
+     * @remarks
+     * Returns the observer synchronously.
+     * The listener runs once per change. It fails when it throws, rejects, or returns or resolves an Err result.
+     * A returned promise is not awaited, so asynchronous listener calls overlap, up to options.concurrency unfinished calls, 256 by default.
+     * Later changes then wait in order, up to options.maxPendingChanges, 256 by default, and a change arriving at that limit
+     * drops the oldest waiting change with a cache.changesDropped Warn.
+     * Waiting changes are discarded when the observer closes.
+     * A throwing options getter throws SdkDefect with code application.defect and the thrown value as its cause
+     *
+     * @example
+     * ```ts
+     * import type { Client } from "@neontechspace/fluxerly"
+     * export function cacheChangesExample(client: Client, forget: (key: string) => void) {
+     *     return client.cache.onChange((change) => {
+     *         if (change.kind === "members" && change.op === "delete" && change.key !== null) forget(change.key)
+     *     })
+     * }
+     * ```
+     */
+    onChange(listener: (change: CacheChange) => unknown, options?: CacheObserverOptions): CacheObserver;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/api/default/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../src/api/default/cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AACnE,OAAO,KAAK,EAAE,mBAAmB,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAClF,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAEzD;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC1B,kFAAkF;IAClF,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,sKAAsK;IACtK,KAAK,IAAI,IAAI,CAAA;IACb,iEAAiE;IACjE,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAA;CAC3B;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,WAAW,GAAG,OAAO;IACxD;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,CAAC,SAAS,SAAS,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,SAAS,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;IACtG;;;;;;;;;OASG;IACH,KAAK,CAAC,IAAI,CAAC,EAAE,SAAS,GAAG,IAAI,CAAA;IAC7B;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,aAAa,CAAA;CACtG"}

package/dist/api/default/cache.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cache.js.map

package/dist/api/default/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../../src/api/default/cache.ts"],"names":[],"mappings":""}