@shadow-js/realtime 0.0.0-stage → 1.0.0

package/dist/dev/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","names":[],"sources":["../../src/memory.ts"],"sourcesContent":["import type {\n  Adapter,\n  HistoryResult,\n  PresenceRef,\n  PublishOptions,\n  PublishResult,\n  Unsubscribe,\n} from \"./adapter\";\nimport type { Member, PresenceEvent, StoredEntry, StoredMessage } from \"./protocol\";\n\ninterface ChannelState {\n  seq: number;\n  log: StoredMessage[];\n  readonly keys: Map<string, { readonly seq: number; readonly expires: number }>;\n  readonly listeners: Set<(message: StoredMessage) => void>;\n  readonly pending: StoredMessage[];\n  draining: boolean;\n  lastActive: number;\n}\n\ninterface PresenceEntry {\n  member: Member;\n  expires: number;\n}\n\n/**\n * Options of {@link memoryAdapter}.\n * @since 1.0.0\n */\nexport interface MemoryAdapterOptions {\n  /** The clock, in epoch milliseconds. Default: `Date.now`. */\n  readonly now?: () => number;\n  /**\n   * Milliseconds a channel with no listener and no retained message is remembered. After that its head is forgotten and its\n   * numbering restarts, which a resuming client sees as `reset`. Default: one hour.\n   */\n  readonly idleMs?: number;\n}\n\n/**\n * The single-process adapter, and the default of `createHub`. Messages, history, idempotency keys and presence live in memory\n * of this process; several hubs created over one adapter object share them, which is how tests exercise two servers. Use the Redis\n * or Cloudflare adapter when more than one process serves clients.\n *\n * @param options The clock.\n * @returns The adapter.\n * @example\n * import { createHub, memoryAdapter } from \"@shadow-js/realtime/server\";\n *\n * const adapter = memoryAdapter();\n * const hub = createHub({ adapter });\n * void hub.close();\n * @since 1.0.0\n */\nexport function memoryAdapter(options: MemoryAdapterOptions = {}): Adapter {\n  const now = options.now ?? Date.now;\n  const idleMs = options.idleMs ?? 3_600_000;\n  let sweepAt = 1024;\n  const channels = new Map<string, ChannelState>();\n  const presence = new Map<string, Map<string, PresenceEntry>>();\n  const presenceListeners = new Map<string, Set<(event: PresenceEvent) => void>>();\n  const presenceQueue: PresenceEvent[] = [];\n  let presenceDraining = false;\n  let closed = false;\n\n  /** Forgets channels nobody listens to and nothing retains; runs when the table has doubled since the last sweep. */\n  function sweep(): void {\n    const cutoff = now() - idleMs;\n    for (const [name, state] of channels)\n      if (state.listeners.size === 0 && state.lastActive < cutoff) {\n        trim(state, state.log.length, idleMs);\n        if (state.log.length === 0) channels.delete(name);\n      }\n    sweepAt = Math.max(1024, channels.size * 2);\n  }\n\n  function channelOf(name: string): ChannelState {\n    let state = channels.get(name);\n    if (state === undefined) {\n      if (channels.size >= sweepAt) sweep();\n      state = {\n        lastActive: now(),\n        seq: 0,\n        log: [],\n        keys: new Map(),\n        listeners: new Set(),\n        pending: [],\n        draining: false,\n      };\n      channels.set(name, state);\n    }\n    state.lastActive = now();\n    return state;\n  }\n\n  /** Delivers queued messages in order; a listener that publishes in turn queues behind the message being delivered. */\n  function drain(state: ChannelState): void {\n    if (state.draining) return;\n    state.draining = true;\n    try {\n      for (let next = state.pending.shift(); next !== undefined; next = state.pending.shift()) {\n        for (const listener of [...state.listeners]) {\n          try {\n            listener(next);\n          } catch {\n            // A listener's failure is its own: delivery to the others goes on (guarantee G13).\n          }\n        }\n      }\n    } finally {\n      state.draining = false;\n    }\n  }\n\n  function emitPresence(event: PresenceEvent): void {\n    presenceQueue.push(event);\n    if (presenceDraining) return;\n    presenceDraining = true;\n    try {\n      for (let next = presenceQueue.shift(); next !== undefined; next = presenceQueue.shift()) {\n        for (const listener of [...(presenceListeners.get(next.channel) ?? [])]) {\n          try {\n            listener(next);\n          } catch {\n            // See `drain`.\n          }\n        }\n      }\n    } finally {\n      presenceDraining = false;\n    }\n  }\n\n  function trim(state: ChannelState, history: number, ttl: number): void {\n    const cutoff = now() - ttl;\n    let drop = Math.max(0, state.log.length - history);\n    while (drop < state.log.length && (state.log[drop]?.at ?? Infinity) < cutoff) drop += 1;\n    if (drop > 0) state.log = state.log.slice(drop);\n  }\n\n  function live(name: string): Map<string, PresenceEntry> {\n    let set = presence.get(name);\n    if (set === undefined) {\n      set = new Map();\n      presence.set(name, set);\n    }\n    return set;\n  }\n\n  function check(): void {\n    if (closed) throw new Error(\"the adapter is closed.\");\n  }\n\n  return {\n    async publish(\n      channel: string,\n      entry: StoredEntry,\n      publish: PublishOptions,\n    ): Promise<PublishResult> {\n      check();\n      const state = channelOf(channel);\n      const at = now();\n      if (publish.key !== undefined) {\n        const known = state.keys.get(publish.key);\n        if (known !== undefined && known.expires > at) return { seq: known.seq, duplicate: true };\n        // Expired keys are swept when a new one is added, so the map stays bounded by the rate of publishes.\n        if (state.keys.size >= 4096)\n          for (const [key, value] of state.keys) if (value.expires <= at) state.keys.delete(key);\n      }\n      state.seq += 1;\n      const message: StoredMessage = { ...entry, seq: state.seq, at };\n      if (publish.key !== undefined)\n        state.keys.set(publish.key, {\n          seq: state.seq,\n          expires: at + publish.idempotencyTtlMs,\n        });\n      if (publish.history > 0) {\n        state.log.push(message);\n        trim(state, publish.history, publish.historyTtlMs);\n      } else {\n        state.log = [];\n      }\n      state.pending.push(message);\n      drain(state);\n      return { seq: message.seq, duplicate: false };\n    },\n\n    async subscribe(\n      channel: string,\n      listener: (message: StoredMessage) => void,\n    ): Promise<Unsubscribe> {\n      check();\n      const state = channelOf(channel);\n      state.listeners.add(listener);\n      return async () => {\n        state.listeners.delete(listener);\n      };\n    },\n\n    async history(channel: string, after: number, limit: number): Promise<HistoryResult> {\n      check();\n      const state = channels.get(channel);\n      if (state === undefined) return { messages: [], head: 0, oldest: 0 };\n      const retained = state.log;\n      const messages: StoredMessage[] = [];\n      for (const message of retained) {\n        if (messages.length >= limit) break;\n        if (message.seq > after) messages.push(message);\n      }\n      return { messages, head: state.seq, oldest: retained[0]?.seq ?? 0 };\n    },\n\n    async presenceSet(channel: string, member: Member, ttlMs: number): Promise<void> {\n      check();\n      const set = live(channel);\n      const known = set.get(member.id);\n      if (known !== undefined && known.member.v > member.v) return;\n      set.set(member.id, { member, expires: now() + ttlMs });\n      if (known === undefined) emitPresence({ channel, op: \"join\", member });\n      else if (known.member.v < member.v) emitPresence({ channel, op: \"set\", member });\n    },\n\n    async presenceRemove(channel: string, id: string): Promise<boolean> {\n      check();\n      const set = presence.get(channel);\n      const known = set?.get(id);\n      if (set === undefined || known === undefined) return false;\n      set.delete(id);\n      if (set.size === 0) presence.delete(channel);\n      emitPresence({ channel, op: \"leave\", member: known.member });\n      return true;\n    },\n\n    async presenceList(channel: string): Promise<readonly Member[]> {\n      check();\n      const at = now();\n      const out: Member[] = [];\n      for (const entry of presence.get(channel)?.values() ?? [])\n        if (entry.expires > at) out.push(entry.member);\n      return out;\n    },\n\n    async presenceTouch(entries, ttlMs): Promise<readonly PresenceRef[]> {\n      check();\n      const expires = now() + ttlMs;\n      const missing: PresenceRef[] = [];\n      for (const ref of entries) {\n        const entry = presence.get(ref.channel)?.get(ref.id);\n        if (entry === undefined) missing.push(ref);\n        else entry.expires = expires;\n      }\n      return missing;\n    },\n\n    async presenceReap(channel: string): Promise<readonly Member[]> {\n      check();\n      const set = presence.get(channel);\n      if (set === undefined) return [];\n      const at = now();\n      const removed: Member[] = [];\n      for (const [id, entry] of [...set]) {\n        if (entry.expires > at) continue;\n        set.delete(id);\n        removed.push(entry.member);\n        emitPresence({ channel, op: \"leave\", member: entry.member });\n      }\n      if (set.size === 0) presence.delete(channel);\n      return removed;\n    },\n\n    async presenceSubscribe(\n      channel: string,\n      listener: (event: PresenceEvent) => void,\n    ): Promise<Unsubscribe> {\n      check();\n      let set = presenceListeners.get(channel);\n      if (set === undefined) {\n        set = new Set();\n        presenceListeners.set(channel, set);\n      }\n      set.add(listener);\n      const owner = set;\n      return async () => {\n        owner.delete(listener);\n        if (owner.size === 0 && presenceListeners.get(channel) === owner)\n          presenceListeners.delete(channel);\n      };\n    },\n\n    async close(): Promise<void> {\n      closed = true;\n      channels.clear();\n      presence.clear();\n      presenceListeners.clear();\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/dev/protocol.d.ts

