@orpc/publisher 1.14.11

package/dist/adapters/redis.mjs

@@ -0,0 +1,125 @@
+import { RPCSerializer } from '@orpc/client';
+import { stringifyJSON, parseEmptyableJSON, once } from '@orpc/shared';
+import { unwrapEvent, withEventMeta, getEventMeta } from '@standardserver/core';
+import { P as Publisher } from '../shared/publisher.BSQf8ybR.mjs';
+
+class RedisPublisher extends Publisher {
+  constructor(redis, options = {}) {
+    super(options);
+    this.redis = redis;
+    this.prefix = options.prefix ?? "";
+    this.serializer = options.serializer ?? new RPCSerializer();
+    this.resumeEnabled = options.resume?.enabled ?? false;
+    this.resumeSeconds = options.resume?.seconds ?? 300;
+    this.subscriber = options.subscriber ?? redis.duplicate();
+  }
+  subscriber;
+  prefix;
+  serializer;
+  resumeEnabled;
+  resumeSeconds;
+  /**
+   * 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.redis.isOpen) {
+      await this.redis.connect();
+    }
+    if (this.resumeEnabled) {
+      const now = Date.now();
+      for (const [event2, firstPublishTime] of this.firstPublishTimeMap) {
+        if (firstPublishTime + this.resumeSeconds * 1e3 < now) {
+          this.firstPublishTimeMap.delete(event2);
+        }
+      }
+      if (!this.firstPublishTimeMap.has(event)) {
+        this.firstPublishTimeMap.set(event, now);
+        const result = await this.redis.multi().xAdd(redisKey, "*", { data: stringifyJSON(data) }).xTrim(redisKey, "MINID", `${now - this.resumeSeconds * 1e3}-0`, { strategyModifier: this.xTrimExactness }).expire(redisKey, this.resumeSeconds * 2).exec();
+        id = result[0];
+      } else {
+        id = await this.redis.xAdd(redisKey, "*", { data: stringifyJSON(data) });
+      }
+    }
+    await this.redis.publish(redisKey, stringifyJSON({ data, id }));
+  }
+  async subscribeListener(event, originalListener, { lastEventId, onError } = {}) {
+    const redisKey = `${this.prefix}${event}`;
+    if (!this.subscriber.isOpen) {
+      await this.subscriber.connect();
+    }
+    let pendingPayloads = [];
+    const resumedIds = /* @__PURE__ */ new Set();
+    const deduplicatingListener = (payload) => {
+      if (pendingPayloads) {
+        pendingPayloads.push(payload);
+        return;
+      }
+      const id = getEventMeta(payload)?.id;
+      if (id !== void 0 && resumedIds.has(id)) {
+        return;
+      }
+      originalListener(payload);
+    };
+    const redisListener = (message) => {
+      try {
+        const { id, data } = parseEmptyableJSON(message);
+        const payload = this.deserializePayload(id, data);
+        deduplicatingListener(payload);
+      } catch (error) {
+        onError?.(error);
+      }
+    };
+    try {
+      const subscribePromise = this.subscriber.subscribe(redisKey, redisListener);
+      try {
+        if (this.resumeEnabled && lastEventId !== void 0) {
+          if (!this.redis.isOpen) {
+            await this.redis.connect();
+          }
+          const results = await this.redis.xRead({ key: redisKey, id: lastEventId });
+          if (results && results[0]) {
+            const { messages } = results[0];
+            for (const { id, message } of messages) {
+              const rawData = message.data;
+              const data = parseEmptyableJSON(rawData);
+              const payload = this.deserializePayload(id, data);
+              resumedIds.add(id);
+              originalListener(payload);
+            }
+          }
+        }
+      } finally {
+        const pending = pendingPayloads;
+        pendingPayloads = void 0;
+        for (const payload of pending) {
+          deduplicatingListener(payload);
+        }
+      }
+      await subscribePromise;
+    } catch (error) {
+      await this.subscriber.unsubscribe(redisKey, redisListener);
+      throw error;
+    }
+    return once(async () => {
+      await this.subscriber.unsubscribe(redisKey, redisListener);
+    });
+  }
+  serializePayload(payload) {
+    const [original, meta] = unwrapEvent(payload);
+    return { payload: this.serializer.serialize(original, { useFormDataForBlobFields: false }), meta };
+  }
+  deserializePayload(id, { payload, meta }) {
+    return withEventMeta(
+      this.serializer.deserialize(payload),
+      id === void 0 ? { ...meta } : { ...meta, id }
+    );
+  }
+}
+
+export { RedisPublisher };

package/dist/adapters/upstash.d.mts

