Caching

CacheChange#

interface CacheChange

// A set can replace an entry and a clear releases a whole kind, so track keys rather than counting events
export function trackCachedKeys(client, keys) {
    return client.cache.onChange((change) => {
        const kindKeys = keys.get(change.kind) ?? new Set()
        keys.set(change.kind, kindKeys)
        if (change.op === "clear")
            kindKeys.clear()
        else if (change.key !== null && change.op === "set")
            kindKeys.add(change.key)
        else if (change.key !== null)
            kindKeys.delete(change.key)
    })
}

import type { Client } from "@neontechspace/fluxerly"
// A set can replace an entry and a clear releases a whole kind, so track keys rather than counting events
export function trackCachedKeys(client: Client, keys: Map<string, Set<string>>) {
    return client.cache.onChange((change) => {
        const kindKeys = keys.get(change.kind) ?? new Set<string>()
        keys.set(change.kind, kindKeys)
        if (change.op === "clear") kindKeys.clear()
        else if (change.key !== null && change.op === "set") kindKeys.add(change.key)
        else if (change.key !== null) kindKeys.delete(change.key)
    })
}

key#

Entry key in the format described for this kind, or null for a clear

string | null

kind#

Cache category whose local copy changed

CacheKind

op#

What happened to the local copy

The value set means an entry was stored or replaced, even with identical content. The value delete means one entry was removed, including removal by cache.delete(), expiry, capacity eviction, an event, a write or a connection gap limited to known communities. The value clear means every entry of this kind was released at once, as by cache.clear() with or without this kind, shutdown, a connection gap of unknown scope or an event or write whose effect cannot be narrowed to single entries. No delete is reported for the entries a clear released

"set" | "clear" | "delete"

CacheDiagnostic#

interface CacheDiagnostic

accountedBytes#

Accounted UTF-8 JSON bytes of retained snapshots, excluding JavaScript overhead and caller-held copies

number

configured#

Whether this category was configured when the client was created

A Closing/Closed client accepts no further snapshots

boolean

evictions#

Snapshots this category removed on its own, by reason

Removal by events, writes, cache.delete, clears, connection gaps and shutdown is not counted

capacity

Least recently used snapshots removed to make room within maxEntries or maxBytes

number

expiry

Snapshots removed because their maxAgeMs passed

number

hits#

Local lookups, such as client.messages.get, that returned a snapshot, including lookups the SDK makes itself

number

maxBytes#

Configured client-wide accounted-byte bound, or null when this category was disabled

number | null

maxEntries#

Configured client-wide entry bound, or null when this category was disabled

number | null

misses#

Local lookups that found no snapshot, including one that had just expired

number

retainedEntries#

Snapshots still held by the SDK after expired entries are removed

number

CacheEntriesOptions#

interface CacheEntriesOptions

limit optional#

Maximum snapshots to return, from 1 through 1,000, default 100

number

CacheObserver#

interface CacheObserver

id#

Identifier of this observer, such as cacheChange#3, used in its log records

string

[dispose](): void

close(): void

CacheObserverOptions#

interface CacheObserverOptions

// One call at a time, so asynchronous work sees the changes in the order they were applied
export function saveChangesInOrder(client, save) {
    return client.cache.onChange((change) => save(change.key), { concurrency: 1, maxPendingChanges: 1_000 })
}

import type { Client } from "@neontechspace/fluxerly"
// One call at a time, so asynchronous work sees the changes in the order they were applied
export function saveChangesInOrder(client: Client, save: (key: string | null) => Promise<void>) {
    return client.cache.onChange((change) => save(change.key), { concurrency: 1, maxPendingChanges: 1_000 })
}

concurrency optional#

Maximum unfinished listener calls, a positive safe integer, default 256

Later changes wait in the order they were applied until a call finishes

number

maxPendingChanges optional#

Maximum changes waiting for an unfinished call, a positive safe integer, default 256

A change that arrives while this many wait drops the oldest waiting change, logs a cache.changesDropped Warn with the observer's id and how many changes it has dropped, and counts the drop in diagnostics().counters.cacheChangesDropped

number

CachedResources#

interface CachedResources<M extends MessageCore = Message>interface CachedResources<
  M extends MessageCore = Message
>

channels#

Community channels, distinct from private conversations

GuildChannel

directMessages#

Direct-message and group direct-message conversations

DirectMessageChannel

emojis#

Community emoji metadata, not image bytes

GuildEmoji

guilds#

Community identity and settings, without a preloaded member or role list

Guild

members#

Individual community memberships

GuildMember

messages#

Messages encountered by eligible REST calls or gateway events

M

roles#

Community role definitions

GuildRole

stickers#

Community sticker metadata, not image bytes

GuildSticker

users#

Public account profiles, not partial message authors

User

ClientCache#

interface ClientCache<M extends MessageCore = Message>interface ClientCache<
  M extends MessageCore = Message
>

clear(kind?: CacheKind): void

delete(kind: CacheKind, key: string): voiddelete(
  kind: CacheKind,
  key: string
): void

