@orpc/publisher 2.0.0-beta.4 → 2.0.0-beta.41

package/dist/adapters/upstash.d.mts

@@ -1,71 +1,30 @@
+import { ThrowableError } from '@orpc/shared';
 import { Redis } from '@upstash/redis';
-import { Publisher, PublisherOptions, PublisherSubscribeListenerOptions } from '../index.mjs';
-import { RPCSerializer } from '@orpc/client';
-import '@orpc/shared';
+import { BaseRedisPublisher, BaseRedisPublisherOptions, RedisStreamEntry } from './base-redis.mjs';
+import '../index.mjs';
+import '@orpc/client';
 
-interface UpstashPublisherOptions extends PublisherOptions {
-    /**
-     * The prefix to use for Redis keys.
-     */
-    prefix?: string;
-    /**
-     * Serializer for serialize and deserialize payloads.
-     *
-     * @default RPCSerializer
-     */
-    serializer?: undefined | Pick<RPCSerializer, keyof RPCSerializer>;
-    /**
-     * Configuration for event replay support.
-     *
-     * When enabled, published events are temporarily stored so new
-     * subscribers can resume from a previous position using `lastEventId`.
-     *
-     * @default { enabled: false }
-     */
-    replay?: {
-        /**
-         * Whether event replay support is enabled.
-         *
-         * When enabled, published events are temporarily stored so new
-         * subscribers can resume from a previous position using `lastEventId`.
-         *
-         * @default false
-         */
-        enabled: boolean;
-        /**
-         * How long (in seconds) to retain events for replay.
-         *
-         * Expired events are cleaned up lazily for performance reasons, so
-         * some events may remain available slightly longer than this period.
-         *
-         * @default 300 (5 min)
-         */
-        seconds?: number;
-    };
+interface UpstashPublisherOptions extends BaseRedisPublisherOptions {
 }
-declare class UpstashPublisher<T extends Record<string, object>> extends Publisher<T> {
+/**
+ * Publisher adapter for Upstash Redis. Distributes events across processes via
+ * Upstash Pub/Sub, with optional resume support backed by Redis Streams.
+ *
+ * @see {@link https://orpc.dev/docs/helpers/publisher#adapters | Publisher Helpers - Adapters}
+ */
+declare class UpstashPublisher<T extends Record<string, object>> extends BaseRedisPublisher<T> {
     private readonly redis;
-    private readonly prefix;
-    private readonly serializer;
     private readonly listenersMap;
     private readonly onErrorsMap;
     private readonly subscriptionMap;
-    private readonly replayEnabled;
-    private readonly replaySeconds;
-    /**
-     * The exactness of the `XTRIM` command.
-     * Used for testing purpose.
-     */
-    private readonly xTrimExactness;
-    constructor(redis: Redis, { replay, prefix, serializer, ...options }?: UpstashPublisherOptions);
-    private readonly firstPublishTimeMap;
-    publish<K extends keyof T & string>(event: K, payload: T[K]): Promise<void>;
-    protected subscribeListener<K extends keyof T & string>(event: K, originalListener: (payload: T[K]) => void, { lastEventId, onError }?: PublisherSubscribeListenerOptions): Promise<() => Promise<void>>;
     private readonly pendingSubscriptionsMap;
-    private subscribeEvent;
-    private unsubscribeEvent;
-    private serializePayload;
-    private deserializePayload;
+    constructor(redis: Redis, options?: UpstashPublisherOptions);
+    protected publishMessage(channel: string, message: string): Promise<void>;
+    protected subscribeChannel(channel: string, listener: (message: unknown) => void, onError?: (error: ThrowableError) => void): Promise<() => Promise<void>>;
+    protected evalScript(script: string, keys: string[], args: string[]): Promise<unknown>;
+    protected readStreamEntries(key: string, lastId: string): Promise<RedisStreamEntry[]>;
+    private subscribeIfNeeded;
+    private unsubscribeIfUnused;
 }
 
 export { UpstashPublisher };

package/dist/adapters/upstash.d.ts

@@ -1,71 +1,30 @@
+import { ThrowableError } from '@orpc/shared';
 import { Redis } from '@upstash/redis';
-import { Publisher, PublisherOptions, PublisherSubscribeListenerOptions } from '../index.js';
-import { RPCSerializer } from '@orpc/client';
-import '@orpc/shared';
+import { BaseRedisPublisher, BaseRedisPublisherOptions, RedisStreamEntry } from './base-redis.js';
+import '../index.js';
+import '@orpc/client';
 
-interface UpstashPublisherOptions extends PublisherOptions {
-    /**
-     * The prefix to use for Redis keys.
-     */
-    prefix?: string;
-    /**
-     * Serializer for serialize and deserialize payloads.
-     *
-     * @default RPCSerializer
-     */
-    serializer?: undefined | Pick<RPCSerializer, keyof RPCSerializer>;
-    /**
-     * Configuration for event replay support.
-     *
-     * When enabled, published events are temporarily stored so new
-     * subscribers can resume from a previous position using `lastEventId`.
-     *
-     * @default { enabled: false }
-     */
-    replay?: {
-        /**
-         * Whether event replay support is enabled.
-         *
-         * When enabled, published events are temporarily stored so new
-         * subscribers can resume from a previous position using `lastEventId`.
-         *
-         * @default false
-         */
-        enabled: boolean;
-        /**
-         * How long (in seconds) to retain events for replay.
-         *
-         * Expired events are cleaned up lazily for performance reasons, so
-         * some events may remain available slightly longer than this period.
-         *
-         * @default 300 (5 min)
-         */
-        seconds?: number;
-    };
+interface UpstashPublisherOptions extends BaseRedisPublisherOptions {
 }
-declare class UpstashPublisher<T extends Record<string, object>> extends Publisher<T> {
+/**
+ * Publisher adapter for Upstash Redis. Distributes events across processes via
+ * Upstash Pub/Sub, with optional resume support backed by Redis Streams.
+ *
+ * @see {@link https://orpc.dev/docs/helpers/publisher#adapters | Publisher Helpers - Adapters}
+ */
+declare class UpstashPublisher<T extends Record<string, object>> extends BaseRedisPublisher<T> {
     private readonly redis;
-    private readonly prefix;
-    private readonly serializer;
     private readonly listenersMap;
     private readonly onErrorsMap;
     private readonly subscriptionMap;
-    private readonly replayEnabled;
-    private readonly replaySeconds;
-    /**
-     * The exactness of the `XTRIM` command.
-     * Used for testing purpose.
-     */
-    private readonly xTrimExactness;
-    constructor(redis: Redis, { replay, prefix, serializer, ...options }?: UpstashPublisherOptions);
-    private readonly firstPublishTimeMap;
-    publish<K extends keyof T & string>(event: K, payload: T[K]): Promise<void>;
-    protected subscribeListener<K extends keyof T & string>(event: K, originalListener: (payload: T[K]) => void, { lastEventId, onError }?: PublisherSubscribeListenerOptions): Promise<() => Promise<void>>;
     private readonly pendingSubscriptionsMap;
-    private subscribeEvent;
-    private unsubscribeEvent;
-    private serializePayload;
-    private deserializePayload;
+    constructor(redis: Redis, options?: UpstashPublisherOptions);
+    protected publishMessage(channel: string, message: string): Promise<void>;
+    protected subscribeChannel(channel: string, listener: (message: unknown) => void, onError?: (error: ThrowableError) => void): Promise<() => Promise<void>>;
+    protected evalScript(script: string, keys: string[], args: string[]): Promise<unknown>;
+    protected readStreamEntries(key: string, lastId: string): Promise<RedisStreamEntry[]>;
+    private subscribeIfNeeded;
+    private unsubscribeIfUnused;
 }
 
 export { UpstashPublisher };

package/dist/adapters/upstash.mjs

@@ -1,199 +1,100 @@
-import { RPCSerializer } from '@orpc/client';
-import { once } from '@orpc/shared';
-import { unwrapEvent, withEventMeta, getEventMeta } from '@standardserver/core';
-import { P as Publisher } from '../shared/publisher.BSQf8ybR.mjs';
+import { promiseWithResolvers } from '@orpc/shared';
+import { BaseRedisPublisher } from './base-redis.mjs';
+import '@orpc/client';
+import '@standard-server/core';
+import '../shared/publisher.DcPG7zl6.mjs';
 
-class UpstashPublisher extends Publisher {
-  constructor(redis, { replay, prefix, serializer, ...options } = {}) {
+class UpstashPublisher extends BaseRedisPublisher {
+  constructor(redis, options = {}) {
     super(options);
     this.redis = redis;
-    this.prefix = prefix ?? "";
-    this.replayEnabled = replay?.enabled ?? false;
-    this.replaySeconds = replay?.seconds ?? 300;
-    this.serializer = serializer ?? new RPCSerializer();
   }
-  prefix;
-  serializer;
   listenersMap = /* @__PURE__ */ new Map();
   onErrorsMap = /* @__PURE__ */ new Map();
   subscriptionMap = /* @__PURE__ */ new Map();
-  // Upstash subscription objects
-  replayEnabled;
-  replaySeconds;
-  /**
-   * The exactness of the `XTRIM` command.
-   * Used for testing purpose.
-   */
-  xTrimExactness = "~";
-  firstPublishTimeMap = /* @__PURE__ */ new Map();
-  async publish(event, payload) {
-    const redisKey = `${this.prefix}${event}`;
-    const data = this.serializePayload(payload);
-    let id;
-    if (this.replayEnabled) {
-      const now = Date.now();
-      for (const [event2, firstPublishTime] of this.firstPublishTimeMap) {
-        if (firstPublishTime + this.replaySeconds * 1e3 < now) {
-          this.firstPublishTimeMap.delete(event2);
-        }
-      }
-      if (!this.firstPublishTimeMap.has(event)) {
-        this.firstPublishTimeMap.set(event, now);
-        const results = await this.redis.multi().xadd(redisKey, "*", { data }).xtrim(redisKey, { strategy: "MINID", exactness: this.xTrimExactness, threshold: `${now - this.replaySeconds * 1e3}-0` }).expire(redisKey, this.replaySeconds * 2).exec();
-        id = results[0];
-      } else {
-        id = await this.redis.xadd(redisKey, "*", { data });
-      }
-    }
-    await this.redis.publish(redisKey, { id, data });
+  pendingSubscriptionsMap = /* @__PURE__ */ new Map();
+  async publishMessage(channel, message) {
+    await this.redis.publish(channel, message);
   }
-  async subscribeListener(event, originalListener, { lastEventId, onError } = {}) {
-    const redisKey = `${this.prefix}${event}`;
-    let pendingPayloads = [];
-    const replayedIds = /* @__PURE__ */ new Set();
-    const deduplicatingListener = (payload) => {
-      if (pendingPayloads) {
-        pendingPayloads.push(payload);
-        return;
-      }
-      const id = getEventMeta(payload)?.id;
-      if (id !== void 0 && replayedIds.has(id)) {
-        return;
-      }
-      originalListener(payload);
-    };
-    let listeners = this.listenersMap.get(event);
-    if (!listeners) {
-      this.listenersMap.set(event, listeners = []);
-    }
-    listeners.push(deduplicatingListener);
+  async subscribeChannel(channel, listener, onError) {
+    push(this.listenersMap, channel, listener);
     try {
-      const subscribeEventPromise = this.subscribeEvent(event);
-      try {
-        if (this.replayEnabled && lastEventId !== void 0) {
-          const results = await this.redis.xread(redisKey, lastEventId);
-          if (results && results[0]) {
-            const [_, items] = results[0];
-            for (const [id, fields] of items) {
-              const data = fields[1];
-              const payload = this.deserializePayload(id, data);
-              replayedIds.add(id);
-              originalListener(payload);
-            }
-          }
-        }
-      } finally {
-        const pending = pendingPayloads;
-        pendingPayloads = void 0;
-        for (const payload of pending) {
-          deduplicatingListener(payload);
-        }
-      }
-      await subscribeEventPromise;
+      await this.subscribeIfNeeded(channel);
     } catch (error) {
-      listeners.splice(listeners.indexOf(deduplicatingListener), 1);
-      if (listeners.length === 0) {
-        this.listenersMap.delete(event);
-      }
-      await this.unsubscribeEvent(event);
+      remove(this.listenersMap, channel, listener);
+      await this.unsubscribeIfUnused(channel);
       throw error;
     }
     if (onError) {
-      let onErrors = this.onErrorsMap.get(event);
-      if (!onErrors) {
-        this.onErrorsMap.set(event, onErrors = []);
-      }
-      onErrors.push(onError);
+      push(this.onErrorsMap, channel, onError);
     }
-    return once(async () => {
-      listeners.splice(listeners.indexOf(deduplicatingListener), 1);
+    return async () => {
+      remove(this.listenersMap, channel, listener);
       if (onError) {
-        const onErrors = this.onErrorsMap.get(event);
-        if (onErrors) {
-          onErrors.splice(onErrors.indexOf(onError), 1);
-        }
-      }
-      if (listeners.length === 0) {
-        this.listenersMap.delete(event);
-        this.onErrorsMap.delete(event);
+        remove(this.onErrorsMap, channel, onError);
       }
-      await this.unsubscribeEvent(event);
-    });
+      await this.unsubscribeIfUnused(channel);
+    };
   }
-  pendingSubscriptionsMap = /* @__PURE__ */ new Map();
-  async subscribeEvent(event) {
-    const redisKey = `${this.prefix}${event}`;
-    const pending = this.pendingSubscriptionsMap.get(event);
-    if (pending) {
-      try {
-        await pending;
-      } catch {
-      }
+  async evalScript(script, keys, args) {
+    return await this.redis.eval(script, keys, args);
+  }
+  async readStreamEntries(key, lastId) {
+    const results = await this.redis.xread(key, lastId);
+    return results?.[0]?.[1].map(([id, fields]) => ({ id, data: fields[1] })) ?? [];
+  }
+  async subscribeIfNeeded(channel) {
+    while (this.pendingSubscriptionsMap.has(channel)) {
+      await this.pendingSubscriptionsMap.get(channel).catch(() => {
+      });
     }
-    if (this.subscriptionMap.has(event)) {
+    if (this.subscriptionMap.has(channel)) {
       return;
     }
-    const dispatchErrorForEvent = (error) => {
-      const onErrors = this.onErrorsMap.get(event);
-      onErrors?.forEach((onError) => onError(error));
-    };
-    const subscription = this.redis.subscribe(redisKey);
-    subscription.on("message", (message) => {
-      try {
-        const listeners = this.listenersMap.get(event);
-        if (listeners) {
-          const { id, data } = message.message;
-          const payload = this.deserializePayload(id, data);
-          listeners.forEach((listener) => listener(payload));
-        }
-      } catch (error) {
-        dispatchErrorForEvent(error);
-      }
-    });
-    let resolvePromise;
-    let rejectPromise;
-    const promise = new Promise((resolve, reject) => {
-      resolvePromise = resolve;
-      rejectPromise = reject;
-    });
+    const { promise, resolve, reject } = promiseWithResolvers();
+    const subscription = this.redis.subscribe(channel);
+    subscription.on("subscribe", () => resolve());
     subscription.on("error", (error) => {
-      rejectPromise(error);
-      dispatchErrorForEvent(error);
+      reject(error);
+      this.onErrorsMap.get(channel)?.slice().forEach((onError) => onError(error));
     });
-    subscription.on("subscribe", () => {
-      resolvePromise();
+    subscription.on("message", ({ message }) => {
+      this.listenersMap.get(channel)?.slice().forEach((listener) => listener(message));
     });
+    this.pendingSubscriptionsMap.set(channel, promise);
     try {
-      this.pendingSubscriptionsMap.set(event, promise);
       await promise;
-      this.subscriptionMap.set(event, subscription);
+      this.subscriptionMap.set(channel, subscription);
+    } catch (error) {
+      await subscription.unsubscribe();
+      throw error;
     } finally {
-      this.pendingSubscriptionsMap.delete(event);
+      this.pendingSubscriptionsMap.delete(channel);
     }
   }
-  async unsubscribeEvent(event) {
-    const pending = this.pendingSubscriptionsMap.get(event);
-    if (pending) {
-      try {
-        await pending;
-      } catch {
-      }
-    }
-    const subscription = this.subscriptionMap.get(event);
-    if (!this.listenersMap.has(event) && subscription) {
-      this.subscriptionMap.delete(event);
+  async unsubscribeIfUnused(channel) {
+    const subscription = this.subscriptionMap.get(channel);
+    if (subscription && !this.listenersMap.has(channel)) {
+      this.subscriptionMap.delete(channel);
       await subscription.unsubscribe();
     }
   }
-  serializePayload(payload) {
-    const [original, meta] = unwrapEvent(payload);
-    return { payload: this.serializer.serialize(original, { useFormDataForBlobFields: false }), meta };
+}
+function push(map, key, value) {
+  let values = map.get(key);
+  if (!values) {
+    map.set(key, values = []);
+  }
+  values.push(value);
+}
+function remove(map, key, value) {
+  const values = map.get(key);
+  const index = values?.indexOf(value) ?? -1;
+  if (index !== -1) {
+    values.splice(index, 1);
   }
-  deserializePayload(id, { payload, meta }) {
-    return withEventMeta(
-      this.serializer.deserialize(payload),
-      id === void 0 ? { ...meta } : { ...meta, id }
-    );
+  if (values?.length === 0) {
+    map.delete(key);
   }
 }
 

package/dist/index.d.mts

@@ -2,10 +2,12 @@ import { ThrowableError, AsyncIteratorClass } from '@orpc/shared';
 
 interface PublisherOptions {
     /**
-     * Maximum number of events to buffer for async iterator subscribers.
+     * Maximum number of events to buffer for AsyncIteratorObject subscribers.
      *
      * If the buffer exceeds this limit, the oldest event is dropped.
      * This prevents unbounded memory growth if consumers process events slowly.
+     * Missed events the adapter replays for `lastEventId` while subscribing are all kept,
+     * and the limit then applies to how much further behind the consumer falls.
      *
      * Set to:
      * - `0`: Disable buffering. Events must be consumed before the next one arrives.
@@ -42,6 +44,8 @@ declare abstract class Publisher<T extends Record<string, object>> {
     /**
      * Subscribes to a specific event using a callback function.
      * Returns an unsubscribe function to remove the listener.
+     * Events missed since `lastEventId` should reach the listener before the returned promise
+     * resolves, so iterator subscribers keep them all regardless of `maxBufferedEvents`.
      *
      * @remarks
      * This method should be protected to avoid conflicts with `subscribe` method
@@ -68,7 +72,7 @@ declare abstract class Publisher<T extends Record<string, object>> {
      */
     subscribe<K extends keyof T & string>(event: K, listener: (payload: T[K]) => void, options?: PublisherSubscribeListenerOptions): Promise<() => Promise<void>>;
     /**
-     * Subscribes to a specific event using an async iterator.
+     * Subscribes to a specific event using an AsyncIteratorObject.
      * Useful for `for await...of` loops with optional buffering and abort support.
      *
      * @example

package/dist/index.d.ts

@@ -2,10 +2,12 @@ import { ThrowableError, AsyncIteratorClass } from '@orpc/shared';
 
 interface PublisherOptions {
     /**
-     * Maximum number of events to buffer for async iterator subscribers.
+     * Maximum number of events to buffer for AsyncIteratorObject subscribers.
      *
      * If the buffer exceeds this limit, the oldest event is dropped.
      * This prevents unbounded memory growth if consumers process events slowly.
+     * Missed events the adapter replays for `lastEventId` while subscribing are all kept,
+     * and the limit then applies to how much further behind the consumer falls.
      *
      * Set to:
      * - `0`: Disable buffering. Events must be consumed before the next one arrives.
@@ -42,6 +44,8 @@ declare abstract class Publisher<T extends Record<string, object>> {
     /**
      * Subscribes to a specific event using a callback function.
      * Returns an unsubscribe function to remove the listener.
+     * Events missed since `lastEventId` should reach the listener before the returned promise
+     * resolves, so iterator subscribers keep them all regardless of `maxBufferedEvents`.
      *
      * @remarks
      * This method should be protected to avoid conflicts with `subscribe` method
@@ -68,7 +72,7 @@ declare abstract class Publisher<T extends Record<string, object>> {
      */
     subscribe<K extends keyof T & string>(event: K, listener: (payload: T[K]) => void, options?: PublisherSubscribeListenerOptions): Promise<() => Promise<void>>;
     /**
-     * Subscribes to a specific event using an async iterator.
+     * Subscribes to a specific event using an AsyncIteratorObject.
      * Useful for `for await...of` loops with optional buffering and abort support.
      *
      * @example

package/dist/index.mjs

@@ -1,2 +1,2 @@
-export { P as Publisher } from './shared/publisher.BSQf8ybR.mjs';
+export { P as Publisher } from './shared/publisher.DcPG7zl6.mjs';
 import '@orpc/shared';

package/dist/shared/{publisher.BSQf8ybR.mjs → publisher.DcPG7zl6.mjs}

@@ -1,4 +1,4 @@
-import { AsyncIteratorClass } from '@orpc/shared';
+import { throwIfAborted, AsyncIteratorClass } from '@orpc/shared';
 
 class Publisher {
   maxBufferedEvents;
@@ -11,10 +11,13 @@ class Publisher {
     }
     const signal = listenerOrOptions?.signal;
     const maxBufferedEvents = listenerOrOptions?.maxBufferedEvents ?? this.maxBufferedEvents;
-    signal?.throwIfAborted();
-    const bufferedEvents = [];
+    throwIfAborted(signal);
+    const resuming = listenerOrOptions?.lastEventId !== void 0;
+    const bufferedEvents = new Queue();
     const pullResolvers = [];
-    const unsubscribePromise = this.subscribeListener(event, (payload) => {
+    let bufferFloor = 0;
+    let bufferLimit = resuming ? Infinity : maxBufferedEvents;
+    const subscription = this.subscribeListener(event, (payload) => {
       if (signal?.aborted) {
         return;
       }
@@ -23,14 +26,18 @@ class Publisher {
         resolver.resolve({ done: false, value: payload });
       } else {
         bufferedEvents.push(payload);
-        if (bufferedEvents.length > maxBufferedEvents) {
+        if (bufferedEvents.length > bufferLimit) {
           bufferedEvents.shift();
         }
       }
     }, {
       lastEventId: listenerOrOptions?.lastEventId,
       onError: (error) => terminate({ kind: "error", error })
-    }).catch((error) => terminate({ kind: "error", error }));
+    });
+    const unsubscribePromise = (resuming ? subscription.finally(() => {
+      bufferFloor = bufferedEvents.length;
+      bufferLimit = bufferFloor + maxBufferedEvents;
+    }) : subscription).catch((error) => terminate({ kind: "error", error }));
     const abortListener = () => terminate({ kind: "error", error: signal.reason });
     signal?.addEventListener("abort", abortListener);
     let terminalState;
@@ -47,7 +54,7 @@ class Publisher {
       }
       if (signal?.aborted) {
         pullResolvers.length = 0;
-        bufferedEvents.length = 0;
+        bufferedEvents.clear();
       }
       await unsubscribePromise.then((unsubscribe) => unsubscribe?.());
     }
@@ -56,8 +63,13 @@ class Publisher {
         if (terminalState?.kind === "cancelled") {
           return { done: true, value: void 0 };
         }
-        if (bufferedEvents.length > 0) {
-          return { done: false, value: bufferedEvents.shift() };
+        const value = bufferedEvents.shift();
+        if (value !== void 0) {
+          if (bufferedEvents.length < bufferFloor) {
+            bufferFloor = bufferedEvents.length;
+            bufferLimit = bufferFloor + maxBufferedEvents;
+          }
+          return { done: false, value };
         }
         if (terminalState?.kind === "error") {
           throw terminalState.error;
@@ -70,5 +82,31 @@ class Publisher {
     );
   }
 }
+class Queue {
+  items = [];
+  head = 0;
+  get length() {
+    return this.items.length - this.head;
+  }
+  push(item) {
+    this.items.push(item);
+  }
+  shift() {
+    if (this.head === this.items.length) {
+      return void 0;
+    }
+    const item = this.items[this.head];
+    this.items[this.head++] = void 0;
+    if (this.head >= 32 && this.head * 2 >= this.items.length) {
+      this.items.splice(0, this.head);
+      this.head = 0;
+    }
+    return item;
+  }
+  clear() {
+    this.items.length = 0;
+    this.head = 0;
+  }
+}
 
 export { Publisher as P };