@neontechspace/fluxerly 1000.0.0-nightly.12

package/dist/role-hierarchy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-hierarchy.d.ts","sourceRoot":"","sources":["../src/role-hierarchy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAIhE;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IAC/B,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,qDAAqD;IACrD,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAA;IAC3B,6CAA6C;IAC7C,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAA;CACvC;AAYD;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACpC;;;;;;;OAOG;IACH,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACtD;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAA;IACnD;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAA;CAChD,CAAC,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,SAAS,EAAE,gBA+BtB,CAAA"}

package/dist/role-hierarchy.js

@@ -0,0 +1,53 @@
+import { GuildOperationError } from "./guilds.js";
+import { compareRoleHierarchy, evaluateMemberHierarchy, isRoleAboveInHierarchy } from "#sdk/internal/role-hierarchy";
+import { inputValidationFailure } from "./input-validation.js";
+const inputFailure = (operation, path, explanation) => new GuildOperationError({
+    operation,
+    reason: "input",
+    outcome: "notDispatched",
+    inputValidation: inputValidationFailure(path, "format", explanation).detail,
+});
+/**
+ * Compare roles and members by Fluxer's role hierarchy from snapshots already held, returning plain values.
+ * Invalid snapshots throw GuildOperationError with reason input
+ * @example
+ * ```ts
+ * import { hierarchy, type Client } from "@neontechspace/fluxerly"
+ * export async function hierarchyExample(client: Client, guildId: string, actorUserId: string, targetUserId: string) {
+ *     const [guild, actor, target, roles] = await Promise.all([
+ *         client.guilds.fetch(guildId),
+ *         client.members.fetch({ guildId, userId: actorUserId }),
+ *         client.members.fetch({ guildId, userId: targetUserId }),
+ *         client.roles.fetchAll(guildId),
+ *     ])
+ *     if (guild.isErr()) return guild
+ *     if (actor.isErr()) return actor
+ *     if (target.isErr()) return target
+ *     if (roles.isErr()) return roles
+ *     return hierarchy.canManage({ guild: guild.value, actor: actor.value, target: target.value, roles: roles.value })
+ * }
+ * ```
+ *
+ * @category Roles and permissions
+ */
+export const hierarchy = Object.freeze({
+    compare(left, right) {
+        const comparison = compareRoleHierarchy(left, right);
+        if (comparison === undefined)
+            throw inputFailure("hierarchy.compare", "roles", "Role snapshots must contain same-community decimal IDs and nonnegative 32-bit integer positions");
+        return comparison;
+    },
+    isAbove(left, right) {
+        const above = isRoleAboveInHierarchy(left, right);
+        if (above === undefined)
+            throw inputFailure("hierarchy.isAbove", "roles", "Role snapshots must contain same-community decimal IDs and nonnegative 32-bit integer positions");
+        return above;
+    },
+    canManage(input) {
+        const manageable = evaluateMemberHierarchy(input);
+        if (manageable === undefined)
+            throw inputFailure("hierarchy.canManage", "input", "Hierarchy input must contain consistent guild, member, and unique role snapshots covering both members");
+        return manageable;
+    },
+});
+//# sourceMappingURL=role-hierarchy.js.map

