@devvit/realtime 0.12.1-next-2025-09-17-15-21-23-c6821c29e.0 → 0.12.1-next-2025-09-22-19-00-17-eb5ffb2a8.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, } 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,GACnB,MAAM,eAAe,CAAC"}

package/client.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devvit/realtime",
-  "version": "0.12.1-next-2025-09-17-15-21-23-c6821c29e.0",
+  "version": "0.12.1-next-2025-09-22-19-00-17-eb5ffb2a8.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-15-21-23-c6821c29e.0",
-    "@devvit/shared": "0.12.1-next-2025-09-17-15-21-23-c6821c29e.0",
-    "@devvit/shared-types": "0.12.1-next-2025-09-17-15-21-23-c6821c29e.0"
+    "@devvit/protos": "0.12.1-next-2025-09-22-19-00-17-eb5ffb2a8.0",
+    "@devvit/shared": "0.12.1-next-2025-09-22-19-00-17-eb5ffb2a8.0",
+    "@devvit/shared-types": "0.12.1-next-2025-09-22-19-00-17-eb5ffb2a8.0"
   },
   "peerDependencies": {
     "@devvit/client": "*",
     "@devvit/server": "*"
   },
   "devDependencies": {
-    "@devvit/client": "0.12.1-next-2025-09-17-15-21-23-c6821c29e.0",
-    "@devvit/repo-tools": "0.12.1-next-2025-09-17-15-21-23-c6821c29e.0",
-    "@devvit/server": "0.12.1-next-2025-09-17-15-21-23-c6821c29e.0",
-    "@devvit/tsconfig": "0.12.1-next-2025-09-17-15-21-23-c6821c29e.0",
+    "@devvit/client": "0.12.1-next-2025-09-22-19-00-17-eb5ffb2a8.0",
+    "@devvit/repo-tools": "0.12.1-next-2025-09-22-19-00-17-eb5ffb2a8.0",
+    "@devvit/server": "0.12.1-next-2025-09-22-19-00-17-eb5ffb2a8.0",
+    "@devvit/tsconfig": "0.12.1-next-2025-09-22-19-00-17-eb5ffb2a8.0",
     "eslint": "9.11.1",
     "typescript": "5.8.3",
     "vitest": "1.6.1"
   },
-  "gitHead": "78409d585f1de45965a7ad87f7f1e3eb7dfab00d"
+  "gitHead": "a62a0afda055b6c8663203e970acddcf15f2027a"
 }

package/realtime.d.ts

@@ -1,36 +1,58 @@
 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>;
 /**
  * Clears all connections. Used for testing purposes.
  * @internal
  */
 export declare const __clearConnections: () => void;
-declare class Connection {
+export declare class Connection {
     #private;
-    constructor(opts: Readonly<ConnectRealtimeOptions>);
+    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>;
     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":"AAAA,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,0DAA0D,CAAC;AAGhH,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,CAQvE;AAED;;;GAGG;AACH,eAAO,MAAM,kBAAkB,QAAO,IAErC,CAAC;AAUF,qBAAa,UAAU;;gBAGT,IAAI,EAAE,QAAQ,CAAC,sBAAsB,CAAC,SAAS,CAAC,CAAC;IAI7D;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAIjC,SAAS,GAAI,IAAI,YAAY,CAAC,+BAA+B,CAAC,KAAG,IAAI,CAgCnE;CACH"}

package/realtime.js

@@ -20,6 +20,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 +53,17 @@ 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);
+    await emitConnectionsEffect();
+}
 /**
  * Clears all connections. Used for testing purposes.
  * @internal
@@ -41,7 +71,14 @@ 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: 0,
+    });
+}
+export class Connection {
     constructor(opts) {
         _Connection_opts.set(this, void 0);
         this.onMessage = (ev) => {
@@ -79,23 +116,10 @@ class Connection {
     /**
      * 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(__classPrivateFieldGet(this, _Connection_opts, "f").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();