@@ -0,0 +1,74 @@
+import { Redis } from '@upstash/redis';
+import { Publisher, PublisherOptions, PublisherSubscribeListenerOptions } from '../index.mjs';
+import { RPCSerializer } from '@orpc/client';
+import '@orpc/shared';
+
+interface UpstashPublisherOptions extends PublisherOptions {
+    /**
+     * The prefix to use for Redis keys.
+     *
+     * @default ''
+     */
+    prefix?: string;
+    /**
+     * Serializer for serialize and deserialize payloads.
+     *
+     * @default RPCSerializer
+     */
+    serializer?: undefined | Pick<RPCSerializer, keyof RPCSerializer>;
+    /**
+     * Configuration for event resume support.
+     *
+     * When enabled, published events are temporarily stored so new
+     * subscribers can resume from a previous position using `lastEventId`.
+     *
+     * @default { enabled: false }
+     */
+    resume?: {
+        /**
+         * Whether event resume 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 resume.
+         *
+         * 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;
+    };
+}
+declare class UpstashPublisher<T extends Record<string, object>> extends Publisher<T> {
+    private readonly redis;
+    private readonly prefix;
+    private readonly serializer;
+    private readonly listenersMap;
+    private readonly onErrorsMap;
+    private readonly subscriptionMap;
+    private readonly resumeEnabled;
+    private readonly resumeSeconds;
+    /**
+     * The exactness of the `XTRIM` command.
+     * Used for testing purpose.
+     */
+    private readonly xTrimExactness;
+    constructor(redis: Redis, { resume, 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;
+}
+
+export { UpstashPublisher };
+export type { UpstashPublisherOptions };

package/dist/adapters/upstash.d.ts

@@ -0,0 +1,74 @@
+import { Redis } from '@upstash/redis';
+import { Publisher, PublisherOptions, PublisherSubscribeListenerOptions } from '../index.js';
+import { RPCSerializer } from '@orpc/client';
+import '@orpc/shared';
+
+interface UpstashPublisherOptions extends PublisherOptions {
+    /**
+     * The prefix to use for Redis keys.
+     *
+     * @default ''
+     */
+    prefix?: string;
+    /**
+     * Serializer for serialize and deserialize payloads.
+     *
+     * @default RPCSerializer
+     */
+    serializer?: undefined | Pick<RPCSerializer, keyof RPCSerializer>;
+    /**
+     * Configuration for event resume support.
+     *
+     * When enabled, published events are temporarily stored so new
+     * subscribers can resume from a previous position using `lastEventId`.
+     *
+     * @default { enabled: false }
+     */
+    resume?: {
+        /**
+         * Whether event resume 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 resume.
+         *
+         * 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;
+    };
+}
+declare class UpstashPublisher<T extends Record<string, object>> extends Publisher<T> {
+    private readonly redis;
+    private readonly prefix;
+    private readonly serializer;
+    private readonly listenersMap;
+    private readonly onErrorsMap;
+    private readonly subscriptionMap;
+    private readonly resumeEnabled;
+    private readonly resumeSeconds;
+    /**
+     * The exactness of the `XTRIM` command.
+     * Used for testing purpose.
+     */
+    private readonly xTrimExactness;
+    constructor(redis: Redis, { resume, 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;
+}
+
+export { UpstashPublisher };
+export type { UpstashPublisherOptions };

package/dist/adapters/upstash.mjs

@@ -0,0 +1,200 @@
+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';
+
+class UpstashPublisher extends Publisher {
+  constructor(redis, { resume, prefix, serializer, ...options } = {}) {
+    super(options);
+    this.redis = redis;
+    this.prefix = prefix ?? "";
+    this.resumeEnabled = resume?.enabled ?? false;
+    this.resumeSeconds = resume?.seconds ?? 300;
+    this.serializer = serializer ?? new RPCSerializer();
+  }
+  prefix;
+  serializer;
+  listenersMap = /* @__PURE__ */ new Map();
+  onErrorsMap = /* @__PURE__ */ new Map();
+  subscriptionMap = /* @__PURE__ */ new Map();
+  // Upstash subscription objects
+  resumeEnabled;
+  resumeSeconds;
+  /**
+   * 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.resumeEnabled) {
+      const now = Date.now();
+      for (const [event2, firstPublishTime] of this.firstPublishTimeMap) {
+        if (firstPublishTime + this.resumeSeconds * 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.resumeSeconds * 1e3}-0` }).expire(redisKey, this.resumeSeconds * 2).exec();
+        id = results[0];
+      } else {
+        id = await this.redis.xadd(redisKey, "*", { data });
+      }
+    }
+    await this.redis.publish(redisKey, { id, data });
+  }
+  async subscribeListener(event, originalListener, { lastEventId, onError } = {}) {
+    const redisKey = `${this.prefix}${event}`;
+    let pendingPayloads = [];
+    const resumedIds = /* @__PURE__ */ new Set();
+    const deduplicatingListener = (payload) => {
+      if (pendingPayloads) {
+        pendingPayloads.push(payload);
+        return;
+      }
+      const id = getEventMeta(payload)?.id;
+      if (id !== void 0 && resumedIds.has(id)) {
+        return;
+      }
+      originalListener(payload);
+    };
+    let listeners = this.listenersMap.get(event);
+    if (!listeners) {
+      this.listenersMap.set(event, listeners = []);
+    }
+    listeners.push(deduplicatingListener);
+    try {
+      const subscribeEventPromise = this.subscribeEvent(event);
+      try {
+        if (this.resumeEnabled && 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);
+              resumedIds.add(id);
+              originalListener(payload);
+            }
+          }
+        }
+      } finally {
+        const pending = pendingPayloads;
+        pendingPayloads = void 0;
+        for (const payload of pending) {
+          deduplicatingListener(payload);
+        }
+      }
+      await subscribeEventPromise;
+    } catch (error) {
+      listeners.splice(listeners.indexOf(deduplicatingListener), 1);
+      if (listeners.length === 0) {
+        this.listenersMap.delete(event);
+      }
+      await this.unsubscribeEvent(event);
+      throw error;
+    }
+    if (onError) {
+      let onErrors = this.onErrorsMap.get(event);
+      if (!onErrors) {
+        this.onErrorsMap.set(event, onErrors = []);
+      }
+      onErrors.push(onError);
+    }
+    return once(async () => {
+      listeners.splice(listeners.indexOf(deduplicatingListener), 1);
+      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);
+      }
+      await this.unsubscribeEvent(event);
+    });
+  }
+  pendingSubscriptionsMap = /* @__PURE__ */ new Map();
+  async subscribeEvent(event) {
+    const redisKey = `${this.prefix}${event}`;
+    const pending = this.pendingSubscriptionsMap.get(event);
+    if (pending) {
+      try {
+        await pending;
+      } catch {
+      }
+    }
+    if (this.subscriptionMap.has(event)) {
+      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;
+    });
+    subscription.on("error", (error) => {
+      rejectPromise(error);
+      dispatchErrorForEvent(error);
+    });
+    subscription.on("subscribe", () => {
+      resolvePromise();
+    });
+    try {
+      this.pendingSubscriptionsMap.set(event, promise);
+      await promise;
+      this.subscriptionMap.set(event, subscription);
+    } finally {
+      this.pendingSubscriptionsMap.delete(event);
+    }
+  }
+  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);
+      await subscription.unsubscribe();
+    }
+  }
+  serializePayload(payload) {
+    const [original, meta] = unwrapEvent(payload);
+    return { payload: this.serializer.serialize(original, { useFormDataForBlobFields: false }), meta };
+  }
+  deserializePayload(id, { payload, meta }) {
+    return withEventMeta(
+      this.serializer.deserialize(payload),
+      id === void 0 ? { ...meta } : { ...meta, id }
+    );
+  }
+}
+
+export { UpstashPublisher };

