@neontechspace/fluxerly 1000.0.0-nightly.12

package/dist/internal/cache-changes.js

@@ -0,0 +1,320 @@
+/**
+ * Cache change notifications: One client-wide hub that every client-owned cache reports set, delete and clear changes to.
+ * Invariant: Notification never changes a cache result, event delivery or REST outcome. Caches only record a change after
+ * applying it and build no record while no observer is registered. Records are delivered in applied order from a microtask
+ * after the synchronous cache work that produced them, so a listener never runs inside a cache operation, and a failing
+ * listener is reported as a cache failure without affecting other listeners. Each listener holds at most its concurrency
+ * of unfinished calls and its maxPendingChanges of waiting changes, and a full queue drops its oldest change with a logged
+ * and counted Warn, so a stuck listener cannot grow memory. Client closure hands the final clears to listeners with a free
+ * call, then closes every observer without waiting for unfinished calls, dropping the changes still waiting with the same
+ * logged and counted Warn. Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import { ConfigurationError } from "#sdk/errors";
+import { localValue } from "#sdk/internal/binding/execute";
+import { record as isRecord } from "./decode/primitives.js";
+import { suspendInput } from "./defects.js";
+import { throwIfErr } from "./failures.js";
+import { unsupportedKeyHint } from "./suggest.js";
+/** Client-wide cache change fan-out. Caches call record after applying a change */
+export class CacheChangeHub {
+    #observers = new Set();
+    #queue = [];
+    #sequence = 0;
+    #ids = 0;
+    #scheduled = false;
+    #closed = false;
+    #watching = false;
+    /** Whether any listener is registered, so caches can skip building change records */
+    get active() {
+        return this.#observers.size > 0;
+    }
+    /** Queue one applied change for the registered listeners. Never runs a listener inline and never throws */
+    record(kind, op, key) {
+        if (this.#observers.size === 0)
+            return;
+        this.#queue.push({ sequence: ++this.#sequence, change: Object.freeze({ kind, op, key }) });
+        if (this.#scheduled)
+            return;
+        this.#scheduled = true;
+        queueMicrotask(() => this.#flush());
+    }
+    #flush() {
+        this.#scheduled = false;
+        // Changes a listener causes are appended to a fresh queue and delivered by this same loop, in applied order
+        while (this.#queue.length) {
+            const batch = this.#queue;
+            this.#queue = [];
+            for (const { sequence, change } of batch)
+                for (const observer of this.#observers)
+                    if (observer.since < sequence)
+                        observer.deliver(change);
+        }
+    }
+    /** A new observer identifier, also given to registrations after closure */
+    nextId() {
+        return `cacheChange#${++this.#ids}`;
+    }
+    /** Register an observer, or return undefined after client closure, when no further change can occur */
+    add(create) {
+        if (this.#closed)
+            return undefined;
+        const observer = create(this.#sequence);
+        this.#observers.add(observer);
+        return observer;
+    }
+    remove(observer) {
+        this.#observers.delete(observer);
+        if (this.#observers.size === 0)
+            this.#queue = [];
+    }
+    /** Close every observer once its owner client closes. Watching starts with the first registration */
+    watch(owner) {
+        if (this.#watching)
+            return;
+        this.#watching = true;
+        owner.subscribe((state) => {
+            if (state === "Closed")
+                this.close();
+        });
+    }
+    /**
+     * Deliver the changes already recorded, including shutdown's final clears, then close every observer. A listener
+     * at its concurrency keeps them waiting, so its observer drops them with a Warn rather than holding shutdown
+     */
+    close() {
+        if (this.#closed)
+            return;
+        this.#flush();
+        this.#closed = true;
+        for (const observer of this.#observers)
+            observer.close();
+        this.#observers.clear();
+        this.#queue = [];
+    }
+}
+const boundKeys = ["concurrency", "maxPendingChanges"];
+/** The validated onChange options, each read once. A throwing read dies as an application fault */
+const observerBounds = (options) => suspendInput(() => {
+    if (options === undefined)
+        options = {};
+    if (!isRecord(options))
+        return Effect.fail(new ConfigurationError("cacheObserverOptions", "Cache observer options must be an object"));
+    const unsupported = Object.keys(options).find((key) => !boundKeys.includes(key));
+    if (unsupported !== undefined)
+        return Effect.fail(new ConfigurationError("cacheObserverOptions", `Unsupported option ${JSON.stringify(unsupported)} in the cache observer options`, { hint: unsupportedKeyHint(unsupported, boundKeys) }));
+    const bounds = { concurrency: 256, maxPendingChanges: 256 };
+    for (const key of boundKeys) {
+        const value = options[key];
+        if (value === undefined)
+            continue;
+        if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0)
+            return Effect.fail(new ConfigurationError(key, `The cache observer option ${JSON.stringify(key)} must be a positive safe integer`));
+        bounds[key] = value;
+    }
+    return Effect.succeed(bounds);
+});
+/**
+ * Bounded delivery to one listener: At most concurrency calls are unfinished, later changes wait in applied order, and a
+ * change arriving while maxPendingChanges wait drops the oldest waiting change with a counted Warn
+ */
+class ListenerQueue {
+    id;
+    bounds;
+    logger;
+    start;
+    #running = 0;
+    #waiting = [];
+    #dropped = 0;
+    #draining = false;
+    #open = true;
+    constructor(id, bounds, logger, 
+    /** Start one listener call. It never throws and calls done once that call has finished */
+    start) {
+        this.id = id;
+        this.bounds = bounds;
+        this.logger = logger;
+        this.start = start;
+    }
+    deliver(change) {
+        if (!this.#open)
+            return;
+        if (this.#running < this.bounds.concurrency && this.#waiting.length === 0) {
+            this.#run(change);
+            return;
+        }
+        if (this.#waiting.length >= this.bounds.maxPendingChanges) {
+            this.#waiting.shift();
+            this.#drop();
+        }
+        this.#waiting.push(change);
+    }
+    /**
+     * Stop delivery and discard waiting changes. At client shutdown, which never waits for unfinished calls, the
+     * discarded changes are logged and counted as drops
+     */
+    close(shutdown = false) {
+        this.#open = false;
+        const discarded = this.#waiting.length;
+        this.#waiting = [];
+        if (!shutdown || discarded === 0)
+            return;
+        this.#dropped += discarded;
+        const { concurrency } = this.bounds;
+        this.logger.count("cacheChangesDropped", discarded);
+        this.logger.log({
+            level: "warn",
+            category: "cache",
+            code: "cache.changesDropped",
+            message: `The client shut down while ${discarded} ${discarded === 1 ? "change" : "changes"} waited for the cache.onChange listener ${this.id}, which had ${concurrency} unfinished ${concurrency === 1 ? "call" : "calls"} (concurrency), so ${discarded === 1 ? "it was" : "they were"} dropped`,
+            subscriptionId: this.id,
+            fields: { dropped: this.#dropped, concurrency, maxPendingChanges: this.bounds.maxPendingChanges },
+        });
+    }
+    #run(change) {
+        this.#running++;
+        let finished = false;
+        this.start(change, () => {
+            if (finished)
+                return;
+            finished = true;
+            this.#running--;
+            this.#drain();
+        });
+    }
+    /** Start waiting changes while calls are free. Calls that finish synchronously continue this loop rather than nest */
+    #drain() {
+        if (this.#draining)
+            return;
+        this.#draining = true;
+        try {
+            while (this.#open && this.#running < this.bounds.concurrency && this.#waiting.length)
+                this.#run(this.#waiting.shift());
+        }
+        finally {
+            this.#draining = false;
+        }
+    }
+    #drop() {
+        this.#dropped++;
+        const { concurrency, maxPendingChanges } = this.bounds;
+        // The message stays the same for every drop, so repeats collapse while fields.dropped carries the latest total
+        this.logger.drop("cacheChangesDropped", {
+            level: "warn",
+            category: "cache",
+            code: "cache.changesDropped",
+            message: `The cache.onChange listener ${this.id} has ${concurrency} unfinished ${concurrency === 1 ? "call" : "calls"} (concurrency) and ${maxPendingChanges} waiting ${maxPendingChanges === 1 ? "change" : "changes"} (maxPendingChanges), so the oldest waiting change was dropped`,
+            subscriptionId: this.id,
+            fields: { dropped: this.#dropped, concurrency, maxPendingChanges },
+        });
+    }
+}
+/** A listener's failure as a client cache report. Reporting never throws */
+function reportFailure(owner, input) {
+    owner.failures.report({ kind: "cache", ...input });
+}
+const closedObserver = (id) => Object.freeze({ id, close: () => undefined, [Symbol.dispose]: () => undefined });
+/** Default-API cache.onChange: Listeners run from a microtask, and returned promises are observed but not awaited */
+export const defaultCacheOnChange = ({ owner }) => (listener, options) => {
+    if (typeof listener !== "function")
+        throw new ConfigurationError("listener", "Cache change listener must be a function");
+    const bounds = localValue(observerBounds(options), "cache.onChange");
+    const hub = owner.cacheChanges;
+    hub.watch(owner);
+    const id = hub.nextId();
+    const report = (error) => reportFailure(owner, { error });
+    const queue = new ListenerQueue(id, bounds, owner.logging, (change, done) => {
+        let settled;
+        try {
+            const result = listener(change);
+            if (typeof result === "object" &&
+                result !== null &&
+                typeof result.then === "function")
+                settled = Promise.resolve(result).then(throwIfErr);
+            else
+                throwIfErr(result);
+        }
+        catch (error) {
+            report(error);
+        }
+        if (settled === undefined)
+            done();
+        else
+            void settled.catch(report).then(done);
+    });
+    let open = true;
+    const observer = hub.add((since) => ({
+        since,
+        deliver: (change) => queue.deliver(change),
+        // The hub closes observers only at client shutdown
+        close: () => {
+            open = false;
+            queue.close(true);
+        },
+    }));
+    if (!observer)
+        return closedObserver(id);
+    const close = () => {
+        if (!open)
+            return;
+        open = false;
+        queue.close();
+        hub.remove(observer);
+    };
+    return Object.freeze({ id, close, [Symbol.dispose]: close });
+};
+/** Native cache.onChange: Each change forks the listener Effect with the registration services, closed with its Scope */
+export const nativeCacheOnChange = (owner) => (listener, options) => Effect.gen(function* () {
+    if (typeof listener !== "function")
+        return yield* Effect.die(new ConfigurationError("listener", "Cache change listener must be a function"));
+    // Invalid options are misuse, so they become a defect rather than a typed failure
+    const bounds = yield* observerBounds(options).pipe(Effect.orDie);
+    const services = (yield* Effect.context());
+    const hub = owner.cacheChanges;
+    const id = hub.nextId();
+    const close = yield* Effect.acquireRelease(Effect.sync(() => {
+        hub.watch(owner);
+        const running = new Set();
+        const queue = new ListenerQueue(id, bounds, owner.logging, (change, done) => {
+            try {
+                const fiber = Effect.runForkWith(services)(Effect.suspend(() => listener(change)));
+                running.add(fiber);
+                fiber.addObserver((exit) => {
+                    running.delete(fiber);
+                    if (Exit.isFailure(exit) && !Cause.hasInterruptsOnly(exit.cause))
+                        reportFailure(owner, { cause: exit.cause });
+                    done();
+                });
+            }
+            catch (error) {
+                reportFailure(owner, { error });
+                done();
+            }
+        });
+        let open = true;
+        const stop = (shutdown = false) => {
+            if (!open)
+                return;
+            open = false;
+            queue.close(shutdown);
+            for (const fiber of running)
+                fiber.interruptUnsafe();
+            running.clear();
+        };
+        const observer = hub.add((since) => ({
+            since,
+            deliver: (change) => queue.deliver(change),
+            // The hub closes observers only at client shutdown
+            close: () => stop(true),
+        }));
+        return () => {
+            stop();
+            if (observer)
+                hub.remove(observer);
+        };
+    }), (close) => Effect.sync(close));
+    return Object.freeze({ id, close: () => Effect.sync(close) });
+});
+//# sourceMappingURL=cache-changes.js.map

package/dist/internal/cache-changes.js.map

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

package/dist/internal/cache.d.ts

@@ -0,0 +1,57 @@
+import type { CacheDiagnostic } from "#sdk/client";
+import type { Message, MessageCore, MessageReference } from "#sdk/messages";
+import type { CacheConfiguration } from "./configuration.js";
+import type { LogicalScheduler } from "./logical-scheduler.js";
+import type { CacheChangeHub } from "./cache-changes.js";
+export type CacheRequest = {
+    readonly channel: string;
+    readonly id: string | undefined;
+    readonly mutation: boolean;
+    readonly generation: number;
+    invalid: boolean;
+};
+/** Running lookup and eviction totals of one cache category, copied into its CacheDiagnostic */
+export type CacheStats = {
+    hits: number;
+    misses: number;
+    evictions: {
+        capacity: number;
+        expiry: number;
+    };
+};
+export declare const cacheStats: () => CacheStats;
+/** A diagnostic copy of the totals, which keep counting after it is taken */
+export declare const readStats: (stats: CacheStats) => CacheStats;
+/** One client's retained observations and bounded in-flight guards, never a server-state replica */
+export declare class MessageCache<M extends MessageCore = Message> {
+    #private;
+    private settings;
+    private report;
+    private readonly now;
+    readonly changes?: CacheChangeHub | undefined;
+    constructor(settings: CacheConfiguration<M> | undefined, report: (error: unknown, message: MessageCore) => void, now: () => number, logical?: LogicalScheduler, changes?: CacheChangeHub | undefined);
+    get generation(): number;
+    diagnostics(): CacheDiagnostic;
+    entries(limit: number): readonly M[];
+    /** Release only this client's retained snapshots and block reads that began before this point from refilling them */
+    clear(): void;
+    get(target: MessageReference): M | undefined;
+    begin(channel: string, id: string | undefined, mutation: boolean, generation: number): CacheRequest;
+    end(request: CacheRequest): void;
+    complete(request: CacheRequest, messages: readonly M[]): void;
+    observe(message: M, request?: CacheRequest): void;
+    delete(target: MessageReference, except?: CacheRequest): void;
+    /** Remove one message by ID when its channel is unknown, and block reads already in flight from restoring it */
+    deleteId(id: string): void;
+    deleteMany(channelId: string, ids: readonly string[]): void;
+    deleteAuthor(userId: string): void;
+    deleteChannel(channelId: string): void;
+    /**
+     * Remove the messages a deleted thread parent can have taken with its threads: Those in this guild, or without guild
+     * context, whose channel held does not place. Reads of such channels already in flight cannot restore them
+     */
+    deleteUnplaced(guildId: string, held: (channelId: string) => boolean): void;
+    gap(affects?: (guildId: string | null | undefined) => boolean): void;
+    close(): void;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/internal/cache.d.ts.map

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