lunibee 0.3.2 → 0.4.0

package/dist/sharding/leader.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Leadership between several coordinators, so a standby `ClusterManager` can
+ * take over when the active one dies. Only the holder of the lock runs
+ * clusters; see `ClusterManagerOptions.leader`.
+ */
+export interface LeaderLock {
+    /**
+     * Takes the lock for `ttlMs`, or extends it when this process already
+     * holds it. Resolves `true` while this process is the leader, `false` when
+     * another one holds it. A rejection counts as "unknown".
+     */
+    acquire(ttlMs: number): Promise<boolean>;
+    /** Gives the lock up if this process holds it. */
+    release(): Promise<void>;
+}
+/** The part of a Redis client the lock uses. `Bun.RedisClient` works as it is; for ioredis pass `{ send: (c, a) => redis.call(c, ...a) }`. */
+export interface LeaderRedisClient {
+    send(command: string, args: string[]): Promise<unknown>;
+}
+/** Options for {@link RedisLeaderLock}. */
+export interface RedisLeaderLockOptions {
+    client: LeaderRedisClient;
+    /** The key every coordinator of one deployment shares. Default `lunibee:cluster:leader`. */
+    key?: string;
+    /** This coordinator's identity in the key. Default: a random UUID. Must differ between coordinators. */
+    token?: string;
+}
+/** A {@link LeaderLock} on one Redis key, with an expiry so a dead leader's lock lapses on its own. */
+export declare class RedisLeaderLock implements LeaderLock {
+    #private;
+    constructor(options: RedisLeaderLockOptions);
+    acquire(ttlMs: number): Promise<boolean>;
+    release(): Promise<void>;
+}

package/dist/sharding/remote.d.ts