package/dist/role-hierarchy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-hierarchy.js","sourceRoot":"","sources":["../src/role-hierarchy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAEjD,OAAO,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAA;AACpH,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA;AAqB9D,MAAM,YAAY,GAAG,CAAC,SAA6B,EAAE,IAAY,EAAE,WAAmB,EAAE,EAAE,CACtF,IAAI,mBAAmB,CAAC;IACpB,SAAS;IACT,MAAM,EAAE,OAAO;IACf,OAAO,EAAE,eAAe;IACxB,eAAe,EAAE,sBAAsB,CAAC,IAAI,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC,MAAM;CAC9E,CAAC,CAAA;AA0CN;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,MAAM,SAAS,GAAqB,MAAM,CAAC,MAAM,CAAC;IACrD,OAAO,CAAC,IAAe,EAAE,KAAgB;QACrC,MAAM,UAAU,GAAG,oBAAoB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;QACpD,IAAI,UAAU,KAAK,SAAS;YACxB,MAAM,YAAY,CACd,mBAAmB,EACnB,OAAO,EACP,iGAAiG,CACpG,CAAA;QACL,OAAO,UAAU,CAAA;IACrB,CAAC;IACD,OAAO,CAAC,IAAe,EAAE,KAAgB;QACrC,MAAM,KAAK,GAAG,sBAAsB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;QACjD,IAAI,KAAK,KAAK,SAAS;YACnB,MAAM,YAAY,CACd,mBAAmB,EACnB,OAAO,EACP,iGAAiG,CACpG,CAAA;QACL,OAAO,KAAK,CAAA;IAChB,CAAC;IACD,SAAS,CAAC,KAAyB;QAC/B,MAAM,UAAU,GAAG,uBAAuB,CAAC,KAAK,CAAC,CAAA;QACjD,IAAI,UAAU,KAAK,SAAS;YACxB,MAAM,YAAY,CACd,qBAAqB,EACrB,OAAO,EACP,wGAAwG,CAC3G,CAAA;QACL,OAAO,UAAU,CAAA;IACrB,CAAC;CACJ,CAAC,CAAA"}

package/dist/sharding.d.ts