export function forgetMember(client, guildId, userId) {
    client.cache.delete("members", `${guildId}:${userId}`)
}

import type { Client } from "@neontechspace/fluxerly"
export function forgetMember(client: Client, guildId: string, userId: string) {
    client.cache.delete("members", `${guildId}:${userId}`)
}

entries<K extends CacheKind>(
    kind: K,
    options?: CacheEntriesOptions
): readonly CachedResources<M>[K][]entries<K extends CacheKind>(
  kind: K,
  options?: CacheEntriesOptions
): readonly CachedResources<M>[K][]

onChange(
    listener: (change: CacheChange) => unknown,
    options?: CacheObserverOptions
): CacheObserveronChange(
  listener: (change: CacheChange)
    => unknown,
  options?: CacheObserverOptions
): CacheObserver

export function cacheChangesExample(client, forget) {
    return client.cache.onChange((change) => {
        if (change.kind === "members" && change.op === "delete" && change.key !== null)
            forget(change.key)
    })
}

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)
    })
}

MessageCacheOptions#

interface MessageCacheOptions<M extends MessageCore = Message>
    extends MessageCacheSettings<M>interface MessageCacheOptions<
  M extends MessageCore = Message
>
  extends MessageCacheSettings<M>

Inherited from MessageCacheSettings: maxAgeMs, maxBytes, maxEntries

MessageCacheSettings#

interface MessageCacheSettings<M extends MessageCore = Message>interface MessageCacheSettings<
  M extends MessageCore = Message
>

maxAgeMs optional#

How long to keep each accepted snapshot, in milliseconds, or a synchronous function that chooses that duration

Use a nonnegative safe integer, zero to skip retention, or null to disable age expiry. Omitting this setting also disables age expiry

number | ((message: M) => number | null) | null| number
| ((message: M) => number | null)
| null

The function receives the frozen message with this client's selected fields and must return a duration or null. A throw, undefined, Promise, thenable or invalid number removes the older copy and reports a cache failure with the thrown value or an explanation. Message delivery and successful REST results still succeed when the policy fails. The SDK does not await or cancel invalid promises and thenables

Each eligible replacement starts a new age, even when values are unchanged. Local lookups change eviction order but do not renew age. Expiry removes SDK references without a lookup, although event-loop stalls can delay cleanup and garbage collection is not immediate. Capacity limits can remove a snapshot before its age limit

Keep the function nonblocking and side-effect-free, since it runs while the SDK accepts an observation. Changing state captured by the function affects later observations only

Removing a cache entry does not delete persistent data or securely erase memory

maxBytes optional#

Maximum UTF-8 JSON bytes of retained messages with this client's selected fields, as a positive safe integer

Defaults to 8,388,608 (8 MiB) and excludes runtime overhead and caller-held copies

number

maxEntries optional#

Maximum messages kept across this client, as a positive safe integer

Defaults to 1,000, not a separate allowance per channel

number

ResourceCacheSettings#

interface ResourceCacheSettings<T = unknown>interface ResourceCacheSettings<
  T = unknown
>

maxAgeMs optional#

How long to keep each accepted snapshot, in milliseconds, or a synchronous function that chooses that duration

Use a nonnegative safe integer, zero to skip retention, or null to disable age expiry. Omitting this setting also disables age expiry

number | ((resource: T) => number | null) | null| number
| ((resource: T) => number | null)
| null

The function receives the frozen snapshot and must return a duration or null, so it can cache selectively, for example by returning zero for snapshots of communities or channels the application does not need. A throw, undefined, Promise, thenable or invalid number removes the older copy and reports a cache failure with the thrown value or an explanation. That failure goes to the client-level onError option as a cache FailureReport, or is logged at Error with the thrown value when no hook is set. Event delivery and successful REST results still succeed when the policy fails. The SDK does not await or cancel invalid promises and thenables

Each eligible replacement starts a new age, even when values are unchanged. Local lookups do not renew age, and expiry removes SDK references without fetching a replacement. Expiry runs without a lookup and can be delayed by an event-loop stall. Capacity limits can remove a snapshot before its age limit

Keep the function nonblocking and side-effect-free, since it runs while the SDK accepts an observation. Changing state captured by the function affects later observations only

maxBytes optional#

Maximum accounted UTF-8 JSON bytes kept for this category, as a positive safe integer

Defaults to 4,194,304 (4 MiB), separate from the message-cache byte budget. Permission bitfields are counted as decimal strings. Cache keys, runtime overhead and caller-held copies are excluded, so this is not an exact heap or process-memory limit

number

maxEntries optional#

Maximum snapshots kept for this category across the client, as a positive safe integer

Defaults to 1,000, not a limit per community

number

CacheKind#

type CacheKind =
    | "messages" | "guilds" | "members" | "roles" | "channels"
    | "users" | "directMessages" | "emojis" | "stickers"type CacheKind =
    | "messages" | "guilds"
    | "members" | "roles"
    | "channels" | "users"
    | "directMessages" | "emojis"
    | "stickers"