@@ -62,6 +62,14 @@ export interface RemoteOptions {
     clientAddress?: (request: Request, peer: string | undefined) => string;
     /** Also run clusters on the coordinator's own machine. Default false: clusters run on the hosts only. */
     local?: boolean;
+    /**
+     * When a host is lost, restart its clusters on the connected host (or
+     * `local`) running the fewest, once the lost host has certainly fenced
+     * itself (two leases after the coordinator dropped it). They stay there
+     * when the host comes back. Default true; `false` restarts them on the
+     * same host only, so they wait for it.
+     */
+    moveClusters?: boolean;
 }
 /** A host as the coordinator sees it. */
 export interface HostStatus {
@@ -115,6 +123,16 @@ export declare class RemoteHosts {
     get port(): number | undefined;
     /** Host IDs that are connected now, sorted. */
     connected(): string[];
+    /** Whether `hostId` is connected now. */
+    isConnected(hostId: string): boolean;
+    /**
+     * When workers that ran on a lost host are certainly gone (epoch ms), or 0
+     * for a host that is connected or was never dropped. The host fences
+     * itself one lease after it last heard from the coordinator, checking
+     * every third of a lease; the coordinator sends nothing after the drop,
+     * and two leases leave room for the kill itself.
+     */
+    fencedAt(hostId: string): number;
     /** Opens the listener. Safe to call twice. */
     start(): void;
     /** Closes the listener and every host connection. */

package/dist/sharding/supervisor.d.ts

@@ -8,9 +8,9 @@ export interface SupervisorOptions {
     maxDelay?: number;
     /** Random spread added to each delay, as a fraction of it (0-1, default 0). */
     jitter?: number;
-    /** Give up after this many restarts inside `window` (default unlimited). */
+    /** Give up after this many restarts without a stable `window` between them (default unlimited). */
     maxRestarts?: number;
-    /** The time over which restarts are counted, and after which a stable cluster is forgiven (default 60,000). */
+    /** How long a restarted cluster must run before its earlier crashes are forgiven (default 60,000). */
     window?: number;
 }
 /**
@@ -27,6 +27,8 @@ export declare class ShardSupervisor {
      * `maxRestarts` times inside `window`.
      */
     next(id: number, now?: number): number | null;
+    /** Restarts of a cluster since it last ran stably for a whole `window`. */
+    attempts(id: number): number;
     /** Forgets a cluster's crashes, e.g. after a deliberate respawn. */
     reset(id?: number): void;
 }

package/dist/sharding/thread.d.ts

@@ -0,0 +1,30 @@
+import type { ChildProcess } from "node:child_process";
+import { type ResourceLimits } from "node:worker_threads";
+/** Options for {@link threadFork}. */
+export interface ThreadForkOptions {
+    /** Heap limits for each cluster thread (`worker_threads` `resourceLimits`). */
+    resourceLimits?: ResourceLimits;
+}
+/**
+ * Runs each cluster as a worker thread of the manager's process instead of a
+ * forked process: pass it as `ClusterManager`'s `fork`. Threads start faster
+ * and use less memory; a crash that takes the process down (an out-of-memory
+ * abort, a native fault) takes every cluster with it. The worker script is the
+ * same: `ShardManager`, `ShardBus` and `ClusterWorker` find the parent through
+ * `parentPort`.
+ */
+export declare function threadFork(options?: ThreadForkOptions): (script: string, env: Record<string, string | undefined>) => ChildProcess;
+/** The parent link of a cluster thread: the part of `process` a worker uses. */
+export interface ThreadEndpoint {
+    send(message: unknown): boolean;
+    on(event: string, listener: (...args: never[]) => void): ThreadEndpoint;
+    off(event: string, listener: (...args: never[]) => void): ThreadEndpoint;
+}
+/** The parent link when this code runs in a cluster thread started by {@link threadFork}, otherwise `undefined`. */
+export declare function threadEndpoint(): ThreadEndpoint | undefined;
+/** Wraps a message port as a worker endpoint. @internal */
+export declare function portEndpoint(port: {
+    postMessage(message: unknown): void;
+    on(event: "message", listener: (frame: unknown) => void): unknown;
+    off(event: "message", listener: (frame: unknown) => void): unknown;
+}): ThreadEndpoint;

package/dist/structures/audit-log.d.ts

@@ -1,5 +1,5 @@
 import { BaseStructure } from "./base.js";
-import type { APIAuditLog, APIAuditLogEntry, APIAuditLogChange, APIAuditLogOptions } from "@lunibee/types";
+import type { APIAuditLog, APIAuditLogEntry, APIAuditLogChange, APIAuditLogOptions } from "../types/index.js";
 /** What `info` holds for each action type that carries extra details (numbers are parsed from Discord's strings). */
 export interface AuditLogInfoByType {
     /** Overwrite created, updated or deleted: a role (`type` 0) or a member (`type` 1). */

package/dist/structures/base.d.ts

@@ -1,4 +1,4 @@
-import { type ChannelKind, type MessageCreateOptions, type MessageEditOptions, type UnknownChannelKind } from "@lunibee/types";
+import { type ChannelKind, type MessageCreateOptions, type MessageEditOptions, type UnknownChannelKind } from "../types/index.js";
 import type { ChannelOfKind } from "./channels.js";
 /** Common Discord snowflake-backed structure. */
 export declare class BaseStructure {
@@ -42,7 +42,7 @@ export interface ResourceContext {
     addMemberRole?(guildId: string, userId: string, roleId: string, reason?: string): Promise<void>;
     removeMemberRole?(guildId: string, userId: string, roleId: string, reason?: string): Promise<void>;
     /** Collects the client's interactions (a `Collector` over `interactionCreate`). Used by message and interaction collectors. */
-    collectInteractions?(options: import("@lunibee/core").CollectorOptions<import("./interactions.js").Interaction>): import("@lunibee/core").Collector<string, import("./interactions.js").Interaction>;
+    collectInteractions?(options: import("../core/index.js").CollectorOptions<import("./interactions.js").Interaction>): import("../core/index.js").Collector<string, import("./interactions.js").Interaction>;
     editPermissionOverwrite?(channelId: string, targetId: string, changes: PermissionOverwriteChanges, options?: {
         type?: 0 | 1;
         reason?: string;
@@ -73,7 +73,7 @@ export declare class User extends BaseStructure {
     system: boolean;
     flags: number;
     discriminator: string | null;
-    constructor(data: import("@lunibee/types").UserData);
+    constructor(data: import("../types/index.js").UserData);
     /** Effective display name — global name, falling back to username. */
     get displayName(): string;
     /** Returns the user's avatar URL, or null if they have no avatar. */
@@ -96,7 +96,7 @@ export declare class Channel extends BaseStructure {
     rateLimitPerUser?: number;
     position?: number;
     /** Role and member permission overwrites (empty for DMs and when not provided). */
-    permissionOverwrites: import("@lunibee/types").APIOverwrite[];
+    permissionOverwrites: import("../types/index.js").APIOverwrite[];
     /**
      * A placeholder built from a message's `channel_id`, not from channel
      * data: its `type`, `name`, `parentId` and `permissionOverwrites` are not
@@ -104,7 +104,7 @@ export declare class Channel extends BaseStructure {
      */
     partial: boolean;
     /** Creates a channel structure from Discord channel data. `options.partial` marks a placeholder. */
-    constructor(data: import("@lunibee/types").APIChannel, context?: ResourceContext, options?: {
+    constructor(data: import("../types/index.js").APIChannel, context?: ResourceContext, options?: {
         partial?: boolean;
     });
     /** Sends a message to this channel. @param options Message payload. @returns The created message. @throws {Error} If the channel is not attached to a client. */
@@ -207,7 +207,7 @@ export declare class Guild extends BaseStructure {
     maxVideoChannelUsers?: number;
     /** Whether the boost progress bar shows. */
     premiumProgressBarEnabled: boolean;
-    constructor(data: import("@lunibee/types").APIGuild);
+    constructor(data: import("../types/index.js").APIGuild);
     /** Returns the guild icon URL, or null if no icon is set. */
     iconURL(options?: ImageURLOptions): string | null;
     /** Returns the guild splash URL, or null if none. */

package/dist/structures/channels.d.ts

@@ -1,6 +1,6 @@
 import { Channel, User, type ResourceContext } from "./base.js";
 import { TextChannel } from "./resources.js";
-import type { APIChannel, APIForumTag, APIPartialEmoji, APIThreadMetadata } from "@lunibee/types";
+import type { APIChannel, APIForumTag, APIPartialEmoji, APIThreadMetadata } from "../types/index.js";
 /** A guild announcement (news) channel. */
 export declare class NewsChannel extends TextChannel {
 }

package/dist/structures/embed.d.ts

@@ -1,4 +1,4 @@
-import type { APIEmbed, APIEmbedAuthor, APIEmbedField, APIEmbedFooter, APIEmbedMedia } from "@lunibee/types";
+import type { APIEmbed, APIEmbedAuthor, APIEmbedField, APIEmbedFooter, APIEmbedMedia } from "../types/index.js";
 /**
  * A rich Embed structure that wraps a Discord API embed object.
  * Provides typed accessors and a fluent builder interface.

package/dist/structures/index.d.ts

@@ -1,9 +1,9 @@
 /** Resource structures for Discord messages and related entities. */
-import type { MessageCreateOptions, MessageEditOptions } from "@lunibee/types";
+import type { MessageCreateOptions, MessageEditOptions } from "../types/index.js";
 import { BaseStructure, Channel, User } from "./base.js";
 import { GuildMember } from "./resources.js";
 import type { ComponentInteraction } from "./interactions.js";
-import type { Collector, CollectorOptions } from "@lunibee/core";
+import type { Collector, CollectorOptions } from "../core/index.js";
 /** Options for {@link Message.createComponentCollector}. */
 export interface ComponentCollectorOptions extends CollectorOptions<ComponentInteraction> {
     /** Only this component type (2 button, 3 string select...). */
@@ -22,22 +22,22 @@ export declare class Message extends BaseStructure {
     flags: number;
     /** Message creation timestamp (from timestamp field or snowflake). */
     readonly timestamp: Date;
-    readonly attachments: import("@lunibee/types").APIAttachment[];
-    readonly embeds: import("@lunibee/types").APIEmbed[];
+    readonly attachments: import("../types/index.js").APIAttachment[];
+    readonly embeds: import("../types/index.js").APIEmbed[];
     readonly mentions: User[];
     readonly mentionRoles: string[];
     pinned: boolean;
     mentionEveryone: boolean;
     type: number;
-    readonly reference?: import("@lunibee/types").APIMessageReference;
-    readonly components: import("@lunibee/types").APIMessageComponent[];
+    readonly reference?: import("../types/index.js").APIMessageReference;
+    readonly components: import("../types/index.js").APIMessageComponent[];
     readonly referencedMessage?: Message | null;
     /** Stickers sent with the message (`sticker_items`). */
-    readonly stickers: import("@lunibee/types").APIStickerItem[];
+    readonly stickers: import("../types/index.js").APIStickerItem[];
     /** The poll, when the message is one. */
-    readonly poll: import("@lunibee/types").APIPoll | null;
+    readonly poll: import("../types/index.js").APIPoll | null;
     /** For a forwarded message, the snapshot of the original. */
-    readonly messageSnapshots: import("@lunibee/types").APIMessageSnapshot[];
+    readonly messageSnapshots: import("../types/index.js").APIMessageSnapshot[];
     /**
      * The author as a guild member, on guild messages from the Gateway. Its
      * `permissions` are computed from the cached roles; `member.kick()` and the
@@ -45,13 +45,13 @@ export declare class Message extends BaseStructure {
      */
     member: GuildMember | null;
     /** Creates a message structure from Discord message data. */
-    constructor(data: import("@lunibee/types").APIMessage, context?: ResourceContext);
+    constructor(data: import("../types/index.js").APIMessage, context?: ResourceContext);
     /** Whether embeds are suppressed on this message. */
     get embedsSuppressed(): boolean;
-    /** Unix timestamp (ms) at which the message was created — discord.js parity.
+    /** Unix timestamp (ms) at which the message was created.
      * Derived from the message `timestamp`, which itself falls back to the id snowflake. */
     get createdTimestamp(): number;
-    /** Date at which the message was created — discord.js parity. Overrides the
+    /** Date at which the message was created. Overrides the
      * snowflake-only `BaseStructure.createdAt` to honour the message `timestamp`. */
     get createdAt(): Date;
     /** Edits this message. @param options Message fields to change. @returns The updated message. @throws {Error} If the message is not attached to a client. */
@@ -93,8 +93,8 @@ export declare class Message extends BaseStructure {
     get isEphemeral(): boolean;
     /** Whether this message is currently pinned in its channel. */
     get isPinned(): boolean;
-    /** Whether this is a system-generated message (join, boost, etc). Mirrors
-     * discord.js: a message is "system" unless its type is one of the user-authored
+    /** Whether this is a system-generated message (join, boost, etc).
+     * A message is "system" unless its type is one of the user-authored
      * types — Default (0), Reply (19), ChatInputCommand (20) or ContextMenuCommand (23). */
     get isSystemMessage(): boolean;
     /** Whether this message was crossposted from an announcement channel. */