@@ -0,0 +1,219 @@
+import type { ConnectionState } from "./client.js";
+/**
+ * Connection-attempt snapshot for one shard, a gateway connection owned by this client.
+ * Recovery means reconnecting after the shard has previously established a session.
+ * Endpoint, session credentials and provider failure details are excluded
+ *
+ * @category Sharding and supervision
+ */
+export interface ShardRecoveryDiagnostic {
+    /** Whether this attempt belongs to initial startup or established-session recovery */
+    readonly phase: "startup" | "recovery";
+    /** One-based connection attempt number for this shard's managed run, counting startup and later recovery.
+     * During a retry delay, identifies the attempt that ended, not the next attempt
+     */
+    readonly attempt: number;
+    /** Scheduled retry wait in milliseconds, or null while the current attempt is not waiting. This is not a remaining countdown */
+    readonly retryDelayMs: number | null;
+}
+/**
+ * Divide the bot's community events among gateway connections called shards.
+ * Set this when the bot needs more than one gateway connection or this client should own only part of a shared shard plan.
+ * One client can own several shards within one process. Separate processes use separate clients
+ *
+ * Every process serving the same bot must use the same total and avoid overlapping ownership.
+ * Omit shardIds to own every ID from zero through totalShards minus one
+ *
+ * Creation validates the plan and copies the supplied IDs in order without changing caller input.
+ * Invalid plans fail creation with ConfigurationError. An explicit plan cannot change during the client's lifetime.
+ * An automatic plan moves to a larger one while the client runs when Fluxer closes a shard with 4011 (sharding required),
+ * and so does the single shard of a client created without sharding settings
+ *
+ * Shard zero receives direct-message gateway traffic. Include it when this client must receive direct messages.
+ * The SDK does not coordinate other processes unless identify supplies a coordinator
+ *
+ * With totalShards set to 1, session startup sends no shard tuple in the gateway Identify command.
+ * Default-API and native clients accept the same plan. Native validation and copying happen when the creation Effect runs
+ *
+ * @category Sharding and supervision
+ */
+export interface ShardingOptions {
+    /**
+     * Immutable total gateway shards for this bot, an integer from 1 through 16,384 shared by every process serving it.
+     * Fluxer closes a shard with 4011 (sharding required) when it serves more than 2,500 communities, and with an explicit
+     * total that closure ends the client with a ConnectionError.
+     * The value "auto" lets this client size the plan itself and own every shard, as the sharding value "auto" does, while
+     * keeping identify and sessions available
+     */
+    readonly totalShards: number | "auto";
+    /** Immutable non-empty local IDs, each unique integer from 0 through totalShards minus one.
+     * Omit to own every ID in ascending order. Automatic sizing requires omission
+     */
+    readonly shardIds?: readonly number[];
+    /**
+     * Coordinate new-session Identify commands with other processes, for example through a shared lock service.
+     * The coordinator then owns pacing: The SDK waits for permit before each Identify and adds no spacing of its own.
+     * Resume never waits for it. See IdentifyCoordinator
+     */
+    readonly identify?: IdentifyCoordinator;
+    /**
+     * Keep resumable sessions across process restarts, so a restart within Fluxer's 60-second resume window can Resume
+     * instead of starting new sessions. A fallback to a new session clears any partial restored replay from that shard's
+     * community caches and dependent resources. A successful Resume retains it. See SessionStore
+     */
+    readonly sessions?: SessionStore;
+    /**
+     * Whether a shard that resumes a session loaded from sessions refills the enabled community, role and channel
+     * caches through REST, default true. Fluxer calls a community a guild. Resume replays missed dispatches but sends no
+     * fresh community snapshot, so without the refill those caches contain only observations from replay, later events
+     * and requests.
+     * Once every shard is ready, the SDK lists the bot's communities and fetches each one on a resumed shard, one
+     * request at a time, so application requests keep the other REST slots and every request respects rate limits.
+     * It logs lifecycle.cacheRefill when done, at Warn when communities failed or the refill stopped early. A community list
+     * page that does not move past the previous one stops the refill instead of paging forever.
+     * Set false to skip the refill, for example for a bot that reads no cache
+     * @defaultValue true
+     */
+    readonly refillCaches?: boolean;
+}
+/**
+ * Coordinates Identify commands for shards that start new sessions, so several processes serving one bot can respect
+ * Fluxer's shared Identify budget.
+ * Creation copies the permit function, bound to its object, and later changes to the object have no effect.
+ * Clients that a local supervisor starts cannot set one, because the supervisor paces their Identify commands. Pass the
+ * coordinator to the supervisor option identify.coordinator instead, and the supervisor consults it for every child
+ *
+ * @category Sharding and supervision
+ */
+export interface IdentifyCoordinator {
+    /**
+     * Resolve when the shard may send Identify now. The SDK calls this once per new-session attempt and sends Identify as
+     * soon as the promise resolves, without spacing of its own, so pace permits within Fluxer's budget of 300 Identify
+     * commands per source IP address in each 60-second window.
+     * Only one permit per client is outstanding at a time, so a slow permit delays this client's other shards.
+     * The wait counts against the startup deadline during startup and against the recovery attempt timeout during recovery.
+     * The signal aborts when the attempt ends first, for example on timeout or shutdown, so resolve or reject promptly then.
+     * A rejection or thrown error fails that connection attempt: The SDK logs the error in full at Error with code
+     * lifecycle.identifyPermitFailed and retries like a transient connection failure, so repeated rejection can end
+     * startup with a ConnectionError whose cause is the rejection
+     *
+     * @param shardId The local shard about to Identify
+     * @param totalShards The plan's total shard count, useful for a bucket key such as shardId modulo a concurrency
+     * @param signal Aborted when the SDK no longer needs this permit
+     */
+    permit(shardId: number, totalShards: number, signal: AbortSignal): Promise<void>;
+}
+/**
+ * The resumable state of one shard's gateway session, saved at shutdown and offered again at the next startup.
+ * It holds the session ID, which lets the bot's token resume the session, so store it as carefully as other secrets
+ *
+ * @category Sharding and supervision
+ */
+export interface SessionSnapshot {
+    /** Session ID from Fluxer's READY */
+    readonly sessionId: string;
+    /** Last dispatch sequence this client received on the session, a non-negative integer */
+    readonly sequence: number;
+    /**
+     * Gateway URL the session connected to. Fluxer publishes no separate resume URL, so this is the discovered gateway
+     * endpoint. A loaded snapshot is used only when it matches the endpoint the new client discovers
+     */
+    readonly resumeUrl: string;
+    /** Wall-clock time the snapshot was taken, in Unix epoch milliseconds, after the session's socket closed */
+    readonly savedAt: number;
+    /**
+     * Total shard count of the plan the session identified with. A session belongs to that plan, so a loaded snapshot is
+     * used only when the new client's plan has the same total
+     */
+    readonly totalShards: number;
+}
+/**
+ * Persist resumable gateway sessions across restarts. Fluxer retains a disconnected session for 60,000 ms, so a
+ * process that restarts within that window can Resume and receive the dispatches it missed, subject to Fluxer's replay
+ * limits. Creation copies both functions, bound to their object.
+ * Snapshots are saved only during shutdown, after each shard's socket has closed, never while a session is live and
+ * not after a permanent connection failure, so a crash leaves no fresh snapshot. A saved session closes with private-use
+ * code 4000 to preserve Resume. Without persistence, intentional final closure uses 1000, which destroys the session
+ *
+ * @category Sharding and supervision
+ */
+export interface SessionStore {
+    /**
+     * Return the snapshot saved for this shard, or undefined when none exists. The SDK calls this once per shard at the
+     * first connection attempt after discovery, and allows 5,000 ms, within the startup deadline.
+     * A snapshot older than 60,000 ms, saved more than 5,000 ms in the future, malformed, for a different gateway
+     * endpoint or for a plan with a different totalShards is ignored and logged at Warn with code
+     * lifecycle.sessionSnapshotIgnored.
+     * A rejection, thrown error or timeout is logged in full at Error with code lifecycle.sessionLoadFailed.
+     * Either way the shard starts a new session, so load problems never fail startup.
+     * If Fluxer no longer holds the session, Resume fails and the shard starts a new session as in any recovery.
+     * Partial replay can update caches before RESUMED. A fallback to Identify clears that shard's cached communities and
+     * dependent resources, then clears reads cached during the wait again at READY. A successful Resume retains the replay
+     *
+     * @param shardId The local shard starting up
+     */
+    load(shardId: number): Promise<SessionSnapshot | undefined>;
+    /**
+     * Store a snapshot for this shard. The SDK calls this during shutdown for each shard that holds a resumable
+     * session, after its socket has closed and before shutdown completes, and allows each call 5,000 ms.
+     * Shutdown waits for these calls, then continues regardless of the outcome.
+     * A rejection, thrown error or timeout is logged in full at Error with code lifecycle.sessionSaveFailed
+     *
+     * @param shardId The local shard the snapshot belongs to
+     * @param snapshot The frozen resumable state
+     */
+    save(shardId: number, snapshot: SessionSnapshot): Promise<void>;
+}
+/**
+ * Create a SessionStore that keeps each shard's snapshot in its own file, shard-ID.json, inside one directory.
+ * Pass it as sharding.sessions so a restart within Fluxer's 60-second window resumes instead of starting new sessions.
+ * Use a directory that only the bot's account can read, outside version control, because each file holds a session ID
+ * that lets the bot's token resume that session. The store never logs snapshot contents
+ *
+ * @remarks
+ * A relative path resolves against the current working directory when the store is created, and a URL must use the
+ * file: scheme. An empty path or another URL scheme throws ConfigurationError.
+ * The store creates nothing until the first save. Each save creates the directory when missing, with mode 0700, writes
+ * the snapshot to a new temporary file with mode 0600 in that directory, flushes it to disk and renames it over the
+ * shard's file, so a crash never leaves a partly written snapshot and the previous file stays until the rename. A failed
+ * save removes its temporary file. Windows ignores these modes, so there the directory's access control list decides
+ * who can read the files.
+ * Load returns undefined when the shard has no file. It returns the parsed file without checking its fields, so the SDK
+ * ignores a malformed or outdated snapshot with a lifecycle.sessionSnapshotIgnored Warn. A file that is not valid JSON
+ * rejects with an Error that names the file but not its contents, and other file system failures reject with their
+ * Node.js error. The SDK logs those rejections as lifecycle.sessionLoadFailed or lifecycle.sessionSaveFailed and
+ * continues, as SessionStore describes.
+ * Separate processes must use separate directories unless their shard IDs never overlap
+ *
+ * @example
+ * ```ts
+ * import { createClient, fileSessionStore } from "@neontechspace/fluxerly"
+ *
+ * export function resumableClient(token: string) {
+ *     return createClient({ token, sharding: { totalShards: "auto", sessions: fileSessionStore("sessions") } })
+ * }
+ * ```
+ *
+ * @category Sharding and supervision
+ */
+export declare function fileSessionStore(directory: string | URL): SessionStore;
+/**
+ * Frozen connection-state snapshot for one gateway shard owned by this client.
+ * Use client.shards to inspect local connections rather than the health of other processes or the whole bot.
+ * An explicit plan keeps its shards for the client's lifetime. A client without sharding options reports shard ID zero.
+ * An automatically sized client reports no shards until its first connect has chosen the plan. Both report the new
+ * plan's shards after they move to a larger plan
+ *
+ * @category Sharding and supervision
+ */
+export interface ShardState {
+    /** This client's local shard ID, retained in the configured local order */
+    readonly shardId: number;
+    /** Current connection status for this shard */
+    readonly state: ConnectionState;
+    /** Latest current-connection heartbeat round trip in milliseconds, or null when no measurement is current */
+    readonly gatewayLatencyMs: number | null;
+    /** Current safe connection attempt or retry snapshot, or null when this shard is not attempting or waiting */
+    readonly recovery: ShardRecoveryDiagnostic | null;
+}
+//# sourceMappingURL=sharding.d.ts.map

