@triformine/nexis-sdk 0.1.0

package/bun.lock

@@ -0,0 +1,111 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "@triformine/nexis-sdk",
+      "dependencies": {
+        "msgpackr": "1.11.8",
+      },
+      "devDependencies": {
+        "typescript": "5.9.3",
+      },
+    },
+  },
+  "packages": {
+    "@msgpackr-extract/msgpackr-extract-darwin-arm64": [
+      "@msgpackr-extract/msgpackr-extract-darwin-arm64@3.0.3",
+      "",
+      { "os": "darwin", "cpu": "arm64" },
+      "sha512-QZHtlVgbAdy2zAqNA9Gu1UpIuI8Xvsd1v8ic6B2pZmeFnFcMWiPLfWXh7TVw4eGEZ/C9TH281KwhVoeQUKbyjw==",
+    ],
+
+    "@msgpackr-extract/msgpackr-extract-darwin-x64": [
+      "@msgpackr-extract/msgpackr-extract-darwin-x64@3.0.3",
+      "",
+      { "os": "darwin", "cpu": "x64" },
+      "sha512-mdzd3AVzYKuUmiWOQ8GNhl64/IoFGol569zNRdkLReh6LRLHOXxU4U8eq0JwaD8iFHdVGqSy4IjFL4reoWCDFw==",
+    ],
+
+    "@msgpackr-extract/msgpackr-extract-linux-arm": [
+      "@msgpackr-extract/msgpackr-extract-linux-arm@3.0.3",
+      "",
+      { "os": "linux", "cpu": "arm" },
+      "sha512-fg0uy/dG/nZEXfYilKoRe7yALaNmHoYeIoJuJ7KJ+YyU2bvY8vPv27f7UKhGRpY6euFYqEVhxCFZgAUNQBM3nw==",
+    ],
+
+    "@msgpackr-extract/msgpackr-extract-linux-arm64": [
+      "@msgpackr-extract/msgpackr-extract-linux-arm64@3.0.3",
+      "",
+      { "os": "linux", "cpu": "arm64" },
+      "sha512-YxQL+ax0XqBJDZiKimS2XQaf+2wDGVa1enVRGzEvLLVFeqa5kx2bWbtcSXgsxjQB7nRqqIGFIcLteF/sHeVtQg==",
+    ],
+
+    "@msgpackr-extract/msgpackr-extract-linux-x64": [
+      "@msgpackr-extract/msgpackr-extract-linux-x64@3.0.3",
+      "",
+      { "os": "linux", "cpu": "x64" },
+      "sha512-cvwNfbP07pKUfq1uH+S6KJ7dT9K8WOE4ZiAcsrSes+UY55E/0jLYc+vq+DO7jlmqRb5zAggExKm0H7O/CBaesg==",
+    ],
+
+    "@msgpackr-extract/msgpackr-extract-win32-x64": [
+      "@msgpackr-extract/msgpackr-extract-win32-x64@3.0.3",
+      "",
+      { "os": "win32", "cpu": "x64" },
+      "sha512-x0fWaQtYp4E6sktbsdAqnehxDgEc/VwM7uLsRCYWaiGu0ykYdZPiS8zCWdnjHwyiumousxfBm4SO31eXqwEZhQ==",
+    ],
+
+    "detect-libc": [
+      "detect-libc@2.1.2",
+      "",
+      {},
+      "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==",
+    ],
+
+    "msgpackr": [
+      "msgpackr@1.11.8",
+      "",
+      { "optionalDependencies": { "msgpackr-extract": "^3.0.2" } },
+      "sha512-bC4UGzHhVvgDNS7kn9tV8fAucIYUBuGojcaLiz7v+P63Lmtm0Xeji8B/8tYKddALXxJLpwIeBmUN3u64C4YkRA==",
+    ],
+
+    "msgpackr-extract": [
+      "msgpackr-extract@3.0.3",
+      "",
+      {
+        "dependencies": { "node-gyp-build-optional-packages": "5.2.2" },
+        "optionalDependencies": {
+          "@msgpackr-extract/msgpackr-extract-darwin-arm64": "3.0.3",
+          "@msgpackr-extract/msgpackr-extract-darwin-x64": "3.0.3",
+          "@msgpackr-extract/msgpackr-extract-linux-arm": "3.0.3",
+          "@msgpackr-extract/msgpackr-extract-linux-arm64": "3.0.3",
+          "@msgpackr-extract/msgpackr-extract-linux-x64": "3.0.3",
+          "@msgpackr-extract/msgpackr-extract-win32-x64": "3.0.3",
+        },
+        "bin": { "download-msgpackr-prebuilds": "bin/download-prebuilds.js" },
+      },
+      "sha512-P0efT1C9jIdVRefqjzOQ9Xml57zpOXnIuS+csaB4MdZbTdmGDLo8XhzBG1N7aO11gKDDkJvBLULeFTo46wwreA==",
+    ],
+
+    "node-gyp-build-optional-packages": [
+      "node-gyp-build-optional-packages@5.2.2",
+      "",
+      {
+        "dependencies": { "detect-libc": "^2.0.1" },
+        "bin": {
+          "node-gyp-build-optional-packages": "bin.js",
+          "node-gyp-build-optional-packages-optional": "optional.js",
+          "node-gyp-build-optional-packages-test": "build-test.js",
+        },
+      },
+      "sha512-s+w+rBWnpTMwSFbaE0UXsRlg7hU4FjekKU4eyAih5T8nJuNZT1nNsskXpxmeqSK9UzkBl6UgRlnKc8hz8IEqOw==",
+    ],
+
+    "typescript": [
+      "typescript@5.9.3",
+      "",
+      { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } },
+      "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+    ],
+  },
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@triformine/nexis-sdk",
+  "version": "0.1.0",
+  "private": false,
+  "author": "TriForMine <quentin@triformine.dev> (https://github.com/TriForMine/)",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "packageManager": "bun@1.3.9",
+  "scripts": {
+    "test": "bun test",
+    "build": "bunx tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "msgpackr": "1.11.8"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3"
+  }
+}

