@crowdedkingdoms/crowdyjs 8.3.0 → 8.4.0

package/dist/stores/durable.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Durable-state stores: host election tracking ({@link HostTracker}), the
+ * per-user app save blob ({@link SaveStateStore}), and typed avatar state
+ * ({@link AvatarStateStore}). These wrap the GraphQL surfaces with local
+ * caches and typed codecs — independent types from your replication state,
+ * as durable and realtime payloads rarely share a layout.
+ */
+import { type StateCodec } from './codec.js';
+import type { WorldSessionContext } from './session.js';
+/** Options for {@link attachHostTracker}. */
+export interface HostTrackerConfig {
+    /**
+     * The authenticated user's id (or a getter), used to compute
+     * {@link HostTracker.isHost}. Without it only `hostUserId` is tracked.
+     */
+    myUserId?: string | (() => string | null);
+    /** Heartbeat cadence in ms (also keeps you host-eligible). Defaults to 3000. */
+    intervalMs?: number;
+    /** Send one heartbeat immediately on attach. Defaults to true. */
+    heartbeatImmediately?: boolean;
+}
+/**
+ * The SDK-managed **host election tracker**: heartbeats on the session
+ * ticker (keeping this client host-eligible), caches the elected host, and
+ * fires {@link onHostChanged} on transitions. Election is informational —
+ * gate authoritative writes with `is_host` invoke policies server-side.
+ * Transient heartbeat failures keep the last known host.
+ */
+export declare class HostTracker {
+    private readonly ctx;
+    private readonly config;
+    private hostUserIdValue;
+    private readonly listeners;
+    constructor(ctx: WorldSessionContext, config?: HostTrackerConfig);
+    /** The elected host's user id (null until the first successful beat). */
+    get hostUserId(): string | null;
+    /** Whether the configured user is the elected host. */
+    get isHost(): boolean;
+    /** Fired when the elected host changes (including the first election). @returns off. */
+    onHostChanged(listener: (hostUserId: string | null) => void): () => void;
+    /** Send one heartbeat now and apply the result. */
+    beat(): Promise<void>;
+}
+/** Attach a {@link HostTracker}. Prefer the `host` config key. */
+export declare function attachHostTracker(ctx: WorldSessionContext, config?: HostTrackerConfig): HostTracker;
+/** Options for {@link attachSaveState}. */
+export interface SaveStateConfig<T> {
+    /** Codec for the save blob. Defaults to JSON. */
+    codec?: StateCodec<T>;
+    /**
+     * Debounced autosave: when set, a dirty value persists automatically at
+     * most once per this many ms (on the session ticker). Defaults to off.
+     */
+    autosaveMs?: number | false;
+    /** Clock override for tests. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * The SDK-managed **save state**: a typed local cache over the per-user
+ * per-app `client.state` blob. `load()` hydrates it, `set()` updates it (and
+ * autosave persists it when configured), `save()` persists on demand.
+ * The type is intentionally independent of your replication state — durable
+ * saves and 5 Hz poses are different data.
+ */
+export declare class SaveStateStore<T> {
+    private readonly ctx;
+    private current;
+    private dirtyFlag;
+    private saving;
+    private lastSavedAtValue;
+    private readonly codec;
+    private readonly now;
+    constructor(ctx: WorldSessionContext, config?: SaveStateConfig<T>);
+    /** The cached typed save (null before {@link load}/{@link set}). */
+    get value(): T | null;
+    /** Whether the cache has unsaved changes. */
+    get dirty(): boolean;
+    /** Local time of the last successful save. */
+    get lastSavedAt(): number | null;
+    /** Fetch and decode the server copy into the cache (null when none). */
+    load(): Promise<T | null>;
+    /** Update the cached save and mark it dirty (autosave persists it). */
+    set(value: T): void;
+    /** Merge a partial update into the cached save (object saves only). */
+    patch(patch: Partial<T>): void;
+    /** Persist the cached save now. No-op when nothing is cached. */
+    save(): Promise<void>;
+}
+/** Attach a {@link SaveStateStore}. Prefer the `save` config key. */
+export declare function attachSaveState<T>(ctx: WorldSessionContext, config?: SaveStateConfig<T>): SaveStateStore<T>;
+/** Options for {@link attachAvatarState}. */
+export interface AvatarStateConfig<TPublic, TPrivate, TApp> {
+    /** The avatar to bind. Omit to bind the caller's first avatar on load. */
+    avatarId?: string;
+    /** Codec for the public (anyone-readable) avatar state. Defaults to JSON. */
+    publicCodec?: StateCodec<TPublic>;
+    /** Codec for the private (owner-only) avatar state. Defaults to JSON. */
+    privateCodec?: StateCodec<TPrivate>;
+    /** Codec for the per-app avatar state. Defaults to JSON. */
+    appCodec?: StateCodec<TApp>;
+}
+/**
+ * The SDK-managed **avatar state**: typed, cached views of one avatar's
+ * public / private / per-app state blobs, each with its own codec (three
+ * independent types — public profiles, private inventory-ish data, and
+ * app-specific progress rarely share a shape).
+ */
+export declare class AvatarStateStore<TPublic = unknown, TPrivate = unknown, TApp = unknown> {
+    private readonly ctx;
+    private avatarIdValue;
+    private publicValue;
+    private privateValue;
+    private appValue;
+    private readonly publicCodec;
+    private readonly privateCodec;
+    private readonly appCodec;
+    constructor(ctx: WorldSessionContext, config?: AvatarStateConfig<TPublic, TPrivate, TApp>);
+    /** The bound avatar id (null before {@link load} resolves a default). */
+    get avatarId(): string | null;
+    /** The cached decoded public state. */
+    get publicState(): TPublic | null;
+    /** The cached decoded private state (owner-only). */
+    get privateState(): TPrivate | null;
+    /** The cached decoded per-app state. */
+    get appState(): TApp | null;
+    /**
+     * Hydrate the cache: resolves the avatar (the caller's first when no
+     * `avatarId` was configured), decodes its public/private state, and
+     * fetches this app's avatar state.
+     */
+    load(): Promise<void>;
+    /** Write the public and/or private state (typed) and update the cache. */
+    setIdentityState(input: {
+        publicState?: TPublic;
+        privateState?: TPrivate;
+    }): Promise<void>;
+    /** Write this app's avatar state (typed) and update the cache. */
+    setAppState(value: TApp): Promise<void>;
+    private requireAvatar;
+    private decodeWith;
+}
+/** Attach an {@link AvatarStateStore}. Prefer the `avatar` config key. */
+export declare function attachAvatarState<TPublic = unknown, TPrivate = unknown, TApp = unknown>(ctx: WorldSessionContext, config?: AvatarStateConfig<TPublic, TPrivate, TApp>): AvatarStateStore<TPublic, TPrivate, TApp>;
+//# sourceMappingURL=durable.d.ts.map

package/dist/stores/durable.d.ts.map

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

package/dist/stores/durable.js

@@ -0,0 +1,246 @@
+/**
+ * Durable-state stores: host election tracking ({@link HostTracker}), the
+ * per-user app save blob ({@link SaveStateStore}), and typed avatar state
+ * ({@link AvatarStateStore}). These wrap the GraphQL surfaces with local
+ * caches and typed codecs — independent types from your replication state,
+ * as durable and realtime payloads rarely share a layout.
+ */
+import { jsonCodec } from './codec.js';
+/**
+ * The SDK-managed **host election tracker**: heartbeats on the session
+ * ticker (keeping this client host-eligible), caches the elected host, and
+ * fires {@link onHostChanged} on transitions. Election is informational —
+ * gate authoritative writes with `is_host` invoke policies server-side.
+ * Transient heartbeat failures keep the last known host.
+ */
+export class HostTracker {
+    constructor(ctx, config = {}) {
+        this.ctx = ctx;
+        this.config = config;
+        this.hostUserIdValue = null;
+        this.listeners = new Set();
+        const interval = config.intervalMs ?? 3000;
+        ctx.onDispose(ctx.ticker.every(interval, () => void this.beat()));
+        if (config.heartbeatImmediately ?? true)
+            void this.beat();
+    }
+    /** The elected host's user id (null until the first successful beat). */
+    get hostUserId() {
+        return this.hostUserIdValue;
+    }
+    /** Whether the configured user is the elected host. */
+    get isHost() {
+        const mine = typeof this.config.myUserId === 'function'
+            ? this.config.myUserId()
+            : this.config.myUserId;
+        return mine != null && this.hostUserIdValue != null && String(mine) === this.hostUserIdValue;
+    }
+    /** Fired when the elected host changes (including the first election). @returns off. */
+    onHostChanged(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    /** Send one heartbeat now and apply the result. */
+    async beat() {
+        let result;
+        try {
+            result = await this.ctx.client.host.heartbeat(this.ctx.appId);
+        }
+        catch {
+            return; // Transient failure: keep the last known host.
+        }
+        const next = result?.hostUserId != null ? String(result.hostUserId) : null;
+        if (next !== this.hostUserIdValue) {
+            this.hostUserIdValue = next;
+            for (const listener of [...this.listeners])
+                listener(next);
+        }
+    }
+}
+/** Attach a {@link HostTracker}. Prefer the `host` config key. */
+export function attachHostTracker(ctx, config = {}) {
+    return new HostTracker(ctx, config);
+}
+/**
+ * The SDK-managed **save state**: a typed local cache over the per-user
+ * per-app `client.state` blob. `load()` hydrates it, `set()` updates it (and
+ * autosave persists it when configured), `save()` persists on demand.
+ * The type is intentionally independent of your replication state — durable
+ * saves and 5 Hz poses are different data.
+ */
+export class SaveStateStore {
+    constructor(ctx, config = {}) {
+        this.ctx = ctx;
+        this.current = null;
+        this.dirtyFlag = false;
+        this.saving = false;
+        this.lastSavedAtValue = null;
+        this.codec = config.codec ?? jsonCodec();
+        this.now = config.now ?? Date.now;
+        const autosave = config.autosaveMs ?? false;
+        if (autosave !== false && autosave > 0) {
+            ctx.onDispose(ctx.ticker.every(autosave, () => {
+                if (this.dirtyFlag && !this.saving)
+                    void this.save();
+            }));
+        }
+    }
+    /** The cached typed save (null before {@link load}/{@link set}). */
+    get value() {
+        return this.current;
+    }
+    /** Whether the cache has unsaved changes. */
+    get dirty() {
+        return this.dirtyFlag;
+    }
+    /** Local time of the last successful save. */
+    get lastSavedAt() {
+        return this.lastSavedAtValue;
+    }
+    /** Fetch and decode the server copy into the cache (null when none). */
+    async load() {
+        const record = await this.ctx.client.state.getOne(this.ctx.appId);
+        if (record?.state == null) {
+            this.current = null;
+            return null;
+        }
+        try {
+            this.current = this.codec.decode(record.state);
+        }
+        catch {
+            this.current = null;
+        }
+        this.dirtyFlag = false;
+        return this.current;
+    }
+    /** Update the cached save and mark it dirty (autosave persists it). */
+    set(value) {
+        this.current = value;
+        this.dirtyFlag = true;
+    }
+    /** Merge a partial update into the cached save (object saves only). */
+    patch(patch) {
+        this.set({ ...this.current, ...patch });
+    }
+    /** Persist the cached save now. No-op when nothing is cached. */
+    async save() {
+        if (this.current === null)
+            return;
+        this.saving = true;
+        try {
+            await this.ctx.client.state.update({
+                appId: this.ctx.appId,
+                state: this.codec.encode(this.current),
+            });
+            this.dirtyFlag = false;
+            this.lastSavedAtValue = this.now();
+        }
+        finally {
+            this.saving = false;
+        }
+    }
+}
+/** Attach a {@link SaveStateStore}. Prefer the `save` config key. */
+export function attachSaveState(ctx, config = {}) {
+    return new SaveStateStore(ctx, config);
+}
+/**
+ * The SDK-managed **avatar state**: typed, cached views of one avatar's
+ * public / private / per-app state blobs, each with its own codec (three
+ * independent types — public profiles, private inventory-ish data, and
+ * app-specific progress rarely share a shape).
+ */
+export class AvatarStateStore {
+    constructor(ctx, config = {}) {
+        this.ctx = ctx;
+        this.publicValue = null;
+        this.privateValue = null;
+        this.appValue = null;
+        this.avatarIdValue = config.avatarId ?? null;
+        this.publicCodec = config.publicCodec ?? jsonCodec();
+        this.privateCodec = config.privateCodec ?? jsonCodec();
+        this.appCodec = config.appCodec ?? jsonCodec();
+    }
+    /** The bound avatar id (null before {@link load} resolves a default). */
+    get avatarId() {
+        return this.avatarIdValue;
+    }
+    /** The cached decoded public state. */
+    get publicState() {
+        return this.publicValue;
+    }
+    /** The cached decoded private state (owner-only). */
+    get privateState() {
+        return this.privateValue;
+    }
+    /** The cached decoded per-app state. */
+    get appState() {
+        return this.appValue;
+    }
+    /**
+     * Hydrate the cache: resolves the avatar (the caller's first when no
+     * `avatarId` was configured), decodes its public/private state, and
+     * fetches this app's avatar state.
+     */
+    async load() {
+        if (!this.avatarIdValue) {
+            const mine = await this.ctx.client.avatars.mine();
+            const first = mine[0];
+            if (!first) {
+                throw new Error('No avatar to bind — create one with client.avatars.create()');
+            }
+            this.avatarIdValue = String(first.avatarId);
+        }
+        const avatar = await this.ctx.client.avatars.get(this.avatarIdValue);
+        this.publicValue = this.decodeWith(this.publicCodec, avatar?.publicState);
+        this.privateValue = this.decodeWith(this.privateCodec, avatar?.privateState);
+        const appRecord = await this.ctx.client.avatars.appState(this.ctx.appId, this.avatarIdValue);
+        this.appValue = this.decodeWith(this.appCodec, appRecord?.state);
+    }
+    /** Write the public and/or private state (typed) and update the cache. */
+    async setIdentityState(input) {
+        const avatarId = this.requireAvatar();
+        await this.ctx.client.avatars.updateState(avatarId, {
+            ...(input.publicState !== undefined
+                ? { publicState: this.publicCodec.encode(input.publicState) }
+                : {}),
+            ...(input.privateState !== undefined
+                ? { privateState: this.privateCodec.encode(input.privateState) }
+                : {}),
+        });
+        if (input.publicState !== undefined)
+            this.publicValue = input.publicState;
+        if (input.privateState !== undefined)
+            this.privateValue = input.privateState;
+    }
+    /** Write this app's avatar state (typed) and update the cache. */
+    async setAppState(value) {
+        const avatarId = this.requireAvatar();
+        await this.ctx.client.avatars.updateAppState({
+            appId: this.ctx.appId,
+            avatarId,
+            state: this.appCodec.encode(value),
+        });
+        this.appValue = value;
+    }
+    requireAvatar() {
+        if (!this.avatarIdValue) {
+            throw new Error('AvatarStateStore is unbound — call load() first or configure avatarId');
+        }
+        return this.avatarIdValue;
+    }
+    decodeWith(codec, encoded) {
+        if (encoded == null || encoded === '')
+            return null;
+        try {
+            return codec.decode(encoded);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/** Attach an {@link AvatarStateStore}. Prefer the `avatar` config key. */
+export function attachAvatarState(ctx, config = {}) {
+    return new AvatarStateStore(ctx, config);
+}

package/dist/stores/errors.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Error attribution — the bookkeeping games skip and then regret.
+ *
+ * The server reports UDP-side failures asynchronously as
+ * `GenericErrorResponse { sequenceNumber, errorCode }`. Without a record of
+ * what each sequence number was, apps can only log them. The session tracks
+ * every outbound send made through the stores (kind, actor uuid, detail) in
+ * a 256-slot table (sequence numbers are uint8), so each error is
+ * **attributed** to the send that caused it and kept in a queryable ring
+ * buffer.
+ */
+import type { SentPacketRecord, WorldSessionContext } from './session.js';
+/** A server-reported send error, attributed to the send that caused it. */
+export interface AttributedError {
+    /** The server's `UdpErrorCode` (e.g. `'UNAUTHORIZED'`). */
+    errorCode: string;
+    sequenceNumber: number;
+    receivedAt: number;
+    /**
+     * The tracked outbound send with this sequence number, when the session
+     * saw one (undefined for sends made outside the stores).
+     */
+    send?: SentPacketRecord;
+}
+/** Options for {@link attachErrorStore}. */
+export interface ErrorStoreConfig {
+    /** Errors kept in the ring buffer. Defaults to 50. */
+    capacity?: number;
+    /** Clock override for tests. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * The SDK-managed **send-error log**: every `GenericErrorResponse` is
+ * attributed to the tracked send with the same sequence number and recorded
+ * (newest first). Query {@link recent}, subscribe with {@link onError}, or
+ * look up the latest error for one actor with {@link lastFor}.
+ *
+ * Sequence numbers are uint8 correlation ids that wrap at 256, so
+ * attribution is best-effort by design: a very old error after 256 newer
+ * sends would attribute to the newer send with the reused number.
+ */
+export declare class ErrorStore {
+    private readonly ring;
+    private readonly sends;
+    private readonly byActor;
+    private readonly listeners;
+    private readonly capacity;
+    private readonly now;
+    private totalCount;
+    constructor(ctx: WorldSessionContext, config?: ErrorStoreConfig);
+    /** The most recent errors, newest first (up to `n`, default all kept). */
+    recent(n?: number): AttributedError[];
+    /** The single most recent error, if any. */
+    get last(): AttributedError | undefined;
+    /** Total errors seen (including ones evicted from the ring). */
+    get total(): number;
+    /** The latest error attributed to sends by one actor uuid. */
+    lastFor(uuid: string): AttributedError | undefined;
+    /** Subscribe to every attributed error. @returns off. */
+    onError(listener: (error: AttributedError) => void): () => void;
+    /** Drop the recorded errors (send tracking continues). */
+    clear(): void;
+}
+/**
+ * Attach an {@link ErrorStore} to a world session context. Prefer the
+ * `errors` key of `createWorldSession`'s config.
+ */
+export declare function attachErrorStore(ctx: WorldSessionContext, config?: ErrorStoreConfig): ErrorStore;
+//# sourceMappingURL=errors.d.ts.map

package/dist/stores/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/stores/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAE1E,2EAA2E;AAC3E,MAAM,WAAW,eAAe;IAC9B,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,IAAI,CAAC,EAAE,gBAAgB,CAAC;CACzB;AAED,4CAA4C;AAC5C,MAAM,WAAW,gBAAgB;IAC/B,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAyB;IAC9C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuC;IAC7D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;IAC9D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA+C;IACzE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,UAAU,CAAK;gBAEX,GAAG,EAAE,mBAAmB,EAAE,MAAM,GAAE,gBAAqB;IA4BnE,0EAA0E;IAC1E,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,GAAG,eAAe,EAAE;IAIrC,4CAA4C;IAC5C,IAAI,IAAI,IAAI,eAAe,GAAG,SAAS,CAEtC;IAED,gEAAgE;IAChE,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,8DAA8D;IAC9D,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAIlD,yDAAyD;IACzD,OAAO,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,GAAG,MAAM,IAAI;IAK/D,0DAA0D;IAC1D,KAAK,IAAI,IAAI;CAId;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,mBAAmB,EACxB,MAAM,GAAE,gBAAqB,GAC5B,UAAU,CAEZ"}

package/dist/stores/errors.js

@@ -0,0 +1,87 @@
+/**
+ * Error attribution — the bookkeeping games skip and then regret.
+ *
+ * The server reports UDP-side failures asynchronously as
+ * `GenericErrorResponse { sequenceNumber, errorCode }`. Without a record of
+ * what each sequence number was, apps can only log them. The session tracks
+ * every outbound send made through the stores (kind, actor uuid, detail) in
+ * a 256-slot table (sequence numbers are uint8), so each error is
+ * **attributed** to the send that caused it and kept in a queryable ring
+ * buffer.
+ */
+/**
+ * The SDK-managed **send-error log**: every `GenericErrorResponse` is
+ * attributed to the tracked send with the same sequence number and recorded
+ * (newest first). Query {@link recent}, subscribe with {@link onError}, or
+ * look up the latest error for one actor with {@link lastFor}.
+ *
+ * Sequence numbers are uint8 correlation ids that wrap at 256, so
+ * attribution is best-effort by design: a very old error after 256 newer
+ * sends would attribute to the newer send with the reused number.
+ */
+export class ErrorStore {
+    constructor(ctx, config = {}) {
+        this.ring = [];
+        this.sends = new Map(); // seq → last send
+        this.byActor = new Map();
+        this.listeners = new Set();
+        this.totalCount = 0;
+        this.capacity = Math.max(1, config.capacity ?? 50);
+        this.now = config.now ?? Date.now;
+        // Become the session's send-tracking sink: stores that send call
+        // ctx.trackSend(...) and we remember the last send per sequence number.
+        ctx.setSendTracker((record) => {
+            this.sends.set(record.sequenceNumber, record);
+        });
+        ctx.onDispose(ctx.on('genericError', (notification) => {
+            const send = this.sends.get(notification.sequenceNumber);
+            const error = {
+                errorCode: String(notification.errorCode),
+                sequenceNumber: notification.sequenceNumber,
+                receivedAt: this.now(),
+                ...(send ? { send } : {}),
+            };
+            this.ring.unshift(error);
+            if (this.ring.length > this.capacity)
+                this.ring.length = this.capacity;
+            this.totalCount += 1;
+            if (send?.uuid)
+                this.byActor.set(send.uuid, error);
+            for (const listener of [...this.listeners])
+                listener(error);
+        }));
+    }
+    /** The most recent errors, newest first (up to `n`, default all kept). */
+    recent(n) {
+        return n === undefined ? [...this.ring] : this.ring.slice(0, n);
+    }
+    /** The single most recent error, if any. */
+    get last() {
+        return this.ring[0];
+    }
+    /** Total errors seen (including ones evicted from the ring). */
+    get total() {
+        return this.totalCount;
+    }
+    /** The latest error attributed to sends by one actor uuid. */
+    lastFor(uuid) {
+        return this.byActor.get(uuid);
+    }
+    /** Subscribe to every attributed error. @returns off. */
+    onError(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    /** Drop the recorded errors (send tracking continues). */
+    clear() {
+        this.ring.length = 0;
+        this.byActor.clear();
+    }
+}
+/**
+ * Attach an {@link ErrorStore} to a world session context. Prefer the
+ * `errors` key of `createWorldSession`'s config.
+ */
+export function attachErrorStore(ctx, config = {}) {
+    return new ErrorStore(ctx, config);
+}