package/dist/sharding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharding.d.ts","sourceRoot":"","sources":["../src/sharding.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAGlD;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACpC,sFAAsF;IACtF,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,CAAA;IACtC;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,gIAAgI;IAChI,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;CACvC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,eAAe;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAA;IACrC;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACrC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,mBAAmB,CAAA;IACvC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAA;IAChC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAClC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IAChC;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACnF;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC5B,qCAAqC;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,yFAAyF;IACzF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,4GAA4G;IAC5G,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC/B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IACzB;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAAA;IAC3D;;;;;;;;OAQG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAClE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,GAAG,GAAG,YAAY,CA0CtE;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACvB,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAA;IAC/B,6GAA6G;IAC7G,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;IACxC,8GAA8G;IAC9G,QAAQ,CAAC,QAAQ,EAAE,uBAAuB,GAAG,IAAI,CAAA;CACpD"}

package/dist/sharding.js

@@ -0,0 +1,86 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, open, readFile, rename, rm } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ConfigurationError } from "./errors.js";
+/**
+ * Create a SessionStore that keeps each shard's snapshot in its own file, shard-ID.json, inside one directory.
+ * Pass it as sharding.sessions so a restart within Fluxer's 60-second window resumes instead of starting new sessions.
+ * Use a directory that only the bot's account can read, outside version control, because each file holds a session ID
+ * that lets the bot's token resume that session. The store never logs snapshot contents
+ *
+ * @remarks
+ * A relative path resolves against the current working directory when the store is created, and a URL must use the
+ * file: scheme. An empty path or another URL scheme throws ConfigurationError.
+ * The store creates nothing until the first save. Each save creates the directory when missing, with mode 0700, writes
+ * the snapshot to a new temporary file with mode 0600 in that directory, flushes it to disk and renames it over the
+ * shard's file, so a crash never leaves a partly written snapshot and the previous file stays until the rename. A failed
+ * save removes its temporary file. Windows ignores these modes, so there the directory's access control list decides
+ * who can read the files.
+ * Load returns undefined when the shard has no file. It returns the parsed file without checking its fields, so the SDK
+ * ignores a malformed or outdated snapshot with a lifecycle.sessionSnapshotIgnored Warn. A file that is not valid JSON
+ * rejects with an Error that names the file but not its contents, and other file system failures reject with their
+ * Node.js error. The SDK logs those rejections as lifecycle.sessionLoadFailed or lifecycle.sessionSaveFailed and
+ * continues, as SessionStore describes.
+ * Separate processes must use separate directories unless their shard IDs never overlap
+ *
+ * @example
+ * ```ts
+ * import { createClient, fileSessionStore } from "@neontechspace/fluxerly"
+ *
+ * export function resumableClient(token: string) {
+ *     return createClient({ token, sharding: { totalShards: "auto", sessions: fileSessionStore("sessions") } })
+ * }
+ * ```
+ *
+ * @category Sharding and supervision
+ */
+export function fileSessionStore(directory) {
+    if (directory instanceof URL ? directory.protocol !== "file:" : typeof directory !== "string" || directory === "")
+        throw new ConfigurationError("sessions", "The session directory must be a non-empty path or a file: URL");
+    const root = resolve(directory instanceof URL ? fileURLToPath(directory) : directory);
+    const file = (shardId) => join(root, `shard-${shardId}.json`);
+    return Object.freeze({
+        async load(shardId) {
+            let text;
+            try {
+                text = await readFile(file(shardId), "utf8");
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    return undefined;
+                throw error;
+            }
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                // allow-silent: The SyntaxError quotes file text, which can hold the session ID, so only the file is named
+                throw new Error(`The saved session file ${file(shardId)} is not valid JSON`);
+            }
+        },
+        async save(shardId, snapshot) {
+            await mkdir(root, { recursive: true, mode: 0o700 });
+            const target = file(shardId);
+            const temporary = `${target}.${randomUUID()}.tmp`;
+            try {
+                const handle = await open(temporary, "wx", 0o600);
+                try {
+                    await handle.writeFile(JSON.stringify(snapshot));
+                    await handle.sync();
+                }
+                finally {
+                    await handle.close();
+                }
+                await rename(temporary, target);
+            }
+            catch (error) {
+                await rm(temporary, { force: true }).catch(() => {
+                    // allow-silent: The save failure below is the outcome the SDK logs, and a leftover temporary file is harmless
+                });
+                throw error;
+            }
+        },
+    });
+}
+//# sourceMappingURL=sharding.js.map