package/dist/index.d.mts

@@ -0,0 +1,85 @@
+import { ThrowableError, AsyncIteratorClass } from '@orpc/shared';
+
+interface PublisherOptions {
+    /**
+     * 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.
+     *
+     * Set to:
+     * - `0`: Disable buffering. Events must be consumed before the next one arrives.
+     * - `1`: Only keep the latest event. Useful for real-time updates where only the most recent value matters.
+     * - `Infinity`: Keep all events. Ensures no data loss, but may lead to high memory usage.
+     *
+     * @default 100
+     */
+    maxBufferedEvents?: number;
+}
+interface PublisherSubscribeListenerOptions {
+    /**
+     * Resume from a specific event ID
+     */
+    lastEventId?: string | undefined;
+    /**
+     * Triggered when an error occur
+     */
+    onError?: (error: ThrowableError) => void;
+}
+interface PublisherSubscribeIteratorOptions extends Pick<PublisherSubscribeListenerOptions, 'lastEventId'>, Pick<PublisherOptions, 'maxBufferedEvents'> {
+    /**
+     * Abort signal, automatically unsubscribes on abort
+     */
+    signal?: AbortSignal | undefined | null;
+}
+declare abstract class Publisher<T extends Record<string, object>> {
+    private readonly maxBufferedEvents;
+    constructor(options?: PublisherOptions);
+    /**
+     * Publish an event to subscribers
+     */
+    abstract publish<K extends keyof T & string>(event: K, payload: T[K]): Promise<void>;
+    /**
+     * Subscribes to a specific event using a callback function.
+     * Returns an unsubscribe function to remove the listener.
+     *
+     * @remarks
+     * This method should be protected to avoid conflicts with `subscribe` method
+     */
+    protected abstract subscribeListener<K extends keyof T & string>(event: K, listener: (payload: T[K]) => void, options?: PublisherSubscribeListenerOptions): Promise<() => Promise<void>>;
+    /**
+     * Subscribes to a specific event using a callback function.
+     * Returns an unsubscribe function to remove the listener.
+     *
+     * @example
+     * ```ts
+     * const unsubscribe = publisher.subscribe('event', (payload) => {
+     *   console.log(payload)
+     * }, {
+     *   lastEventId,
+     *   onError: (error) => {
+     *     // handle error (consider unsubscribe if error can't be recovered)
+     *   }
+     * })
+     *
+     * // Later
+     * unsubscribe()
+     * ```
+     */
+    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 AsyncIteratorObject.
+     * Useful for `for await...of` loops with optional buffering and abort support.
+     *
+     * @example
+     * ```ts
+     * for await (const payload of publisher.subscribe('event', { signal, lastEventId })) {
+     *   console.log(payload)
+     * }
+     * ```
+     */
+    subscribe<K extends keyof T & string>(event: K, options?: PublisherSubscribeIteratorOptions): AsyncIteratorClass<T[K], void, void>;
+}
+
+export { Publisher };
+export type { PublisherOptions, PublisherSubscribeIteratorOptions, PublisherSubscribeListenerOptions };