package/src/client.ts

@@ -0,0 +1,949 @@
+import {
+  applyPatch,
+  computeStateChecksum,
+  parsePatchPayload,
+  parseSnapshotPayload,
+} from "./patch";
+import { JsonCodec, MsgpackCodec, codecFor, type Codec } from "./codec";
+import { RpcClient, UnknownRidError } from "./rpc";
+import type {
+  ConnectOptions,
+  Envelope,
+  HandshakeRequest,
+  MatchFound,
+  MatchmakingDequeueResponse,
+  MatchmakingQueueResponse,
+  RoomListResponse,
+  RoomMessagePayload,
+  RoomMessageType,
+} from "./types";
+
+const DEFAULT_VERSION = 1;
+const DEFAULT_RECONNECT_INITIAL_DELAY_MS = 250;
+const DEFAULT_RECONNECT_MAX_DELAY_MS = 3_000;
+const DEFAULT_RECONNECT_MAX_ATTEMPTS = 20;
+
+type EventHandler = (message: Envelope) => void;
+type StateHandler = (state: Record<string, unknown>) => void;
+type MatchFoundHandler = (match: MatchFound, message: Envelope) => void;
+type RoomMessageHandler = (data: unknown, envelope: Envelope) => void;
+type SelectorHandler = (value: unknown, state: Record<string, unknown>) => void;
+type SupportedCodec = "json" | "msgpack";
+
+type SelectorRegistration = {
+  path: string;
+  callback: SelectorHandler;
+  lastValue: unknown;
+};
+
+type ResolvedConnectOptions = ConnectOptions & {
+  codecs: Array<"msgpack" | "json">;
+  autoJoinMatchedRoom: boolean;
+  autoReconnect: boolean;
+  reconnectInitialDelayMs: number;
+  reconnectMaxDelayMs: number;
+  reconnectMaxAttempts: number;
+};
+
+export type RoomStateChangeSubscription = {
+  (callback: StateHandler): () => void;
+  once(callback: StateHandler): () => void;
+  select(path: string, callback: SelectorHandler): () => void;
+};
+
+function normalizeConnectOptions(
+  options: ConnectOptions,
+): ResolvedConnectOptions {
+  const reconnectInitialDelayMs = Math.max(
+    50,
+    options.reconnectInitialDelayMs ?? DEFAULT_RECONNECT_INITIAL_DELAY_MS,
+  );
+  const reconnectMaxDelayMs = Math.max(
+    reconnectInitialDelayMs,
+    options.reconnectMaxDelayMs ?? DEFAULT_RECONNECT_MAX_DELAY_MS,
+  );
+  const reconnectMaxAttempts = Math.max(
+    1,
+    options.reconnectMaxAttempts ?? DEFAULT_RECONNECT_MAX_ATTEMPTS,
+  );
+  return {
+    ...options,
+    codecs: options.codecs ?? ["msgpack", "json"],
+    autoJoinMatchedRoom: options.autoJoinMatchedRoom ?? false,
+    autoReconnect: options.autoReconnect ?? true,
+    reconnectInitialDelayMs,
+    reconnectMaxDelayMs,
+    reconnectMaxAttempts,
+  };
+}
+
+function readCodecName(message: Envelope): SupportedCodec {
+  const payload = message.p;
+  if (
+    payload &&
+    typeof payload === "object" &&
+    "codec" in payload &&
+    (payload as { codec?: unknown }).codec === "msgpack"
+  ) {
+    return "msgpack";
+  }
+  return "json";
+}
+
+function readSessionId(message: Envelope): string | undefined {
+  const payload = message.p;
+  if (
+    payload &&
+    typeof payload === "object" &&
+    "session_id" in payload &&
+    typeof (payload as { session_id?: unknown }).session_id === "string"
+  ) {
+    return (payload as { session_id: string }).session_id;
+  }
+  return undefined;
+}
+
+function readErrorReason(message: Envelope): string {
+  const payload = message.p;
+  if (
+    payload &&
+    typeof payload === "object" &&
+    "reason" in payload &&
+    typeof (payload as { reason?: unknown }).reason === "string"
+  ) {
+    return (payload as { reason: string }).reason;
+  }
+  return "server returned error";
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return (
+    Array.isArray(value) && value.every((item) => typeof item === "string")
+  );
+}
+
+function deepEqual(left: unknown, right: unknown): boolean {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function toJsonValue(bytes: Uint8Array): string {
+  let binary = "";
+  for (const value of bytes) {
+    binary += String.fromCharCode(value);
+  }
+  return btoa(binary);
+}
+
+function fromJsonValue(value: unknown): Uint8Array | null {
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  try {
+    const decoded = atob(value);
+    const bytes = new Uint8Array(decoded.length);
+    for (let i = 0; i < decoded.length; i += 1) {
+      bytes[i] = decoded.charCodeAt(i);
+    }
+    return bytes;
+  } catch {
+    return null;
+  }
+}
+
+function readRoomMessagePayload(payload: unknown): RoomMessagePayload | null {
+  if (!payload || typeof payload !== "object") {
+    return null;
+  }
+  const type = (payload as { type?: unknown }).type;
+  if (typeof type !== "string" && typeof type !== "number") {
+    return null;
+  }
+  const data = (payload as { data?: unknown }).data;
+  return { type, data };
+}
+
+export function parseMatchFoundPayload(payload: unknown): MatchFound | null {
+  if (!payload || typeof payload !== "object") {
+    return null;
+  }
+
+  const room = (payload as { room?: unknown }).room;
+  const roomType = (payload as { room_type?: unknown }).room_type;
+  const size = (payload as { size?: unknown }).size;
+  const participants = (payload as { participants?: unknown }).participants;
+  if (
+    typeof room !== "string" ||
+    typeof roomType !== "string" ||
+    typeof size !== "number" ||
+    !Number.isFinite(size) ||
+    !isStringArray(participants)
+  ) {
+    return null;
+  }
+
+  return {
+    room,
+    roomType,
+    size,
+    participants,
+  };
+}
+
+export class NexisRoom {
+  readonly id: string;
+  readonly onStateChange: RoomStateChangeSubscription;
+
+  constructor(
+    private readonly client: NexisClient,
+    roomId: string,
+  ) {
+    this.id = roomId;
+    this.onStateChange = this.buildStateChangeSubscription();
+  }
+
+  get state(): Record<string, unknown> {
+    return this.client.getRoomState(this.id);
+  }
+
+  send(type: RoomMessageType, message: unknown): void {
+    this.client.sendRoomMessage(this.id, type, message);
+  }
+
+  sendBytes(type: RoomMessageType, bytes: Uint8Array | number[]): void {
+    const normalized =
+      bytes instanceof Uint8Array ? bytes : Uint8Array.from(bytes);
+    this.client.sendRoomMessageBytes(this.id, type, normalized);
+  }
+
+  onMessage(type: RoomMessageType, callback: RoomMessageHandler): () => void {
+    return this.client.onRoomMessage(this.id, type, callback);
+  }
+
+  private buildStateChangeSubscription(): RoomStateChangeSubscription {
+    const subscribe = (callback: StateHandler): (() => void) =>
+      this.client.onRoomState(this.id, callback);
+
+    subscribe.once = (callback: StateHandler): (() => void) =>
+      this.client.onRoomStateOnce(this.id, callback);
+
+    subscribe.select = (
+      path: string,
+      callback: SelectorHandler,
+    ): (() => void) => this.client.onRoomStateSelect(this.id, path, callback);
+
+    return subscribe;
+  }
+}
+
+export class NexisClient {
+  private socket: WebSocket;
+  private readonly url: string;
+  private readonly connectOptions: ResolvedConnectOptions;
+  private readonly rpc = new RpcClient();
+  private codec: Codec;
+  private readonly eventHandlers = new Map<string, Set<EventHandler>>();
+  private readonly stateHandlers = new Set<StateHandler>();
+  private readonly roomStateHandlers = new Map<string, Set<StateHandler>>();
+  private readonly roomStateSelectors = new Map<
+    string,
+    Set<SelectorRegistration>
+  >();
+  private readonly roomMessageHandlers = new Map<
+    string,
+    Map<string, Set<RoomMessageHandler>>
+  >();
+  private readonly roomStates = new Map<string, Record<string, unknown>>();
+  private readonly roomSeq = new Map<string, number>();
+  private readonly roomChecksum = new Map<string, string>();
+  private sessionId: string | undefined;
+  private readonly autoJoinMatchedRoom: boolean;
+  private reconnecting = false;
+  private disposed = false;
+
+  private constructor(
+    url: string,
+    socket: WebSocket,
+    codec: Codec,
+    sessionId: string | undefined,
+    options: ResolvedConnectOptions,
+  ) {
+    this.url = url;
+    this.socket = socket;
+    this.codec = codec;
+    this.sessionId = sessionId;
+    this.connectOptions = options;
+    this.autoJoinMatchedRoom = options.autoJoinMatchedRoom;
+    this.attachSocket(socket);
+  }
+
+  static connect(url: string, options: ConnectOptions): Promise<NexisClient> {
+    const resolved = normalizeConnectOptions(options);
+    return NexisClient.openSocketAndHandshake(
+      url,
+      resolved,
+      resolved.sessionId,
+    ).then(
+      ({ socket, codec, sessionId }) =>
+        new NexisClient(url, socket, codec, sessionId, resolved),
+    );
+  }
+
+  close(): void {
+    this.disposed = true;
+    this.socket.close();
+  }
+
+  private attachSocket(socket: WebSocket): void {
+    this.socket = socket;
+    this.socket.addEventListener("message", (event) => {
+      void this.onRawMessage(event.data);
+    });
+    this.socket.addEventListener("close", () => {
+      this.rpc.rejectAll(new Error("socket closed"));
+      if (!this.disposed && this.connectOptions.autoReconnect) {
+        void this.tryReconnect();
+      }
+    });
+  }
+
+  private async tryReconnect(): Promise<void> {
+    if (this.reconnecting || this.disposed) {
+      return;
+    }
+    this.reconnecting = true;
+    this.dispatchEvent({
+      v: DEFAULT_VERSION,
+      t: "reconnect.start",
+      p: { session_id: this.sessionId },
+    });
+
+    let attempt = 0;
+    let delayMs = this.connectOptions.reconnectInitialDelayMs;
+    while (
+      !this.disposed &&
+      attempt < this.connectOptions.reconnectMaxAttempts
+    ) {
+      attempt += 1;
+      await NexisClient.wait(delayMs);
+      try {
+        const reconnect = await NexisClient.openSocketAndHandshake(
+          this.url,
+          this.connectOptions,
+          this.sessionId,
+        );
+        this.codec = reconnect.codec;
+        this.sessionId = reconnect.sessionId ?? this.sessionId;
+        this.attachSocket(reconnect.socket);
+        this.dispatchEvent({
+          v: DEFAULT_VERSION,
+          t: "reconnect.ok",
+          p: { attempt, session_id: this.sessionId },
+        });
+        this.reconnecting = false;
+        return;
+      } catch {
+        this.dispatchEvent({
+          v: DEFAULT_VERSION,
+          t: "reconnect.retry",
+          p: { attempt },
+        });
+      }
+      delayMs = Math.min(delayMs * 2, this.connectOptions.reconnectMaxDelayMs);
+    }
+
+    this.reconnecting = false;
+    this.dispatchEvent({
+      v: DEFAULT_VERSION,
+      t: "reconnect.failed",
+      p: { session_id: this.sessionId },
+    });
+  }
+
+  getSessionId(): string | undefined {
+    return this.sessionId;
+  }
+
+  room(roomId: string): NexisRoom {
+    return new NexisRoom(this, roomId);
+  }
+
+  async joinOrCreate(
+    roomType: string,
+    options?: { roomId?: string } & Record<string, unknown>,
+  ): Promise<NexisRoom> {
+    const roomId =
+      typeof options?.roomId === "string" ? options.roomId : undefined;
+    const response = await this.sendRPC(
+      "room.join_or_create",
+      {
+        roomType,
+        roomId,
+        options,
+      },
+      roomId,
+    );
+    if (
+      response &&
+      typeof response === "object" &&
+      typeof (response as { room?: unknown }).room === "string"
+    ) {
+      return this.room((response as { room: string }).room);
+    }
+    if (roomId) {
+      return this.room(roomId);
+    }
+    return this.room(`${roomType}:default`);
+  }
+
+  listRooms(roomType?: string): Promise<RoomListResponse> {
+    return this.sendRPC(
+      "room.list",
+      roomType ? { roomType } : {},
+    ) as Promise<RoomListResponse>;
+  }
+
+  enqueueMatchmaking(
+    roomType: string,
+    size = 2,
+  ): Promise<MatchmakingQueueResponse> {
+    return this.sendRPC("matchmaking.enqueue", {
+      roomType,
+      size,
+    }) as Promise<MatchmakingQueueResponse>;
+  }
+
+  dequeueMatchmaking(): Promise<MatchmakingDequeueResponse> {
+    return this.sendRPC(
+      "matchmaking.dequeue",
+      {},
+    ) as Promise<MatchmakingDequeueResponse>;
+  }
+
+  onStateChange(callback: StateHandler): () => void {
+    this.stateHandlers.add(callback);
+    return () => this.stateHandlers.delete(callback);
+  }
+
+  onEvent(type: string, callback: EventHandler): () => void {
+    const handlers = this.eventHandlers.get(type) ?? new Set<EventHandler>();
+    handlers.add(callback);
+    this.eventHandlers.set(type, handlers);
+    return () => {
+      const current = this.eventHandlers.get(type);
+      if (!current) {
+        return;
+      }
+      current.delete(callback);
+      if (current.size === 0) {
+        this.eventHandlers.delete(type);
+      }
+    };
+  }
+
+  onMatchFound(callback: MatchFoundHandler): () => void {
+    return this.onEvent("match.found", (message) => {
+      const parsed = parseMatchFoundPayload(message.p);
+      if (!parsed) {
+        return;
+      }
+      callback(parsed, message);
+    });
+  }
+
+  sendRPC(type: string, payload: unknown, room?: string): Promise<unknown> {
+    const { message, promise } = this.rpc.createRequest(type, payload, room);
+    this.sendEnvelope(message);
+    return promise;
+  }
+
+  getRoomState(roomId: string): Record<string, unknown> {
+    return this.roomStates.get(roomId) ?? {};
+  }
+
+  sendRoomMessage(roomId: string, type: RoomMessageType, data: unknown): void {
+    this.sendEnvelope({
+      v: DEFAULT_VERSION,
+      t: "room.message",
+      room: roomId,
+      p: { type: String(type), data },
+    });
+  }
+
+  sendRoomMessageBytes(
+    roomId: string,
+    type: RoomMessageType,
+    data: Uint8Array,
+  ): void {
+    this.sendEnvelope({
+      v: DEFAULT_VERSION,
+      t: "room.message.bytes",
+      room: roomId,
+      p: { type: String(type), data_b64: toJsonValue(data) },
+    });
+  }
+
+  onRoomMessage(
+    roomId: string,
+    type: RoomMessageType,
+    callback: RoomMessageHandler,
+  ): () => void {
+    const key = String(type);
+    const byType = this.roomMessageHandlers.get(roomId) ?? new Map();
+    const handlers = byType.get(key) ?? new Set<RoomMessageHandler>();
+    handlers.add(callback);
+    byType.set(key, handlers);
+    this.roomMessageHandlers.set(roomId, byType);
+
+    return () => {
+      const roomHandlers = this.roomMessageHandlers.get(roomId);
+      if (!roomHandlers) {
+        return;
+      }
+      const typeHandlers = roomHandlers.get(key);
+      if (!typeHandlers) {
+        return;
+      }
+      typeHandlers.delete(callback);
+      if (typeHandlers.size === 0) {
+        roomHandlers.delete(key);
+      }
+      if (roomHandlers.size === 0) {
+        this.roomMessageHandlers.delete(roomId);
+      }
+    };
+  }
+
+  onRoomState(roomId: string, callback: StateHandler): () => void {
+    const handlers =
+      this.roomStateHandlers.get(roomId) ?? new Set<StateHandler>();
+    handlers.add(callback);
+    this.roomStateHandlers.set(roomId, handlers);
+    if (this.roomStates.has(roomId)) {
+      callback(this.roomStates.get(roomId) ?? {});
+    }
+    return () => {
+      const current = this.roomStateHandlers.get(roomId);
+      if (!current) {
+        return;
+      }
+      current.delete(callback);
+      if (current.size === 0) {
+        this.roomStateHandlers.delete(roomId);
+      }
+    };
+  }
+
+  onRoomStateOnce(roomId: string, callback: StateHandler): () => void {
+    let disposed = false;
+    const off = this.onRoomState(roomId, (state) => {
+      if (disposed) {
+        return;
+      }
+      disposed = true;
+      off();
+      callback(state);
+    });
+    return () => {
+      disposed = true;
+      off();
+    };
+  }
+
+  onRoomStateSelect(
+    roomId: string,
+    path: string,
+    callback: SelectorHandler,
+  ): () => void {
+    const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
+    const currentState = this.getRoomState(roomId);
+    const registration: SelectorRegistration = {
+      path: normalizedPath,
+      callback,
+      lastValue: currentState[normalizedPath],
+    };
+    const selectors = this.roomStateSelectors.get(roomId) ?? new Set();
+    selectors.add(registration);
+    this.roomStateSelectors.set(roomId, selectors);
+
+    return () => {
+      const current = this.roomStateSelectors.get(roomId);
+      if (!current) {
+        return;
+      }
+      current.delete(registration);
+      if (current.size === 0) {
+        this.roomStateSelectors.delete(roomId);
+      }
+    };
+  }
+
+  private sendEnvelope(message: Envelope): void {
+    const bytes = this.codec.encode(message);
+    this.socket.send(bytes);
+  }
+
+  private dispatchEvent(message: Envelope): void {
+    const handlers = this.eventHandlers.get(message.t);
+    if (!handlers) {
+      return;
+    }
+
+    for (const handler of handlers) {
+      handler(message);
+    }
+  }
+
+  private dispatchState(
+    roomId: string,
+    nextState: Record<string, unknown>,
+    prevState: Record<string, unknown>,
+  ): void {
+    for (const handler of this.stateHandlers) {
+      handler(nextState);
+    }
+
+    const roomHandlers = this.roomStateHandlers.get(roomId);
+    if (roomHandlers) {
+      for (const handler of roomHandlers) {
+        handler(nextState);
+      }
+    }
+
+    const selectors = this.roomStateSelectors.get(roomId);
+    if (selectors) {
+      for (const registration of selectors) {
+        const nextValue = nextState[registration.path];
+        const prevValue = prevState[registration.path];
+        if (!deepEqual(nextValue, prevValue)) {
+          registration.lastValue = nextValue;
+          registration.callback(nextValue, nextState);
+        }
+      }
+    }
+  }
+
+  private dispatchRoomMessage(message: Envelope): void {
+    if (!message.room) {
+      return;
+    }
+
+    const payload = readRoomMessagePayload(message.p);
+    if (!payload) {
+      return;
+    }
+
+    const byType = this.roomMessageHandlers.get(message.room);
+    if (!byType) {
+      return;
+    }
+
+    const handlers = byType.get(String(payload.type));
+    if (!handlers) {
+      return;
+    }
+    for (const handler of handlers) {
+      handler(payload.data, message);
+    }
+  }
+
+  private async onRawMessage(raw: unknown): Promise<void> {
+    const bytes = await NexisClient.toBytes(raw);
+    if (!bytes) {
+      return;
+    }
+
+    let message: Envelope;
+    try {
+      message = this.codec.decode(bytes);
+    } catch {
+      return;
+    }
+
+    if (message.t === "rpc.response") {
+      try {
+        this.rpc.resolveResponse(message);
+      } catch (error) {
+        if (error instanceof UnknownRidError) {
+          this.dispatchEvent({
+            v: DEFAULT_VERSION,
+            t: "error",
+            p: { reason: error.message },
+          });
+          return;
+        }
+        throw error;
+      }
+      return;
+    }
+
+    if (message.t === "state.snapshot") {
+      if (!message.room) {
+        return;
+      }
+      const snapshot = parseSnapshotPayload(message.p);
+      if (!snapshot) {
+        return;
+      }
+      const computedChecksum = await computeStateChecksum(snapshot.state);
+      if (snapshot.checksum && snapshot.checksum !== computedChecksum) {
+        this.sendEnvelope({
+          v: DEFAULT_VERSION,
+          t: "state.resync",
+          room: message.room,
+          p: { since: this.roomSeq.get(message.room) ?? 0 },
+        });
+        return;
+      }
+      const checksum = snapshot.checksum ?? computedChecksum;
+
+      const prevState = this.roomStates.get(message.room) ?? {};
+      this.roomStates.set(message.room, snapshot.state);
+      this.roomSeq.set(message.room, snapshot.seq);
+      this.roomChecksum.set(message.room, checksum);
+      this.dispatchState(message.room, snapshot.state, prevState);
+      this.sendEnvelope({
+        v: DEFAULT_VERSION,
+        t: "state.ack",
+        room: message.room,
+        p: { seq: snapshot.seq, checksum },
+      });
+      return;
+    }
+
+    if (message.t === "state.patch") {
+      if (!message.room) {
+        return;
+      }
+      const parsedPatch = parsePatchPayload(message.p);
+      if (!parsedPatch) {
+        return;
+      }
+
+      const currentSeq = this.roomSeq.get(message.room) ?? 0;
+      const patchSeq = parsedPatch.seq > 0 ? parsedPatch.seq : currentSeq + 1;
+
+      if (patchSeq <= currentSeq) {
+        return;
+      }
+
+      if (patchSeq > currentSeq + 1) {
+        this.sendEnvelope({
+          v: DEFAULT_VERSION,
+          t: "state.resync",
+          room: message.room,
+          p: { since: currentSeq },
+        });
+        return;
+      }
+
+      const currentState = this.roomStates.get(message.room) ?? {};
+      const nextState = applyPatch(currentState, parsedPatch.ops);
+      let localChecksum: string | undefined;
+      if (parsedPatch.checksum) {
+        localChecksum = await computeStateChecksum(nextState);
+        if (parsedPatch.checksum !== localChecksum) {
+          this.sendEnvelope({
+            v: DEFAULT_VERSION,
+            t: "state.resync",
+            room: message.room,
+            p: {
+              since: currentSeq,
+              checksum: this.roomChecksum.get(message.room),
+            },
+          });
+          return;
+        }
+      }
+
+      this.roomStates.set(message.room, nextState);
+      this.roomSeq.set(message.room, patchSeq);
+      if (parsedPatch.checksum) {
+        this.roomChecksum.set(message.room, parsedPatch.checksum);
+      } else if (localChecksum) {
+        this.roomChecksum.set(message.room, localChecksum);
+      }
+      this.dispatchState(message.room, nextState, currentState);
+      this.sendEnvelope({
+        v: DEFAULT_VERSION,
+        t: "state.ack",
+        room: message.room,
+        p: parsedPatch.checksum
+          ? { seq: patchSeq, checksum: this.roomChecksum.get(message.room) }
+          : { seq: patchSeq },
+      });
+      return;
+    }
+
+    if (this.autoJoinMatchedRoom && message.t === "match.found") {
+      const parsed = parseMatchFoundPayload(message.p);
+      if (parsed) {
+        void this.joinOrCreate(parsed.roomType, { roomId: parsed.room }).catch(
+          () => undefined,
+        );
+      }
+    }
+
+    if (message.t === "room.message" && message.room) {
+      this.dispatchRoomMessage(message);
+    }
+
+    this.dispatchEvent(message);
+  }
+
+  private static openSocketAndHandshake(
+    url: string,
+    options: ResolvedConnectOptions,
+    sessionIdOverride?: string,
+  ): Promise<{
+    socket: WebSocket;
+    codec: Codec;
+    sessionId: string | undefined;
+  }> {
+    const socket = new WebSocket(url);
+    const jsonCodec = new JsonCodec();
+    const msgpackCodec = new MsgpackCodec();
+
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const handshakeSessionId = sessionIdOverride ?? options.sessionId;
+
+      const onOpen = () => {
+        const handshake: HandshakeRequest = {
+          v: DEFAULT_VERSION,
+          codecs: options.codecs,
+          project_id: options.projectId?.trim() || "anonymous",
+          token: options.token?.trim() || "",
+          session_id: handshakeSessionId,
+        };
+        socket.send(JSON.stringify(handshake));
+      };
+
+      const onError = () => {
+        finishReject(new Error("socket connection failed"));
+      };
+
+      const onClose = () => {
+        finishReject(new Error("socket closed before handshake"));
+      };
+
+      const onMessage = async (event: MessageEvent) => {
+        try {
+          const message = await NexisClient.decodeHandshakeMessage(
+            event.data,
+            jsonCodec,
+            msgpackCodec,
+          );
+          if (!message) {
+            return;
+          }
+
+          if (message.t === "error") {
+            finishReject(new Error(readErrorReason(message)));
+            return;
+          }
+
+          if (message.t !== "handshake.ok") {
+            return;
+          }
+
+          const negotiatedCodec = readCodecName(message);
+          const sessionId = readSessionId(message) ?? handshakeSessionId;
+          finishResolve({
+            socket,
+            codec: codecFor(negotiatedCodec),
+            sessionId,
+          });
+        } catch (error) {
+          finishReject(new Error(`handshake decode failed: ${String(error)}`));
+        }
+      };
+
+      const cleanup = () => {
+        socket.removeEventListener("open", onOpen);
+        socket.removeEventListener("error", onError);
+        socket.removeEventListener("close", onClose);
+        socket.removeEventListener("message", onMessage);
+      };
+
+      const finishResolve = (result: {
+        socket: WebSocket;
+        codec: Codec;
+        sessionId: string | undefined;
+      }) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        cleanup();
+        resolve(result);
+      };
+
+      const finishReject = (error: Error) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        cleanup();
+        reject(error);
+      };
+
+      socket.addEventListener("open", onOpen);
+      socket.addEventListener("error", onError);
+      socket.addEventListener("close", onClose);
+      socket.addEventListener("message", onMessage);
+    });
+  }
+
+  private static wait(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
+  private static async decodeHandshakeMessage(
+    raw: unknown,
+    jsonCodec: JsonCodec,
+    msgpackCodec: MsgpackCodec,
+  ): Promise<Envelope | null> {
+    if (typeof raw === "string") {
+      return JSON.parse(raw) as Envelope;
+    }
+
+    const bytes = await NexisClient.toBytes(raw);
+    if (!bytes) {
+      return null;
+    }
+
+    try {
+      return msgpackCodec.decode(bytes);
+    } catch {
+      return jsonCodec.decode(bytes);
+    }
+  }
+
+  private static async toBytes(raw: unknown): Promise<Uint8Array | null> {
+    if (raw instanceof Uint8Array) {
+      return raw;
+    }
+    if (raw instanceof ArrayBuffer) {
+      return new Uint8Array(raw);
+    }
+    if (raw instanceof Blob) {
+      return new Uint8Array(await raw.arrayBuffer());
+    }
+    if (typeof raw === "string") {
+      return new TextEncoder().encode(raw);
+    }
+    return null;
+  }
+}
+
+export async function connect(
+  url: string,
+  options: ConnectOptions,
+): Promise<NexisClient> {
+  return NexisClient.connect(url, options);
+}
+
+export function decodeRoomBytes(payload: unknown): Uint8Array | null {
+  return fromJsonValue(payload);
+}