@@ -0,0 +1,211 @@
+import { ErrorCode } from "./errors.js";
+//#region src/protocol.d.ts
+/**
+ * The wire protocol version this package speaks (https://realtime.shadowjs.net/guides/realtime-protocol/).
+ * @example
+ * import { PROTOCOL_VERSION } from "@shadow-js/realtime";
+ *
+ * const hello = JSON.stringify({ t: "hello", v: PROTOCOL_VERSION });
+ * @since 1.0.0
+ */
+export declare const PROTOCOL_VERSION: 1;
+/**
+ * Any JSON value.
+ * @since 1.0.0
+ */
+export type Json = null | boolean | number | string | readonly Json[] | {
+  readonly [key: string]: Json;
+};
+/**
+ * One member of a channel's presence set: the connection that joined, its user, its state, and the version of that state.
+ * @since 1.0.0
+ */
+export interface Member<State = Json> {
+  /** The connection id. */
+  readonly id: string;
+  /** The user of the connection's identity, when it has one. */
+  readonly u?: string;
+  /** The member's state. */
+  readonly s: State;
+  /** A counter that rises with every state change of this member, from 1. */
+  readonly v: number;
+}
+/** A message as stored by an adapter: the data is its JSON text. @since 1.0.0 */
+export interface StoredMessage {
+  readonly seq: number;
+  readonly event: string;
+  /** The JSON text of the data. */
+  readonly data: string;
+  /** The publishing connection id, when a connection published it. */
+  readonly publisher?: string;
+  /** The publishing user, when it has one. */
+  readonly user?: string;
+  /** When the adapter accepted it, in epoch milliseconds. */
+  readonly at: number;
+}
+/** What a publisher supplies; the adapter adds `seq` and `at`. @since 1.0.0 */
+export type StoredEntry = Omit<StoredMessage, "seq" | "at">;
+/** A change of a presence set, as adapters deliver it. @since 1.0.0 */
+export interface PresenceEvent {
+  readonly channel: string;
+  readonly op: "join" | "set" | "leave";
+  readonly member: Member;
+}
+/** Frames a client sends. @since 1.0.0 */
+export type ClientFrame = {
+  readonly t: "hello";
+  readonly v: number;
+} | {
+  readonly t: "sub";
+  readonly n: number;
+  readonly c: string;
+  readonly after?: number;
+  readonly echo?: boolean;
+  readonly presence?: Json;
+  readonly hasPresence: boolean;
+  readonly watch?: boolean;
+} | {
+  readonly t: "unsub";
+  readonly n?: number;
+  readonly c: string;
+} | {
+  readonly t: "pub";
+  readonly c: string;
+  readonly e: string;
+  readonly d: string;
+  readonly n?: number;
+  readonly k?: string;
+} | {
+  readonly t: "req";
+  readonly n: number;
+  readonly c: string;
+  readonly e: string;
+  readonly d: Json;
+  readonly ms?: number;
+} | {
+  readonly t: "pres";
+  readonly c: string;
+  readonly s: Json;
+} | {
+  readonly t: "ping";
+  readonly n?: number;
+};
+/** What decoding a client frame yields. @since 1.0.0 */
+export type DecodedClientFrame = {
+  readonly ok: true;
+  readonly frame: ClientFrame;
+} | {
+  readonly ok: false;
+  readonly code: ErrorCode;
+  readonly n?: number;
+  readonly why: string;
+};
+/**
+ * Whether `value` is a valid channel name: 1..128 characters of `A-Za-z0-9_.:/@-`, not starting with the reserved `$`.
+ * @param value The candidate.
+ * @returns True for a valid name.
+ * @example
+ * import { isChannelName } from "@shadow-js/realtime";
+ *
+ * isChannelName("chat:lobby"); // true
+ * isChannelName("chat lobby"); // false
+ * @since 1.0.0
+ */
+export declare function isChannelName(value: unknown): value is string;
+/**
+ * Whether `value` is a valid event name: 1..64 characters of `A-Za-z0-9_.:@-`.
+ * @param value The candidate.
+ * @returns True for a valid name.
+ * @example
+ * import { isEventName } from "@shadow-js/realtime";
+ *
+ * isEventName("message"); // true
+ * isEventName("a/b"); // false
+ * @since 1.0.0
+ */
+export declare function isEventName(value: unknown): value is string;
+/**
+ * Decodes and validates one client frame (server side). Never throws: any text yields a frame or a refusal.
+ *
+ * @param text The frame text.
+ * @param maxBytes The largest accepted frame, in UTF-8 bytes.
+ * @returns The frame, or the code and reason to refuse it with.
+ * @example
+ * import { decodeClientFrame } from "@shadow-js/realtime";
+ *
+ * const result = decodeClientFrame('{"t":"ping"}', 65_536);
+ * result.ok; // true
+ * @since 1.0.0
+ */
+export declare function decodeClientFrame(text: string, maxBytes: number): DecodedClientFrame;
+/** Frames a server sends, as a client reads them. @since 1.0.0 */
+export type ServerFrame = {
+  readonly t: "ready";
+  readonly v: number;
+  readonly id: string;
+  readonly hb: number;
+  readonly max: number;
+} | {
+  readonly t: "subbed";
+  readonly n: number;
+  readonly c: string;
+  readonly head: number;
+  readonly gap?: boolean;
+  readonly reset?: boolean;
+} | {
+  readonly t: "unsubbed";
+  readonly c: string;
+  readonly why?: string;
+} | {
+  readonly t: "msg";
+  readonly c: string;
+  readonly s: number;
+  readonly e: string;
+  readonly d: Json;
+  readonly p?: string;
+  readonly u?: string;
+  readonly r?: 1;
+} | {
+  readonly t: "ack";
+  readonly n: number;
+  readonly s: number;
+  readonly dup?: boolean;
+} | {
+  readonly t: "rep";
+  readonly n: number;
+  readonly d: Json;
+} | {
+  readonly t: "err";
+  readonly n?: number;
+  readonly c?: string;
+  readonly code: ErrorCode;
+  readonly msg?: string;
+} | {
+  readonly t: "pres";
+  readonly c: string;
+  readonly op: "sync" | "join" | "set" | "leave";
+  readonly m: Member | readonly Member[];
+} | {
+  readonly t: "pong";
+  readonly n?: number;
+} | {
+  readonly t: "bye";
+  readonly code: number;
+  readonly why: string;
+};
+/**
+ * Decodes one server frame (client side). Returns `undefined` for anything that is not a known, well-formed frame, so a
+ * client ignores what a newer server may send and never acts on a malformed frame.
+ *
+ * @param text The frame text.
+ * @returns The frame, or undefined.
+ * @example
+ * import { decodeServerFrame } from "@shadow-js/realtime";
+ *
+ * decodeServerFrame('{"t":"pong"}'); // { t: "pong" }
+ * decodeServerFrame("not json"); // undefined
+ * @since 1.0.0
+ */
+export declare function decodeServerFrame(text: string): ServerFrame | undefined;
+//#endregion
+//# sourceMappingURL=protocol.d.ts.map