package/dist/index.d.ts

@@ -0,0 +1,85 @@
+import { ThrowableError, AsyncIteratorClass } from '@orpc/shared';
+
+interface PublisherOptions {
+    /**
+     * 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.
+     *
+     * Set to:
+     * - `0`: Disable buffering. Events must be consumed before the next one arrives.
+     * - `1`: Only keep the latest event. Useful for real-time updates where only the most recent value matters.
+     * - `Infinity`: Keep all events. Ensures no data loss, but may lead to high memory usage.
+     *
+     * @default 100
+     */
+    maxBufferedEvents?: number;
+}
+interface PublisherSubscribeListenerOptions {
+    /**
+     * Resume from a specific event ID
+     */
+    lastEventId?: string | undefined;
+    /**
+     * Triggered when an error occur
+     */
+    onError?: (error: ThrowableError) => void;
+}
+interface PublisherSubscribeIteratorOptions extends Pick<PublisherSubscribeListenerOptions, 'lastEventId'>, Pick<PublisherOptions, 'maxBufferedEvents'> {
+    /**
+     * Abort signal, automatically unsubscribes on abort
+     */
+    signal?: AbortSignal | undefined | null;
+}
+declare abstract class Publisher<T extends Record<string, object>> {
+    private readonly maxBufferedEvents;
+    constructor(options?: PublisherOptions);
+    /**
+     * Publish an event to subscribers
+     */
+    abstract publish<K extends keyof T & string>(event: K, payload: T[K]): Promise<void>;
+    /**
+     * Subscribes to a specific event using a callback function.
+     * Returns an unsubscribe function to remove the listener.
+     *
+     * @remarks
+     * This method should be protected to avoid conflicts with `subscribe` method
+     */
+    protected abstract subscribeListener<K extends keyof T & string>(event: K, listener: (payload: T[K]) => void, options?: PublisherSubscribeListenerOptions): Promise<() => Promise<void>>;
+    /**
+     * Subscribes to a specific event using a callback function.
+     * Returns an unsubscribe function to remove the listener.
+     *
+     * @example
+     * ```ts
+     * const unsubscribe = publisher.subscribe('event', (payload) => {
+     *   console.log(payload)
+     * }, {
+     *   lastEventId,
+     *   onError: (error) => {
+     *     // handle error (consider unsubscribe if error can't be recovered)
+     *   }
+     * })
+     *
+     * // Later
+     * unsubscribe()
+     * ```
+     */
+    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 AsyncIteratorObject.
+     * Useful for `for await...of` loops with optional buffering and abort support.
+     *
+     * @example
+     * ```ts
+     * for await (const payload of publisher.subscribe('event', { signal, lastEventId })) {
+     *   console.log(payload)
+     * }
+     * ```
+     */
+    subscribe<K extends keyof T & string>(event: K, options?: PublisherSubscribeIteratorOptions): AsyncIteratorClass<T[K], void, void>;
+}
+
+export { Publisher };
+export type { PublisherOptions, PublisherSubscribeIteratorOptions, PublisherSubscribeListenerOptions };

package/dist/index.mjs

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