package/dist/sharding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharding.js","sourceRoot":"","sources":["../src/sharding.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAA;AACpE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAExC,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AA4KhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAAuB;IACpD,IAAI,SAAS,YAAY,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,EAAE;QAC7G,MAAM,IAAI,kBAAkB,CAAC,UAAU,EAAE,+DAA+D,CAAC,CAAA;IAC7G,MAAM,IAAI,GAAG,OAAO,CAAC,SAAS,YAAY,GAAG,CAAC,CAAC,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;IACrF,MAAM,IAAI,GAAG,CAAC,OAAe,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,OAAO,OAAO,CAAC,CAAA;IACrE,OAAO,MAAM,CAAC,MAAM,CAAC;QACjB,KAAK,CAAC,IAAI,CAAC,OAAe;YACtB,IAAI,IAAY,CAAA;YAChB,IAAI,CAAC;gBACD,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,CAAA;YAChD,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACb,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;oBAAE,OAAO,SAAS,CAAA;gBACxE,MAAM,KAAK,CAAA;YACf,CAAC;YACD,IAAI,CAAC;gBACD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAoB,CAAA;YAC9C,CAAC;YAAC,MAAM,CAAC;gBACL,2GAA2G;gBAC3G,MAAM,IAAI,KAAK,CAAC,0BAA0B,IAAI,CAAC,OAAO,CAAC,oBAAoB,CAAC,CAAA;YAChF,CAAC;QACL,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,OAAe,EAAE,QAAyB;YACjD,MAAM,KAAK,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAA;YACnD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,CAAA;YAC5B,MAAM,SAAS,GAAG,GAAG,MAAM,IAAI,UAAU,EAAE,MAAM,CAAA;YACjD,IAAI,CAAC;gBACD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,KAAK,CAAC,CAAA;gBACjD,IAAI,CAAC;oBACD,MAAM,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAA;oBAChD,MAAM,MAAM,CAAC,IAAI,EAAE,CAAA;gBACvB,CAAC;wBAAS,CAAC;oBACP,MAAM,MAAM,CAAC,KAAK,EAAE,CAAA;gBACxB,CAAC;gBACD,MAAM,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAA;YACnC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACb,MAAM,EAAE,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;oBAC5C,8GAA8G;gBAClH,CAAC,CAAC,CAAA;gBACF,MAAM,KAAK,CAAA;YACf,CAAC;QACL,CAAC;KACJ,CAAC,CAAA;AACN,CAAC"}