package/dist/dev/protocol.js

@@ -0,0 +1,400 @@
+//#region src/protocol.ts
+/**
+* The wire protocol version this package speaks (https://realtime.shadowjs.net/guides/realtime-protocol/).
+* @example
+* import { PROTOCOL_VERSION } from "@shadow-js/realtime";
+*
+* const hello = JSON.stringify({ t: "hello", v: PROTOCOL_VERSION });
+* @since 1.0.0
+*/
+const PROTOCOL_VERSION = 1;
+const CHANNEL = /^[A-Za-z0-9_.:/@-]{1,128}$/;
+const EVENT = /^[A-Za-z0-9_.:@-]{1,64}$/;
+const KEY = /^[A-Za-z0-9_.:@-]{1,64}$/;
+const encoder = new TextEncoder();
+/**
+* Whether `value` is a valid channel name: 1..128 characters of `A-Za-z0-9_.:/@-`, not starting with the reserved `$`.
+* @param value The candidate.
+* @returns True for a valid name.
+* @example
+* import { isChannelName } from "@shadow-js/realtime";
+*
+* isChannelName("chat:lobby"); // true
+* isChannelName("chat lobby"); // false
+* @since 1.0.0
+*/
+function isChannelName(value) {
+	return typeof value === "string" && CHANNEL.test(value);
+}
+/**
+* Whether `value` is a valid event name: 1..64 characters of `A-Za-z0-9_.:@-`.
+* @param value The candidate.
+* @returns True for a valid name.
+* @example
+* import { isEventName } from "@shadow-js/realtime";
+*
+* isEventName("message"); // true
+* isEventName("a/b"); // false
+* @since 1.0.0
+*/
+function isEventName(value) {
+	return typeof value === "string" && EVENT.test(value);
+}
+/** Whether `value` is a valid idempotency key. @internal */
+function isIdempotencyKey(value) {
+	return typeof value === "string" && KEY.test(value);
+}
+/** The number of bytes of `text` in UTF-8, without encoding the common cases. @internal */
+function byteLength(text) {
+	if (text.length * 3 <= 2147483647) {
+		let ascii = true;
+		for (let at = 0; at < text.length; at += 1) if (text.charCodeAt(at) > 127) {
+			ascii = false;
+			break;
+		}
+		if (ascii) return text.length;
+	}
+	return encoder.encode(text).length;
+}
+function isCount(value) {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function bad(why, n) {
+	return isCount(n) ? {
+		ok: false,
+		code: "bad_frame",
+		n,
+		why
+	} : {
+		ok: false,
+		code: "bad_frame",
+		why
+	};
+}
+/**
+* Decodes and validates one client frame (server side). Never throws: any text yields a frame or a refusal.
+*
+* @param text The frame text.
+* @param maxBytes The largest accepted frame, in UTF-8 bytes.
+* @returns The frame, or the code and reason to refuse it with.
+* @example
+* import { decodeClientFrame } from "@shadow-js/realtime";
+*
+* const result = decodeClientFrame('{"t":"ping"}', 65_536);
+* result.ok; // true
+* @since 1.0.0
+*/
+function decodeClientFrame(text, maxBytes) {
+	if (byteLength(text) > maxBytes) return {
+		ok: false,
+		code: "too_large",
+		why: "the frame is larger than the limit"
+	};
+	let value;
+	try {
+		value = JSON.parse(text);
+	} catch {
+		return bad("the frame is not JSON");
+	}
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return bad("the frame is not an object");
+	const raw = value;
+	const type = raw["t"];
+	const n = raw["n"];
+	if (n !== void 0 && !isCount(n)) return bad("n must be a non-negative integer");
+	const c = raw["c"];
+	const needChannel = () => isChannelName(c) ? void 0 : {
+		...bad("c is not a valid channel name", n),
+		code: "bad_channel"
+	};
+	switch (type) {
+		case "hello": {
+			const v = raw["v"];
+			if (typeof v !== "number" || !Number.isInteger(v) || v < 1) return bad("v must be a version");
+			return {
+				ok: true,
+				frame: {
+					t: "hello",
+					v
+				}
+			};
+		}
+		case "ping": return {
+			ok: true,
+			frame: n === void 0 ? { t: "ping" } : {
+				t: "ping",
+				n
+			}
+		};
+		case "sub": {
+			const refusal = needChannel();
+			if (refusal !== void 0) return refusal;
+			if (n === void 0) return bad("sub needs n");
+			const after = raw["after"];
+			if (after !== void 0 && !isCount(after)) return bad("after must be a non-negative integer", n);
+			const echo = raw["echo"];
+			if (echo !== void 0 && typeof echo !== "boolean") return bad("echo must be a boolean", n);
+			const watch = raw["watch"];
+			if (watch !== void 0 && typeof watch !== "boolean") return bad("watch must be a boolean", n);
+			const hasPresence = "presence" in raw;
+			return {
+				ok: true,
+				frame: {
+					t: "sub",
+					n,
+					c,
+					hasPresence,
+					...after === void 0 ? {} : { after },
+					...echo === void 0 ? {} : { echo },
+					...watch === void 0 ? {} : { watch },
+					...hasPresence ? { presence: raw["presence"] } : {}
+				}
+			};
+		}
+		case "unsub": {
+			const refusal = needChannel();
+			if (refusal !== void 0) return refusal;
+			return {
+				ok: true,
+				frame: n === void 0 ? {
+					t: "unsub",
+					c
+				} : {
+					t: "unsub",
+					n,
+					c
+				}
+			};
+		}
+		case "pub": {
+			const refusal = needChannel();
+			if (refusal !== void 0) return refusal;
+			const e = raw["e"];
+			if (!isEventName(e)) return bad("e is not a valid event name", n);
+			const k = raw["k"];
+			if (k !== void 0 && !isIdempotencyKey(k)) return bad("k is not a valid key", n);
+			return {
+				ok: true,
+				frame: {
+					t: "pub",
+					c,
+					e,
+					d: JSON.stringify(raw["d"] ?? null),
+					...n === void 0 ? {} : { n },
+					...k === void 0 ? {} : { k }
+				}
+			};
+		}
+		case "req": {
+			const refusal = needChannel();
+			if (refusal !== void 0) return refusal;
+			if (n === void 0) return bad("req needs n");
+			const e = raw["e"];
+			if (!isEventName(e)) return bad("e is not a valid event name", n);
+			const ms = raw["ms"];
+			if (ms !== void 0 && !(typeof ms === "number" && Number.isFinite(ms) && ms > 0)) return bad("ms must be a positive number", n);
+			return {
+				ok: true,
+				frame: {
+					t: "req",
+					n,
+					c,
+					e,
+					d: raw["d"] ?? null,
+					...ms === void 0 ? {} : { ms }
+				}
+			};
+		}
+		case "pres": {
+			const refusal = needChannel();
+			if (refusal !== void 0) return refusal;
+			return {
+				ok: true,
+				frame: {
+					t: "pres",
+					c,
+					s: raw["s"] ?? null
+				}
+			};
+		}
+		default: return bad("unknown frame type", n);
+	}
+}
+/**
+* Decodes one server frame (client side). Returns `undefined` for anything that is not a known, well-formed frame, so a
+* client ignores what a newer server may send and never acts on a malformed frame.
+*
+* @param text The frame text.
+* @returns The frame, or undefined.
+* @example
+* import { decodeServerFrame } from "@shadow-js/realtime";
+*
+* decodeServerFrame('{"t":"pong"}'); // { t: "pong" }
+* decodeServerFrame("not json"); // undefined
+* @since 1.0.0
+*/
+function decodeServerFrame(text) {
+	let value;
+	try {
+		value = JSON.parse(text);
+	} catch {
+		return;
+	}
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return void 0;
+	const raw = value;
+	const str = (key) => {
+		const item = raw[key];
+		return typeof item === "string" ? item : void 0;
+	};
+	const num = (key) => {
+		const item = raw[key];
+		return isCount(item) ? item : void 0;
+	};
+	switch (raw["t"]) {
+		case "ready": {
+			const v = num("v");
+			const id = str("id");
+			if (v === void 0 || id === void 0) return void 0;
+			return {
+				t: "ready",
+				v,
+				id,
+				hb: num("hb") ?? 3e4,
+				max: num("max") ?? 65536
+			};
+		}
+		case "subbed": {
+			const n = num("n");
+			const c = str("c");
+			const head = num("head");
+			if (n === void 0 || c === void 0 || head === void 0) return void 0;
+			return {
+				t: "subbed",
+				n,
+				c,
+				head,
+				...raw["gap"] === true ? { gap: true } : {},
+				...raw["reset"] === true ? { reset: true } : {}
+			};
+		}
+		case "unsubbed": {
+			const c = str("c");
+			if (c === void 0) return void 0;
+			const why = str("why");
+			return why === void 0 ? {
+				t: "unsubbed",
+				c
+			} : {
+				t: "unsubbed",
+				c,
+				why
+			};
+		}
+		case "msg": {
+			const c = str("c");
+			const s = num("s");
+			const e = str("e");
+			if (c === void 0 || s === void 0 || e === void 0 || s < 1) return void 0;
+			const p = str("p");
+			const u = str("u");
+			return {
+				t: "msg",
+				c,
+				s,
+				e,
+				d: raw["d"],
+				...p === void 0 ? {} : { p },
+				...u === void 0 ? {} : { u },
+				...raw["r"] === 1 ? { r: 1 } : {}
+			};
+		}
+		case "ack": {
+			const n = num("n");
+			const s = num("s");
+			if (n === void 0 || s === void 0) return void 0;
+			return {
+				t: "ack",
+				n,
+				s,
+				...raw["dup"] === true ? { dup: true } : {}
+			};
+		}
+		case "rep": {
+			const n = num("n");
+			if (n === void 0) return void 0;
+			return {
+				t: "rep",
+				n,
+				d: raw["d"]
+			};
+		}
+		case "err": {
+			const code = str("code");
+			if (code === void 0) return void 0;
+			const n = num("n");
+			const c = str("c");
+			const msg = str("msg");
+			return {
+				t: "err",
+				code,
+				...n === void 0 ? {} : { n },
+				...c === void 0 ? {} : { c },
+				...msg === void 0 ? {} : { msg }
+			};
+		}
+		case "pres": {
+			const c = str("c");
+			const op = raw["op"];
+			const m = raw["m"];
+			if (c === void 0 || op !== "sync" && op !== "join" && op !== "set" && op !== "leave") return void 0;
+			const member = (item) => {
+				if (item === null || typeof item !== "object") return void 0;
+				const entry = item;
+				if (typeof entry["id"] !== "string" || !isCount(entry["v"])) return void 0;
+				return {
+					id: entry["id"],
+					v: entry["v"],
+					s: entry["s"] ?? null,
+					...typeof entry["u"] === "string" ? { u: entry["u"] } : {}
+				};
+			};
+			if (op === "sync") {
+				if (!Array.isArray(m)) return void 0;
+				const list = m.map(member);
+				if (list.some((item) => item === void 0)) return void 0;
+				return {
+					t: "pres",
+					c,
+					op,
+					m: list
+				};
+			}
+			const one = member(m);
+			return one === void 0 ? void 0 : {
+				t: "pres",
+				c,
+				op,
+				m: one
+			};
+		}
+		case "pong": {
+			const n = num("n");
+			return n === void 0 ? { t: "pong" } : {
+				t: "pong",
+				n
+			};
+		}
+		case "bye": {
+			const code = num("code");
+			return code === void 0 ? void 0 : {
+				t: "bye",
+				code,
+				why: str("why") ?? ""
+			};
+		}
+		default: return;
+	}
+}
+//#endregion
+export { PROTOCOL_VERSION, byteLength, decodeClientFrame, decodeServerFrame, isChannelName, isEventName, isIdempotencyKey };
+
+//# sourceMappingURL=protocol.js.map