@devvit/realtime 0.12.1-next-2025-09-17-19-53-43-a7752f728.0 → 0.12.1-next-2025-09-22-20-12-49-9b3f04aa9.0

package/RealtimeClient.d.ts

@@ -1,7 +1,18 @@
 import type { JsonValue } from '@devvit/shared';
 export declare class RealtimeClient {
     #private;
-    send(channel: string, msg: JsonValue): Promise<void>;
+    /**
+     * @example
+     *
+     * ```ts
+     * import {context, realtime} from '@devvit/web/server';
+     * import type {T2} from '@devvit/web/shared'
+     *
+     * type RealtimeMessage = {x: number, y: number, t2: T2}
+     *
+     * await realtime.send<RealtimeMessage>({x: 1, y: 2, t2: context.userId})
+     * ```
+     */
+    send<Msg extends JsonValue>(channel: string, msg: Msg): Promise<void>;
 }
-export declare const realtime: RealtimeClient;
 //# sourceMappingURL=RealtimeClient.d.ts.map

package/RealtimeClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RealtimeClient.d.ts","sourceRoot":"","sources":["../src/RealtimeClient.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAGhD,qBAAa,cAAc;;IAGnB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;CAQ3D;AAED,eAAO,MAAM,QAAQ,gBAAuB,CAAC"}
+{"version":3,"file":"RealtimeClient.d.ts","sourceRoot":"","sources":["../src/RealtimeClient.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAGhD,qBAAa,cAAc;;IAGzB;;;;;;;;;;;OAWG;IACG,IAAI,CAAC,GAAG,SAAS,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;CAQ5E"}

package/RealtimeClient.js

@@ -18,6 +18,18 @@ export class RealtimeClient {
         _RealtimeClient_instances.add(this);
         _RealtimeClient_pluginCache.set(this, void 0);
     }
+    /**
+     * @example
+     *
+     * ```ts
+     * import {context, realtime} from '@devvit/web/server';
+     * import type {T2} from '@devvit/web/shared'
+     *
+     * type RealtimeMessage = {x: number, y: number, t2: T2}
+     *
+     * await realtime.send<RealtimeMessage>({x: 1, y: 2, t2: context.userId})
+     * ```
+     */
     async send(channel, msg) {
         // guarantee an object by wrapping msg. the key must align to useChannel().
         await __classPrivateFieldGet(this, _RealtimeClient_instances, "a", _RealtimeClient_plugin_get).Send({ channel, data: { msg } }, context.metadata);
@@ -26,4 +38,3 @@ export class RealtimeClient {
 _RealtimeClient_pluginCache = new WeakMap(), _RealtimeClient_instances = new WeakSet(), _RealtimeClient_plugin_get = function _RealtimeClient_plugin_get() {
     return (__classPrivateFieldSet(this, _RealtimeClient_pluginCache, __classPrivateFieldGet(this, _RealtimeClient_pluginCache, "f") ?? getDevvitConfig().use(RealtimeDefinition), "f"));
 };
-export const realtime = new RealtimeClient();

package/client.d.ts

@@ -1,2 +1,2 @@
-export { connectRealtime } from './realtime.js';
+export { type Connection, connectRealtime, type ConnectRealtimeOptions, disconnectRealtime, isRealtimeConnected, } from './realtime.js';
 //# sourceMappingURL=client.d.ts.map

package/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,UAAU,EACf,eAAe,EACf,KAAK,sBAAsB,EAC3B,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,eAAe,CAAC"}

package/client.js

@@ -1 +1 @@
-export { connectRealtime } from './realtime.js';
+export { connectRealtime, disconnectRealtime, isRealtimeConnected, } from './realtime.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devvit/realtime",
-  "version": "0.12.1-next-2025-09-17-19-53-43-a7752f728.0",
+  "version": "0.12.1-next-2025-09-22-20-12-49-9b3f04aa9.0",
   "license": "BSD-3-Clause",
   "repository": {
     "type": "git",
@@ -35,22 +35,22 @@
     "test:unit-with-coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@devvit/protos": "0.12.1-next-2025-09-17-19-53-43-a7752f728.0",
-    "@devvit/shared": "0.12.1-next-2025-09-17-19-53-43-a7752f728.0",
-    "@devvit/shared-types": "0.12.1-next-2025-09-17-19-53-43-a7752f728.0"
+    "@devvit/protos": "0.12.1-next-2025-09-22-20-12-49-9b3f04aa9.0",
+    "@devvit/shared": "0.12.1-next-2025-09-22-20-12-49-9b3f04aa9.0",
+    "@devvit/shared-types": "0.12.1-next-2025-09-22-20-12-49-9b3f04aa9.0"
   },
   "peerDependencies": {
     "@devvit/client": "*",
     "@devvit/server": "*"
   },
   "devDependencies": {
-    "@devvit/client": "0.12.1-next-2025-09-17-19-53-43-a7752f728.0",
-    "@devvit/repo-tools": "0.12.1-next-2025-09-17-19-53-43-a7752f728.0",
-    "@devvit/server": "0.12.1-next-2025-09-17-19-53-43-a7752f728.0",
-    "@devvit/tsconfig": "0.12.1-next-2025-09-17-19-53-43-a7752f728.0",
+    "@devvit/client": "0.12.1-next-2025-09-22-20-12-49-9b3f04aa9.0",
+    "@devvit/repo-tools": "0.12.1-next-2025-09-22-20-12-49-9b3f04aa9.0",
+    "@devvit/server": "0.12.1-next-2025-09-22-20-12-49-9b3f04aa9.0",
+    "@devvit/tsconfig": "0.12.1-next-2025-09-22-20-12-49-9b3f04aa9.0",
     "eslint": "9.11.1",
     "typescript": "5.8.3",
     "vitest": "1.6.1"
   },
-  "gitHead": "94bf4342af792bc0ea4433cac03c90ac14c2998f"
+  "gitHead": "5a216cfbb873d9d818cb009701fb203f6c026258"
 }

package/realtime.d.ts

@@ -1,36 +1,64 @@
 import type { WebViewMessageEvent_MessageData } from '@devvit/protos/json/devvit/ui/events/v1alpha/web_view.js';
 import type { JsonValue } from '@devvit/shared';
-type ConnectRealtimeOptions = {
+export type ConnectRealtimeOptions<Msg extends JsonValue> = {
     channel: string;
     onConnect?: (channel: string) => void;
     onDisconnect?: (channel: string) => void;
-    onMessage: (data: JsonValue) => void;
+    onMessage: (data: Msg) => void;
 };
 /**
  * Connects to a realtime channel for receiving messages.
  *
  * @param opts - Connection options including channel name and callbacks
  * @returns A Connection object with a disconnect method
+ *
+ * @example
+ *
+ * ```ts
+ * import {connectRealtime, context} from '@devvit/web/client'
+ * import type {T2} from '@devvit/web/shared'
+ *
+ * type RealtimeMessage = {x: number, y: number, t2: T2}
+ *
+ * connectRealtime<RealtimeMessage>({
+ *   channel: context.postId,
+ *   onConnect() {
+ *     console.log(`${context.userId} connected`)
+ *   },
+ *   onDisconnect() {
+ *     console.log(`${context.userId} disconnected`)
+ *   },
+ *   onMessage(msg) {
+ *     // Filter out current user across all sessions.
+ *     if (msg.t2 === context.userId) return
+ *
+ *     console.log(`user ${msg.t2} at (${msg.x}, ${msg.y})`)
+ *   }
+ * })
+ * ```
  */
-export declare const connectRealtime: (opts: Readonly<ConnectRealtimeOptions>) => Promise<Connection>;
+export declare const connectRealtime: <Msg extends JsonValue>(opts: Readonly<ConnectRealtimeOptions<Msg>>) => Promise<Connection>;
+export declare function disconnectRealtime(channel: string): Promise<void>;
+/** True if the channel socket is connected. */
+export declare function isRealtimeConnected(channel: string): boolean;
 /**
  * Clears all connections. Used for testing purposes.
  * @internal
  */
 export declare const __clearConnections: () => void;
-declare class Connection {
-    #private;
-    constructor(opts: Readonly<ConnectRealtimeOptions>);
+export declare class Connection {
+    /** @internal */
+    connected: boolean;
+    /** @internal */
+    readonly opts: Readonly<ConnectRealtimeOptions<JsonValue>>;
+    constructor(opts: Readonly<ConnectRealtimeOptions<JsonValue>>);
     /**
      * Disconnects from the realtime channel.
      *
-     * This works by sending a list of all channels we want to remain subscribed to,
-     * excluding the channel we want to disconnect from. The effect handler compares this
-     * new list with existing subscriptions and triggers disconnect for any channel
-     * that's no longer in the list.
+     * @deprecated Use `disconnectRealtime()`.
      */
     disconnect(): Promise<void>;
+    /** @internal */
     onMessage: (ev: MessageEvent<WebViewMessageEvent_MessageData>) => void;
 }
-export {};
 //# sourceMappingURL=realtime.d.ts.map

package/realtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"realtime.d.ts","sourceRoot":"","sources":["../src/realtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,0DAA0D,CAAC;AAGhH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAGhD,KAAK,sBAAsB,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,SAAS,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;CACtC,CAAC;AAQF;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAC1B,MAAM,QAAQ,CAAC,sBAAsB,CAAC,KACrC,OAAO,CAAC,UAAU,CAepB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,kBAAkB,QAAO,IAErC,CAAC;AAEF,cAAM,UAAU;;gBAGF,IAAI,EAAE,QAAQ,CAAC,sBAAsB,CAAC;IAIlD;;;;;;;OAOG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBjC,SAAS,GAAI,IAAI,YAAY,CAAC,+BAA+B,CAAC,KAAG,IAAI,CAgCnE;CACH"}
+{"version":3,"file":"realtime.d.ts","sourceRoot":"","sources":["../src/realtime.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,0DAA0D,CAAC;AAChH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAGhD,MAAM,MAAM,sBAAsB,CAAC,GAAG,SAAS,SAAS,IAAI;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,SAAS,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,IAAI,CAAC;CAChC,CAAC;AAQF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,eAAe,GAAU,GAAG,SAAS,SAAS,EACzD,MAAM,QAAQ,CAAC,sBAAsB,CAAC,GAAG,CAAC,CAAC,KAC1C,OAAO,CAAC,UAAU,CAYpB,CAAC;AAEF,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAUvE;AAED,+CAA+C;AAC/C,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAE5D;AAED;;;GAGG;AACH,eAAO,MAAM,kBAAkB,QAAO,IAErC,CAAC;AAUF,qBAAa,UAAU;IACrB,gBAAgB;IAChB,SAAS,EAAE,OAAO,CAAS;IAE3B,gBAAgB;IAChB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,sBAAsB,CAAC,SAAS,CAAC,CAAC,CAAC;gBAE/C,IAAI,EAAE,QAAQ,CAAC,sBAAsB,CAAC,SAAS,CAAC,CAAC;IAI7D;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAIjC,gBAAgB;IAChB,SAAS,GAAI,IAAI,YAAY,CAAC,+BAA+B,CAAC,KAAG,IAAI,CAkCnE;CACH"}

package/realtime.js

@@ -1,15 +1,5 @@
-var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
-    if (kind === "m") throw new TypeError("Private method is not writable");
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
-    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
-};
-var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
-    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
-};
-var _Connection_opts;
+import { EffectType } from '@devvit/protos/json/devvit/ui/effects/v1alpha/effect.js';
+import { RealtimeSubscriptionStatus } from '@devvit/protos/json/devvit/ui/effects/v1alpha/realtime_subscriptions.js';
 import { emitEffect } from '@devvit/shared-types/client/emit-effect.js';
 const connectionsByChannel = new Map();
 /* TODO: Clean up this API. Now that realtime has been removed from the
@@ -20,6 +10,31 @@ const connectionsByChannel = new Map();
  *
  * @param opts - Connection options including channel name and callbacks
  * @returns A Connection object with a disconnect method
+ *
+ * @example
+ *
+ * ```ts
+ * import {connectRealtime, context} from '@devvit/web/client'
+ * import type {T2} from '@devvit/web/shared'
+ *
+ * type RealtimeMessage = {x: number, y: number, t2: T2}
+ *
+ * connectRealtime<RealtimeMessage>({
+ *   channel: context.postId,
+ *   onConnect() {
+ *     console.log(`${context.userId} connected`)
+ *   },
+ *   onDisconnect() {
+ *     console.log(`${context.userId} disconnected`)
+ *   },
+ *   onMessage(msg) {
+ *     // Filter out current user across all sessions.
+ *     if (msg.t2 === context.userId) return
+ *
+ *     console.log(`user ${msg.t2} at (${msg.x}, ${msg.y})`)
+ *   }
+ * })
+ * ```
  */
 export const connectRealtime = async (opts) => {
     if (connectionsByChannel.has(opts.channel)) {
@@ -28,12 +43,24 @@ export const connectRealtime = async (opts) => {
     const connection = new Connection(opts);
     connectionsByChannel.set(opts.channel, connection);
     addEventListener('message', connection.onMessage);
-    await emitEffect({
-        realtimeSubscriptions: { subscriptionIds: [...connectionsByChannel.keys()] },
-        type: 0,
-    });
+    await emitConnectionsEffect();
     return connection;
 };
+export async function disconnectRealtime(channel) {
+    const connection = connectionsByChannel.get(channel);
+    if (!connection)
+        return;
+    connectionsByChannel.delete(channel);
+    removeEventListener('message', connection.onMessage);
+    if (connection.connected)
+        connection.opts.onDisconnect?.(channel);
+    connection.connected = false;
+    await emitConnectionsEffect();
+}
+/** True if the channel socket is connected. */
+export function isRealtimeConnected(channel) {
+    return !!connectionsByChannel.get(channel)?.connected;
+}
 /**
  * Clears all connections. Used for testing purposes.
  * @internal
@@ -41,9 +68,18 @@ export const connectRealtime = async (opts) => {
 export const __clearConnections = () => {
     connectionsByChannel.clear();
 };
-class Connection {
+/** Emits open connections which may cause subscribe / unsubscribe. */
+async function emitConnectionsEffect() {
+    await emitEffect({
+        realtimeSubscriptions: { subscriptionIds: [...connectionsByChannel.keys()] },
+        type: EffectType.EFFECT_REALTIME_SUB,
+    });
+}
+export class Connection {
     constructor(opts) {
-        _Connection_opts.set(this, void 0);
+        /** @internal */
+        this.connected = false;
+        /** @internal */
         this.onMessage = (ev) => {
             const { type, data } = ev.data;
             if (type !== 'devvit-message') {
@@ -53,49 +89,37 @@ class Connection {
                 return;
             }
             const { status, event } = data.realtimeEvent;
-            if (!event?.channel.endsWith(__classPrivateFieldGet(this, _Connection_opts, "f").channel)) {
+            if (!event?.channel.endsWith(this.opts.channel)) {
                 return;
             }
             // Normalize the channel name (remove namespacing)
-            event.channel = __classPrivateFieldGet(this, _Connection_opts, "f").channel;
-            if (status === 0) {
-                __classPrivateFieldGet(this, _Connection_opts, "f").onConnect?.(__classPrivateFieldGet(this, _Connection_opts, "f").channel);
+            event.channel = this.opts.channel;
+            if (status === RealtimeSubscriptionStatus.REALTIME_SUBSCRIBED) {
+                this.connected = true;
+                this.opts.onConnect?.(this.opts.channel);
             }
-            else if (status === 1) {
-                __classPrivateFieldGet(this, _Connection_opts, "f").onDisconnect?.(__classPrivateFieldGet(this, _Connection_opts, "f").channel);
+            else if (status === RealtimeSubscriptionStatus.REALTIME_UNSUBSCRIBED) {
+                this.connected = false;
+                this.opts.onDisconnect?.(this.opts.channel);
             }
             else if (event.data) {
-                __classPrivateFieldGet(this, _Connection_opts, "f").onMessage(event.data.msg);
+                this.opts.onMessage(event.data.msg);
             }
             else {
                 console.error('[realtime] Received event without data:', {
-                    channel: __classPrivateFieldGet(this, _Connection_opts, "f").channel,
+                    channel: this.opts.channel,
                     event,
                 });
             }
         };
-        __classPrivateFieldSet(this, _Connection_opts, opts, "f");
+        this.opts = opts;
     }
     /**
      * Disconnects from the realtime channel.
      *
-     * This works by sending a list of all channels we want to remain subscribed to,
-     * excluding the channel we want to disconnect from. The effect handler compares this
-     * new list with existing subscriptions and triggers disconnect for any channel
-     * that's no longer in the list.
+     * @deprecated Use `disconnectRealtime()`.
      */
     async disconnect() {
-        const connection = connectionsByChannel.get(__classPrivateFieldGet(this, _Connection_opts, "f").channel);
-        if (!connection) {
-            return;
-        }
-        // Get all current subscriptions except the one we're disconnecting
-        const remainingChannels = [...connectionsByChannel.keys()].filter((ch) => ch !== __classPrivateFieldGet(this, _Connection_opts, "f").channel);
-        await emitEffect({
-            realtimeSubscriptions: { subscriptionIds: remainingChannels },
-            type: 0,
-        });
-        connectionsByChannel.delete(__classPrivateFieldGet(this, _Connection_opts, "f").channel);
+        await disconnectRealtime(this.opts.channel);
     }
 }
-_Connection_opts = new WeakMap();

package/server.d.ts

@@ -1,2 +1,4 @@
-export { realtime, type RealtimeClient } from './RealtimeClient.js';
+import { RealtimeClient } from './RealtimeClient.js';
+export type { RealtimeClient } from './RealtimeClient.js';
+export declare const realtime: RealtimeClient;
 //# sourceMappingURL=server.d.ts.map

package/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,eAAO,MAAM,QAAQ,EAAE,cAAqC,CAAC"}

package/server.js

@@ -1 +1,2 @@
-export { realtime } from './RealtimeClient.js';
+import { RealtimeClient } from './RealtimeClient.js';
+export const realtime = new RealtimeClient();