package/src/codec.ts

@@ -0,0 +1,48 @@
+import { Packr, Unpackr } from "msgpackr";
+import type { Envelope } from "./types";
+
+export interface Codec {
+  readonly name: "json" | "msgpack";
+  encode(message: Envelope): Uint8Array;
+  decode(bytes: Uint8Array): Envelope;
+}
+
+export class JsonCodec implements Codec {
+  readonly name = "json" as const;
+
+  encode(message: Envelope): Uint8Array {
+    return new TextEncoder().encode(JSON.stringify(message));
+  }
+
+  decode(bytes: Uint8Array): Envelope {
+    const text = new TextDecoder().decode(bytes);
+    const parsed = JSON.parse(text);
+    return parsed as Envelope;
+  }
+}
+
+export class MsgpackCodec implements Codec {
+  readonly name = "msgpack" as const;
+  private readonly packr = new Packr({
+    useRecords: false,
+    structuredClone: false,
+    bundleStrings: false,
+    maxSharedStructures: 0,
+  });
+  private readonly unpackr = new Unpackr({
+    useRecords: false,
+  });
+
+  encode(message: Envelope): Uint8Array {
+    return this.packr.pack(message);
+  }
+
+  decode(bytes: Uint8Array): Envelope {
+    const decoded = this.unpackr.unpack(bytes);
+    return decoded as Envelope;
+  }
+}
+
+export function codecFor(name: "json" | "msgpack"): Codec {
+  return name === "msgpack" ? new MsgpackCodec() : new JsonCodec();
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./types";
+export * from "./codec";
+export * from "./patch";
+export * from "./rpc";
+export * from "./client";

package/src/patch.ts

@@ -0,0 +1,128 @@
+import type { PatchOp, StatePatchPayload, StateSnapshotPayload } from "./types";
+
+function keyFromPath(path: string): string {
+  if (!path.startsWith("/")) {
+    throw new Error(`Invalid patch path: ${path}`);
+  }
+  const key = path.slice(1);
+  if (!key || key.includes("/")) {
+    throw new Error(`Invalid patch path: ${path}`);
+  }
+  return key.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+
+export function applyPatch<T extends Record<string, unknown>>(
+  state: T,
+  patch: PatchOp[],
+): T {
+  const next: Record<string, unknown> = { ...state };
+
+  for (const op of patch) {
+    const key = keyFromPath(op.path);
+    if (op.op === "set") {
+      next[key] = op.value;
+      continue;
+    }
+    delete next[key];
+  }
+
+  return next as T;
+}
+
+function canonicalize(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => canonicalize(item));
+  }
+
+  if (value && typeof value === "object") {
+    const sortedEntries = Object.entries(value as Record<string, unknown>).sort(
+      ([left], [right]) => left.localeCompare(right),
+    );
+    const normalized: Record<string, unknown> = {};
+    for (const [key, item] of sortedEntries) {
+      normalized[key] = canonicalize(item);
+    }
+    return normalized;
+  }
+
+  return value;
+}
+
+export async function computeStateChecksum(state: unknown): Promise<string> {
+  const cryptoApi = globalThis.crypto?.subtle;
+  if (!cryptoApi) {
+    throw new Error("crypto.subtle is unavailable");
+  }
+
+  const canonicalJson = JSON.stringify(canonicalize(state));
+  const bytes = new TextEncoder().encode(canonicalJson);
+  const digest = await cryptoApi.digest("SHA-256", bytes);
+  const hashBytes = new Uint8Array(digest);
+
+  return Array.from(hashBytes)
+    .map((value) => value.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+export function parsePatchPayload(payload: unknown): StatePatchPayload | null {
+  if (Array.isArray(payload)) {
+    return {
+      seq: 0,
+      checksum: undefined,
+      ops: payload as PatchOp[],
+    };
+  }
+
+  if (!payload || typeof payload !== "object") {
+    return null;
+  }
+
+  const candidate = payload as {
+    seq?: unknown;
+    checksum?: unknown;
+    ops?: unknown;
+  };
+  if (
+    typeof candidate.seq !== "number" ||
+    !Array.isArray(candidate.ops) ||
+    (candidate.checksum !== undefined && typeof candidate.checksum !== "string")
+  ) {
+    return null;
+  }
+
+  return {
+    seq: candidate.seq,
+    checksum: candidate.checksum as string | undefined,
+    ops: candidate.ops as PatchOp[],
+  };
+}
+
+export function parseSnapshotPayload(
+  payload: unknown,
+): StateSnapshotPayload | null {
+  if (!payload || typeof payload !== "object") {
+    return null;
+  }
+
+  const candidate = payload as {
+    seq?: unknown;
+    checksum?: unknown;
+    state?: unknown;
+  };
+  if (
+    typeof candidate.seq !== "number" ||
+    (candidate.checksum !== undefined &&
+      typeof candidate.checksum !== "string") ||
+    !candidate.state ||
+    typeof candidate.state !== "object" ||
+    Array.isArray(candidate.state)
+  ) {
+    return null;
+  }
+
+  return {
+    seq: candidate.seq,
+    checksum: candidate.checksum as string | undefined,
+    state: candidate.state as Record<string, unknown>,
+  };
+}

package/src/rpc.ts

@@ -0,0 +1,54 @@
+import type { Envelope } from "./types";
+
+export class UnknownRidError extends Error {
+  constructor(rid: string) {
+    super(`Unknown RPC rid: ${rid}`);
+  }
+}
+
+export class RpcClient {
+  private nextId = 1;
+  private pending = new Map<
+    string,
+    { resolve: (payload: unknown) => void; reject: (error: Error) => void }
+  >();
+
+  createRequest(
+    type: string,
+    payload: unknown,
+    room?: string,
+  ): { message: Envelope; promise: Promise<unknown> } {
+    const rid = `rpc-${this.nextId++}`;
+    const message: Envelope = { v: 1, t: type, rid, p: payload };
+    if (room !== undefined) {
+      message.room = room;
+    }
+    const promise = new Promise<unknown>((resolve, reject) => {
+      this.pending.set(rid, { resolve, reject });
+    });
+
+    return { message, promise };
+  }
+
+  resolveResponse(response: Envelope): void {
+    const rid = response.rid;
+    if (!rid) {
+      throw new UnknownRidError("missing");
+    }
+
+    const pending = this.pending.get(rid);
+    if (!pending) {
+      throw new UnknownRidError(rid);
+    }
+
+    this.pending.delete(rid);
+    pending.resolve(response.p);
+  }
+
+  rejectAll(error: Error): void {
+    for (const pending of this.pending.values()) {
+      pending.reject(error);
+    }
+    this.pending.clear();
+  }
+}

package/src/types.ts

@@ -0,0 +1,82 @@
+export type Envelope = {
+  v: number;
+  t: string;
+  rid?: string;
+  room?: string;
+  p?: unknown;
+};
+
+export type HandshakeRequest = {
+  v: number;
+  codecs: string[];
+  project_id: string;
+  token: string;
+  session_id?: string;
+};
+
+export type ConnectOptions = {
+  projectId?: string;
+  token?: string;
+  codecs?: Array<"msgpack" | "json">;
+  sessionId?: string;
+  autoJoinMatchedRoom?: boolean;
+  autoReconnect?: boolean;
+  reconnectInitialDelayMs?: number;
+  reconnectMaxDelayMs?: number;
+  reconnectMaxAttempts?: number;
+};
+
+export type RoomSummary = {
+  id: string;
+  room_type: string;
+  members: number;
+};
+
+export type RoomListResponse = {
+  ok: boolean;
+  rooms: RoomSummary[];
+};
+
+export type MatchFound = {
+  room: string;
+  roomType: string;
+  size: number;
+  participants: string[];
+};
+
+export type MatchmakingQueueResponse = {
+  ok: boolean;
+  queued?: boolean;
+  matched?: boolean;
+  room_type?: string;
+  size?: number;
+  position?: number;
+};
+
+export type MatchmakingDequeueResponse = {
+  ok: boolean;
+  removed: boolean;
+};
+
+export type PatchOp =
+  | { op: "set"; path: string; value: unknown }
+  | { op: "del"; path: string };
+
+export type StatePatchPayload = {
+  seq: number;
+  checksum?: string;
+  ops: PatchOp[];
+};
+
+export type StateSnapshotPayload = {
+  seq: number;
+  checksum?: string;
+  state: Record<string, unknown>;
+};
+
+export type RoomMessageType = string | number;
+
+export type RoomMessagePayload = {
+  type: RoomMessageType;
+  data: unknown;
+};

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "declaration": true,
+    "outDir": "dist",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+  },
+  "include": ["src"],
+}