@crowdedkingdoms/crowdyjs 8.2.0 → 8.4.0

package/dist/stores/inbox.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Messaging stores — typed inboxes over the three message-shaped realtime
+ * surfaces: channel messages ({@link ChannelInbox}), direct actor-to-actor
+ * messages ({@link ActorInbox}), and app-defined client/server events
+ * ({@link EventRouter}). Each keeps a queryable history and dispatches typed
+ * callbacks, replacing the per-app chat rings and payload plumbing.
+ */
+import type { ChunkCoordinatesInput } from '../generated/graphql.js';
+import { type StateCodec } from './codec.js';
+import type { WorldSessionContext } from './session.js';
+/** A decoded message in a {@link ChannelInbox} or {@link ActorInbox}. */
+export interface InboxMessage<T> {
+    /** The channel id (channel messages) or the notification uuid (actor messages). */
+    channelId?: string;
+    /**
+     * The uuid on the wire. For channel messages this is the SENDER's actor
+     * uuid; for single-actor messages the payload is opaque to the server, so
+     * apps conventionally embed the sender identity in the payload itself.
+     */
+    uuid: string;
+    /** The decoded payload. */
+    payload: T;
+    epochMillis: number;
+    receivedAt: number;
+}
+/** Options for {@link attachChannelInbox}. */
+export interface ChannelInboxConfig<T = string> {
+    /** Codec for message payloads. Defaults to UTF-8 text. */
+    codec?: StateCodec<T>;
+    /** Messages kept per channel (oldest dropped). Defaults to 100. */
+    capacity?: number;
+    /**
+     * The sender uuid stamped on outbound messages. Wired from the session's
+     * local actor automatically; a random uuid otherwise.
+     */
+    senderUuid?: string | (() => string | null);
+    /** Clock override for tests. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * The SDK-managed **channel inbox**: every `channelMessage` notification is
+ * decoded and appended to a per-channel history ring (chronological, capped),
+ * with typed send + subscribe. This is the inbound channel fan-out most
+ * games never get around to writing.
+ */
+export declare class ChannelInbox<T = string> {
+    private readonly ctx;
+    private readonly config;
+    private readonly byChannel;
+    private readonly listeners;
+    private readonly codec;
+    private readonly capacity;
+    private readonly now;
+    private readonly fallbackUuid;
+    private decodeFailureCount;
+    private sequence;
+    constructor(ctx: WorldSessionContext, config?: ChannelInboxConfig<T>);
+    /** One channel's history, oldest first (capped at `capacity`). */
+    messages(channelId: string): Array<InboxMessage<T>>;
+    /** Channel ids with recorded history. */
+    channels(): string[];
+    /** Payloads that failed to decode (foreign encodings). */
+    get decodeFailures(): number;
+    /**
+     * Subscribe to incoming messages — every channel, or one `channelId`.
+     * @returns off.
+     */
+    onMessage(handler: (message: InboxMessage<T>) => void, channelId?: string): () => void;
+    /**
+     * Send a typed payload to a channel (requires membership with
+     * `send_messages`; delivery is app-wide, not chunk-routed).
+     */
+    send(channelId: string, payload: T): Promise<boolean>;
+    /** Drop history (one channel, or all). */
+    clear(channelId?: string): void;
+    private ring;
+    private senderUuid;
+    private nextSequence;
+}
+/** Attach a {@link ChannelInbox}. Prefer the `channelInbox` config key. */
+export declare function attachChannelInbox<T = string>(ctx: WorldSessionContext, config?: ChannelInboxConfig<T>): ChannelInbox<T>;
+/** Options for {@link attachActorInbox}. */
+export interface ActorInboxConfig<T = string> {
+    /** Codec for message payloads. Defaults to UTF-8 text. */
+    codec?: StateCodec<T>;
+    /** Messages kept (oldest dropped). Defaults to 100. */
+    capacity?: number;
+    /** Clock override for tests. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * The SDK-managed **direct-message inbox**: `singleActorMessage`
+ * notifications decoded into a capped history with typed subscribe, plus a
+ * typed `send` (the sender must know the target's current chunk — pair with
+ * a {@link RemoteActorStore}, whose records carry it).
+ */
+export declare class ActorInbox<T = string> {
+    private readonly ctx;
+    private readonly history;
+    private readonly listeners;
+    private readonly codec;
+    private readonly capacity;
+    private readonly now;
+    private decodeFailureCount;
+    private sequence;
+    constructor(ctx: WorldSessionContext, config?: ActorInboxConfig<T>);
+    /** Received messages, oldest first (capped at `capacity`). */
+    messages(): Array<InboxMessage<T>>;
+    /** Payloads that failed to decode. */
+    get decodeFailures(): number;
+    /** Subscribe to incoming direct messages. @returns off. */
+    onMessage(listener: (message: InboxMessage<T>) => void): () => void;
+    /**
+     * Send a typed payload to one actor (identified by uuid + its current
+     * chunk). Fire-and-forget: `true` means accepted for sending.
+     */
+    send(targetUuid: string, payload: T, targetChunk: ChunkCoordinatesInput): Promise<boolean>;
+    /** Drop the history. */
+    clear(): void;
+    private nextSequence;
+}
+/** Attach an {@link ActorInbox}. Prefer the `actorInbox` config key. */
+export declare function attachActorInbox<T = string>(ctx: WorldSessionContext, config?: ActorInboxConfig<T>): ActorInbox<T>;
+/** A decoded client/server event delivered by the {@link EventRouter}. */
+export interface TypedEvent<T> {
+    eventType: number;
+    /** Whether another client or the server (model notification) emitted it. */
+    origin: 'client' | 'server';
+    /** The emitting actor/source uuid. */
+    uuid: string;
+    value: T;
+    chunk: ChunkCoordinatesInput;
+    epochMillis: number;
+    receivedAt: number;
+}
+/** Options for {@link attachEventRouter}. */
+export interface EventRouterConfig {
+    /**
+     * The sender uuid stamped on outbound events. Wired from the session's
+     * local actor automatically; a random uuid otherwise.
+     */
+    senderUuid?: string | (() => string | null);
+    /** Replication radius for outbound events (0-8). */
+    distance?: number;
+    /** Clock override for tests. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * The SDK-managed **event router**: register a codec + handler per
+ * app-defined `eventType` (uint16) and receive typed client AND server
+ * events; the latest decoded event per type stays queryable via
+ * {@link lastEvent}. Send typed events with {@link send}.
+ */
+export declare class EventRouter {
+    private readonly ctx;
+    private readonly config;
+    private readonly registrations;
+    private readonly lastByType;
+    private readonly now;
+    private readonly fallbackUuid;
+    private decodeFailureCount;
+    private sequence;
+    constructor(ctx: WorldSessionContext, config?: EventRouterConfig);
+    /**
+     * Register a typed handler for one `eventType`. Multiple handlers (even
+     * with different codecs) may coexist per type.
+     * @returns off.
+     */
+    on<T>(eventType: number, codec: StateCodec<T>, handler: (event: TypedEvent<T>) => void): () => void;
+    /** The latest decoded event of one type (undefined before the first). */
+    lastEvent<T = unknown>(eventType: number): TypedEvent<T> | undefined;
+    /** Events whose registered codec failed to decode. */
+    get decodeFailures(): number;
+    /**
+     * Send a typed app-defined event to a chunk (fanned out to nearby actors
+     * as a `ClientEventNotification`).
+     */
+    send<T>(eventType: number, codec: StateCodec<T>, value: T, chunk: ChunkCoordinatesInput): Promise<boolean>;
+    private senderUuid;
+    private nextSequence;
+}
+/** Attach an {@link EventRouter}. Prefer the `events` config key. */
+export declare function attachEventRouter(ctx: WorldSessionContext, config?: EventRouterConfig): EventRouter;
+//# sourceMappingURL=inbox.d.ts.map

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

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

package/dist/stores/inbox.js

@@ -0,0 +1,326 @@
+/**
+ * Messaging stores — typed inboxes over the three message-shaped realtime
+ * surfaces: channel messages ({@link ChannelInbox}), direct actor-to-actor
+ * messages ({@link ActorInbox}), and app-defined client/server events
+ * ({@link EventRouter}). Each keeps a queryable history and dispatches typed
+ * callbacks, replacing the per-app chat rings and payload plumbing.
+ */
+import { generateCrowdyUuid } from '../utils.js';
+import { textCodec } from './codec.js';
+/**
+ * The SDK-managed **channel inbox**: every `channelMessage` notification is
+ * decoded and appended to a per-channel history ring (chronological, capped),
+ * with typed send + subscribe. This is the inbound channel fan-out most
+ * games never get around to writing.
+ */
+export class ChannelInbox {
+    constructor(ctx, config = {}) {
+        this.ctx = ctx;
+        this.config = config;
+        this.byChannel = new Map();
+        this.listeners = new Set();
+        this.fallbackUuid = generateCrowdyUuid();
+        this.decodeFailureCount = 0;
+        this.sequence = 0;
+        this.codec = config.codec ?? textCodec;
+        this.capacity = Math.max(1, config.capacity ?? 100);
+        this.now = config.now ?? Date.now;
+        ctx.onDispose(ctx.on('channelMessage', (notification) => {
+            let payload;
+            try {
+                payload = this.codec.decode(notification.payload);
+            }
+            catch {
+                this.decodeFailureCount += 1;
+                return;
+            }
+            const message = {
+                channelId: String(notification.channelId),
+                uuid: notification.uuid,
+                payload,
+                epochMillis: Number(notification.epochMillis),
+                receivedAt: this.now(),
+            };
+            const ring = this.ring(String(notification.channelId));
+            ring.push(message);
+            if (ring.length > this.capacity)
+                ring.splice(0, ring.length - this.capacity);
+            for (const entry of [...this.listeners]) {
+                if (entry.channelId === undefined || entry.channelId === message.channelId) {
+                    entry.handler(message);
+                }
+            }
+        }));
+    }
+    /** One channel's history, oldest first (capped at `capacity`). */
+    messages(channelId) {
+        return [...(this.byChannel.get(String(channelId)) ?? [])];
+    }
+    /** Channel ids with recorded history. */
+    channels() {
+        return [...this.byChannel.keys()];
+    }
+    /** Payloads that failed to decode (foreign encodings). */
+    get decodeFailures() {
+        return this.decodeFailureCount;
+    }
+    /**
+     * Subscribe to incoming messages — every channel, or one `channelId`.
+     * @returns off.
+     */
+    onMessage(handler, channelId) {
+        const entry = {
+            channelId: channelId !== undefined ? String(channelId) : undefined,
+            handler,
+        };
+        this.listeners.add(entry);
+        return () => this.listeners.delete(entry);
+    }
+    /**
+     * Send a typed payload to a channel (requires membership with
+     * `send_messages`; delivery is app-wide, not chunk-routed).
+     */
+    async send(channelId, payload) {
+        const sequenceNumber = this.nextSequence();
+        this.ctx.trackSend({
+            kind: 'channelMessage',
+            sequenceNumber,
+            sentAt: this.now(),
+            uuid: this.senderUuid(),
+            detail: { channelId: String(channelId) },
+        });
+        return this.ctx.client.udp.sendChannelMessage({
+            channelId,
+            uuid: this.senderUuid(),
+            payload: this.codec.encode(payload),
+            sequenceNumber,
+        });
+    }
+    /** Drop history (one channel, or all). */
+    clear(channelId) {
+        if (channelId !== undefined)
+            this.byChannel.delete(String(channelId));
+        else
+            this.byChannel.clear();
+    }
+    ring(channelId) {
+        let ring = this.byChannel.get(channelId);
+        if (!ring) {
+            ring = [];
+            this.byChannel.set(channelId, ring);
+        }
+        return ring;
+    }
+    senderUuid() {
+        const configured = typeof this.config.senderUuid === 'function'
+            ? this.config.senderUuid()
+            : this.config.senderUuid;
+        return configured ?? this.fallbackUuid;
+    }
+    nextSequence() {
+        this.sequence = (this.sequence + 1) % 256;
+        return this.sequence;
+    }
+}
+/** Attach a {@link ChannelInbox}. Prefer the `channelInbox` config key. */
+export function attachChannelInbox(ctx, config = {}) {
+    return new ChannelInbox(ctx, config);
+}
+/**
+ * The SDK-managed **direct-message inbox**: `singleActorMessage`
+ * notifications decoded into a capped history with typed subscribe, plus a
+ * typed `send` (the sender must know the target's current chunk — pair with
+ * a {@link RemoteActorStore}, whose records carry it).
+ */
+export class ActorInbox {
+    constructor(ctx, config = {}) {
+        this.ctx = ctx;
+        this.history = [];
+        this.listeners = new Set();
+        this.decodeFailureCount = 0;
+        this.sequence = 0;
+        this.codec = config.codec ?? textCodec;
+        this.capacity = Math.max(1, config.capacity ?? 100);
+        this.now = config.now ?? Date.now;
+        ctx.onDispose(ctx.on('singleActorMessage', (notification) => {
+            let payload;
+            try {
+                payload = this.codec.decode(notification.payload);
+            }
+            catch {
+                this.decodeFailureCount += 1;
+                return;
+            }
+            const message = {
+                uuid: notification.uuid,
+                payload,
+                epochMillis: Number(notification.epochMillis),
+                receivedAt: this.now(),
+            };
+            this.history.push(message);
+            if (this.history.length > this.capacity) {
+                this.history.splice(0, this.history.length - this.capacity);
+            }
+            for (const listener of [...this.listeners])
+                listener(message);
+        }));
+    }
+    /** Received messages, oldest first (capped at `capacity`). */
+    messages() {
+        return [...this.history];
+    }
+    /** Payloads that failed to decode. */
+    get decodeFailures() {
+        return this.decodeFailureCount;
+    }
+    /** Subscribe to incoming direct messages. @returns off. */
+    onMessage(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    /**
+     * Send a typed payload to one actor (identified by uuid + its current
+     * chunk). Fire-and-forget: `true` means accepted for sending.
+     */
+    async send(targetUuid, payload, targetChunk) {
+        const sequenceNumber = this.nextSequence();
+        this.ctx.trackSend({
+            kind: 'singleActorMessage',
+            sequenceNumber,
+            sentAt: this.now(),
+            detail: { targetUuid },
+        });
+        return this.ctx.client.udp.sendSingleActorMessage({
+            appId: this.ctx.appId,
+            chunk: targetChunk,
+            targetUuid,
+            payload: this.codec.encode(payload),
+            sequenceNumber,
+        });
+    }
+    /** Drop the history. */
+    clear() {
+        this.history.length = 0;
+    }
+    nextSequence() {
+        this.sequence = (this.sequence + 1) % 256;
+        return this.sequence;
+    }
+}
+/** Attach an {@link ActorInbox}. Prefer the `actorInbox` config key. */
+export function attachActorInbox(ctx, config = {}) {
+    return new ActorInbox(ctx, config);
+}
+/**
+ * The SDK-managed **event router**: register a codec + handler per
+ * app-defined `eventType` (uint16) and receive typed client AND server
+ * events; the latest decoded event per type stays queryable via
+ * {@link lastEvent}. Send typed events with {@link send}.
+ */
+export class EventRouter {
+    constructor(ctx, config = {}) {
+        this.ctx = ctx;
+        this.config = config;
+        this.registrations = new Map();
+        this.lastByType = new Map();
+        this.fallbackUuid = generateCrowdyUuid();
+        this.decodeFailureCount = 0;
+        this.sequence = 0;
+        this.now = config.now ?? Date.now;
+        const dispatch = (origin) => (notification) => {
+            const set = this.registrations.get(notification.eventType);
+            if (!set || set.size === 0)
+                return;
+            for (const registration of [...set]) {
+                let value;
+                try {
+                    value = registration.codec.decode(notification.state);
+                }
+                catch {
+                    this.decodeFailureCount += 1;
+                    continue;
+                }
+                const event = {
+                    eventType: notification.eventType,
+                    origin,
+                    uuid: notification.uuid,
+                    value,
+                    chunk: {
+                        x: notification.chunkX,
+                        y: notification.chunkY,
+                        z: notification.chunkZ,
+                    },
+                    epochMillis: Number(notification.epochMillis),
+                    receivedAt: this.now(),
+                };
+                this.lastByType.set(notification.eventType, event);
+                registration.handler(event);
+            }
+        };
+        ctx.onDispose(ctx.on('clientEvent', dispatch('client')));
+        ctx.onDispose(ctx.on('serverEvent', dispatch('server')));
+    }
+    /**
+     * Register a typed handler for one `eventType`. Multiple handlers (even
+     * with different codecs) may coexist per type.
+     * @returns off.
+     */
+    on(eventType, codec, handler) {
+        let set = this.registrations.get(eventType);
+        if (!set) {
+            set = new Set();
+            this.registrations.set(eventType, set);
+        }
+        const registration = {
+            codec: codec,
+            handler: handler,
+        };
+        set.add(registration);
+        return () => set.delete(registration);
+    }
+    /** The latest decoded event of one type (undefined before the first). */
+    lastEvent(eventType) {
+        return this.lastByType.get(eventType);
+    }
+    /** Events whose registered codec failed to decode. */
+    get decodeFailures() {
+        return this.decodeFailureCount;
+    }
+    /**
+     * Send a typed app-defined event to a chunk (fanned out to nearby actors
+     * as a `ClientEventNotification`).
+     */
+    async send(eventType, codec, value, chunk) {
+        const sequenceNumber = this.nextSequence();
+        this.ctx.trackSend({
+            kind: 'clientEvent',
+            sequenceNumber,
+            sentAt: this.now(),
+            uuid: this.senderUuid(),
+            detail: { eventType },
+        });
+        return this.ctx.client.udp.sendClientEvent({
+            appId: this.ctx.appId,
+            chunk,
+            uuid: this.senderUuid(),
+            eventType,
+            state: codec.encode(value),
+            sequenceNumber,
+            ...(this.config.distance !== undefined ? { distance: this.config.distance } : {}),
+        });
+    }
+    senderUuid() {
+        const configured = typeof this.config.senderUuid === 'function'
+            ? this.config.senderUuid()
+            : this.config.senderUuid;
+        return configured ?? this.fallbackUuid;
+    }
+    nextSequence() {
+        this.sequence = (this.sequence + 1) % 256;
+        return this.sequence;
+    }
+}
+/** Attach an {@link EventRouter}. Prefer the `events` config key. */
+export function attachEventRouter(ctx, config = {}) {
+    return new EventRouter(ctx, config);
+}