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

package/dist/adapters/base-redis.d.ts

@@ -0,0 +1,138 @@
+import { Public, ThrowableError } from '@orpc/shared';
+import { Publisher, PublisherOptions, PublisherSubscribeListenerOptions } from '../index.js';
+import { RPCJsonSerializer } from '@orpc/client';
+
+/**
+ * Options shared by every Redis-backed publisher adapter.
+ *
+ * @see {@link https://orpc.dev/docs/helpers/publisher#adapters | Publisher Helpers - Adapters}
+ */
+interface BaseRedisPublisherOptions extends PublisherOptions {
+    /**
+     * The prefix to use for Redis keys.
+     *
+     * @default ''
+     */
+    prefix?: string;
+    /**
+     * Serializer for serialize and deserialize payloads.
+     *
+     * @default RPCJsonSerializer
+     */
+    serializer?: undefined | Public<RPCJsonSerializer>;
+    /**
+     * 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;
+    };
+}
+/**
+ * An entry of the Redis Stream that stores events for resume.
+ *
+ * @see {@link https://orpc.dev/docs/helpers/publisher#adapters | Publisher Helpers - Adapters}
+ */
+interface RedisStreamEntry {
+    /**
+     * The entry ID assigned by Redis, which doubles as the event ID.
+     */
+    id: string;
+    /**
+     * The `data` field, as JSON text or already parsed by clients that deserialize automatically.
+     */
+    data: unknown;
+}
+/**
+ * Trimming to apply to a Redis Stream while adding an entry.
+ *
+ * @see {@link https://orpc.dev/docs/helpers/publisher#adapters | Publisher Helpers - Adapters}
+ */
+interface RedisStreamTrimOptions {
+    /**
+     * Entries with an ID lower than this one are removed (`XTRIM key MINID minId`).
+     */
+    minId: string;
+    /**
+     * Whether trimming is exact (`=`) or approximate (`~`).
+     */
+    exactness: '~' | '=';
+    /**
+     * Time to live to set on the stream key, in seconds (`EXPIRE key seconds`).
+     */
+    expireSeconds: number;
+}
+/**
+ * Base class for Redis-backed publisher adapters. It owns the key naming, the
+ * message format, and the resume logic, so every adapter built on it can exchange
+ * events with the others regardless of the Redis client in use.
+ *
+ * Extend it and implement the abstract methods to support another Redis client.
+ *
+ * @see {@link https://orpc.dev/docs/helpers/publisher#adapters | Publisher Helpers - Adapters}
+ */
+declare abstract class BaseRedisPublisher<T extends Record<string, object>> extends Publisher<T> {
+    protected readonly prefix: string;
+    protected readonly serializer: Public<RPCJsonSerializer>;
+    protected readonly resumeEnabled: boolean;
+    protected readonly resumeSeconds: number;
+    /**
+     * Tests switch this to `=` for deterministic trimming.
+     */
+    protected readonly xTrimExactness: '~' | '=';
+    private readonly lastTrimTimes;
+    constructor({ prefix, serializer, resume, ...options }?: BaseRedisPublisherOptions);
+    /**
+     * Sends a message to a Pub/Sub channel (`PUBLISH channel message`).
+     */
+    protected abstract publishMessage(channel: string, message: string): Promise<void>;
+    /**
+     * Listens for messages on a Pub/Sub channel (`SUBSCRIBE channel`) and resolves
+     * with a function that stops listening (`UNSUBSCRIBE channel`).
+     *
+     * Messages reach the listener as JSON text, or already parsed by clients that
+     * deserialize automatically. The listener may be invoked as soon as the subscription is established, even
+     * before the returned promise settles. When the promise rejects, nothing may be
+     * left subscribed. `onError` reports failures of the established subscription,
+     * such as a lost connection.
+     */
+    protected abstract subscribeChannel(channel: string, listener: (message: unknown) => void, onError?: (error: ThrowableError) => void): Promise<() => Promise<void>>;
+    /**
+     * Appends an entry to a stream (`XADD key * data <data>`) and resolves with its ID.
+     * When `trim` is provided, also trims the stream and refreshes its TTL,
+     * preferably within the same round trip.
+     */
+    protected abstract addStreamEntry(key: string, data: string, trim?: RedisStreamTrimOptions): Promise<string>;
+    /**
+     * Reads the entries with an ID greater than `lastId` (`XREAD STREAMS key lastId`), oldest first.
+     */
+    protected abstract readStreamEntries(key: string, lastId: string): Promise<RedisStreamEntry[]>;
+    publish<K extends keyof T & string>(event: K, payload: T[K]): Promise<void>;
+    protected subscribeListener<K extends keyof T & string>(event: K, listener: (payload: T[K]) => void, { lastEventId, onError }?: PublisherSubscribeListenerOptions): Promise<() => Promise<void>>;
+    private serializePayload;
+    private deserializePayload;
+}
+
+export { BaseRedisPublisher };
+export type { BaseRedisPublisherOptions, RedisStreamEntry, RedisStreamTrimOptions };

package/dist/adapters/base-redis.mjs

@@ -0,0 +1,104 @@
+import { RPCJsonSerializer } from '@orpc/client';
+import { stringifyJSON, once, parseEmptyableJSON } from '@orpc/shared';
+import { unwrapEvent, withEventMeta, getEventMeta } from '@standard-server/core';
+import { P as Publisher } from '../shared/publisher.BSQf8ybR.mjs';
+
+class BaseRedisPublisher extends Publisher {
+  prefix;
+  serializer;
+  resumeEnabled;
+  resumeSeconds;
+  /**
+   * Tests switch this to `=` for deterministic trimming.
+   */
+  xTrimExactness = "~";
+  lastTrimTimes = /* @__PURE__ */ new Map();
+  constructor({ prefix, serializer, resume, ...options } = {}) {
+    super(options);
+    this.prefix = prefix ?? "";
+    this.serializer = serializer ?? new RPCJsonSerializer();
+    this.resumeEnabled = resume?.enabled ?? false;
+    this.resumeSeconds = resume?.seconds ?? 300;
+  }
+  async publish(event, payload) {
+    const channel = `${this.prefix}${event}`;
+    const data = this.serializePayload(payload);
+    let id;
+    if (this.resumeEnabled) {
+      const now = Date.now();
+      const windowMs = this.resumeSeconds * 1e3;
+      for (const [trimmedChannel, trimTime] of this.lastTrimTimes) {
+        if (trimTime + windowMs < now) {
+          this.lastTrimTimes.delete(trimmedChannel);
+        }
+      }
+      if (this.lastTrimTimes.has(channel)) {
+        id = await this.addStreamEntry(channel, stringifyJSON(data));
+      } else {
+        this.lastTrimTimes.set(channel, now);
+        id = await this.addStreamEntry(channel, stringifyJSON(data), {
+          minId: `${now - windowMs}-0`,
+          exactness: this.xTrimExactness,
+          // 2x so entries added late in a window outlive it until the next trim refreshes the TTL.
+          expireSeconds: this.resumeSeconds * 2
+        });
+      }
+    }
+    await this.publishMessage(channel, stringifyJSON({ data, id }));
+  }
+  async subscribeListener(event, listener, { lastEventId, onError } = {}) {
+    const channel = `${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)) {
+        listener(payload);
+      }
+    };
+    const messageListener = (message) => {
+      try {
+        const { id, data } = parseIfText(message);
+        deduplicatingListener(this.deserializePayload(id, data));
+      } catch (error) {
+        onError?.(error);
+      }
+    };
+    const unsubscribe = await this.subscribeChannel(channel, messageListener, onError);
+    try {
+      if (this.resumeEnabled && lastEventId !== void 0) {
+        for (const { id, data } of await this.readStreamEntries(channel, lastEventId)) {
+          resumedIds.add(id);
+          listener(this.deserializePayload(id, parseIfText(data)));
+        }
+      }
+      const pending = pendingPayloads;
+      pendingPayloads = void 0;
+      pending.forEach(deduplicatingListener);
+    } catch (error) {
+      await unsubscribe();
+      throw error;
+    }
+    return once(unsubscribe);
+  }
+  serializePayload(payload) {
+    const [original, meta] = unwrapEvent(payload);
+    const { json, meta: jsonMeta } = this.serializer.serialize(original);
+    return { payload: { json, meta: jsonMeta }, meta };
+  }
+  deserializePayload(id, { payload, meta }) {
+    return withEventMeta(
+      this.serializer.deserialize(payload),
+      id === void 0 ? { ...meta } : { ...meta, id }
+    );
+  }
+}
+function parseIfText(value) {
+  return typeof value === "string" ? parseEmptyableJSON(value) : value;
+}
+
+export { BaseRedisPublisher };

package/dist/adapters/memory.d.mts

@@ -3,16 +3,16 @@ import '@orpc/shared';
 
 interface MemoryPublisherOptions extends PublisherOptions {
     /**
-     * Configuration for event replay support.
+     * 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 }
      */
-    replay?: {
+    resume?: {
         /**
-         * Whether event replay support is enabled.
+         * Whether event resume support is enabled.
          *
          * When enabled, published events are temporarily stored so new
          * subscribers can resume from a previous position using `lastEventId`.
@@ -21,7 +21,7 @@ interface MemoryPublisherOptions extends PublisherOptions {
          */
         enabled: boolean;
         /**
-         * How long (in seconds) to retain events for replay.
+         * 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.
@@ -31,13 +31,19 @@ interface MemoryPublisherOptions extends PublisherOptions {
         seconds?: number;
     };
 }
+/**
+ * Publisher adapter backed by in-memory storage, with optional resume support.
+ * Events are delivered to subscribers within the same process only.
+ *
+ * @see {@link https://orpc.dev/docs/helpers/publisher#adapters | Publisher Helpers - Adapters}
+ */
 declare class MemoryPublisher<T extends Record<string, object>> extends Publisher<T> {
     private readonly listenersMap;
     private readonly idGenerator;
     private readonly eventsMap;
-    private readonly replayEnabled;
-    private readonly replaySeconds;
-    constructor({ replay, ...options }?: MemoryPublisherOptions);
+    private readonly resumeEnabled;
+    private readonly resumeSeconds;
+    constructor({ resume, ...options }?: MemoryPublisherOptions);
     publish<K extends keyof T & string>(event: K, payload: T[K]): Promise<void>;
     protected subscribeListener<K extends keyof T & string>(event: K, listener: (payload: T[K]) => void, options?: PublisherSubscribeListenerOptions): Promise<() => Promise<void>>;
     private lastCleanupTime;

package/dist/adapters/memory.d.ts

@@ -3,16 +3,16 @@ import '@orpc/shared';
 
 interface MemoryPublisherOptions extends PublisherOptions {
     /**
-     * Configuration for event replay support.
+     * 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 }
      */
-    replay?: {
+    resume?: {
         /**
-         * Whether event replay support is enabled.
+         * Whether event resume support is enabled.
          *
          * When enabled, published events are temporarily stored so new
          * subscribers can resume from a previous position using `lastEventId`.
@@ -21,7 +21,7 @@ interface MemoryPublisherOptions extends PublisherOptions {
          */
         enabled: boolean;
         /**
-         * How long (in seconds) to retain events for replay.
+         * 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.
@@ -31,13 +31,19 @@ interface MemoryPublisherOptions extends PublisherOptions {
         seconds?: number;
     };
 }
+/**
+ * Publisher adapter backed by in-memory storage, with optional resume support.
+ * Events are delivered to subscribers within the same process only.
+ *
+ * @see {@link https://orpc.dev/docs/helpers/publisher#adapters | Publisher Helpers - Adapters}
+ */
 declare class MemoryPublisher<T extends Record<string, object>> extends Publisher<T> {
     private readonly listenersMap;
     private readonly idGenerator;
     private readonly eventsMap;
-    private readonly replayEnabled;
-    private readonly replaySeconds;
-    constructor({ replay, ...options }?: MemoryPublisherOptions);
+    private readonly resumeEnabled;
+    private readonly resumeSeconds;
+    constructor({ resume, ...options }?: MemoryPublisherOptions);
     publish<K extends keyof T & string>(event: K, payload: T[K]): Promise<void>;
     protected subscribeListener<K extends keyof T & string>(event: K, listener: (payload: T[K]) => void, options?: PublisherSubscribeListenerOptions): Promise<() => Promise<void>>;
     private lastCleanupTime;

package/dist/adapters/memory.mjs

@@ -1,22 +1,22 @@
 import { SequentialIdGenerator, once, compareSequentialIds } from '@orpc/shared';
-import { unwrapEvent, withEventMeta, getEventMeta } from '@standardserver/core';
+import { unwrapEvent, withEventMeta, getEventMeta } from '@standard-server/core';
 import { P as Publisher } from '../shared/publisher.BSQf8ybR.mjs';
 
 class MemoryPublisher extends Publisher {
   listenersMap = /* @__PURE__ */ new Map();
   idGenerator = new SequentialIdGenerator();
   eventsMap = /* @__PURE__ */ new Map();
-  replayEnabled;
-  replaySeconds;
-  constructor({ replay, ...options } = {}) {
+  resumeEnabled;
+  resumeSeconds;
+  constructor({ resume, ...options } = {}) {
     super(options);
-    this.replayEnabled = replay?.enabled ?? false;
-    this.replaySeconds = replay?.seconds ?? 300;
+    this.resumeEnabled = resume?.enabled ?? false;
+    this.resumeSeconds = resume?.seconds ?? 300;
   }
   async publish(event, payload) {
     this.cleanup();
-    if (this.replayEnabled) {
-      const expiresAt = Date.now() + this.replaySeconds * 1e3;
+    if (this.resumeEnabled) {
+      const expiresAt = Date.now() + this.resumeSeconds * 1e3;
       let bucket = this.eventsMap.get(event);
       if (!bucket) {
         this.eventsMap.set(event, bucket = []);
@@ -30,10 +30,10 @@ class MemoryPublisher extends Publisher {
   }
   async subscribeListener(event, listener, options) {
     this.cleanup();
-    if (this.replayEnabled && options?.lastEventId !== void 0) {
+    if (this.resumeEnabled && options?.lastEventId !== void 0) {
       const bucket = this.eventsMap.get(event);
       if (bucket?.length) {
-        const startIdx = findReplayStartIndex(bucket, options.lastEventId);
+        const startIdx = findResumeStartIndex(bucket, options.lastEventId);
         for (let i = startIdx; i < bucket.length; i++) {
           listener(bucket[i].payload);
         }
@@ -53,11 +53,11 @@ class MemoryPublisher extends Publisher {
   }
   lastCleanupTime = 0;
   cleanup() {
-    if (!this.replayEnabled) {
+    if (!this.resumeEnabled) {
       return;
     }
     const now = Date.now();
-    if (now - this.lastCleanupTime < this.replaySeconds * 1e3) {
+    if (now - this.lastCleanupTime < this.resumeSeconds * 1e3) {
       return;
     }
     this.lastCleanupTime = now;
@@ -69,7 +69,7 @@ class MemoryPublisher extends Publisher {
     }
   }
 }
-function findReplayStartIndex(bucket, lastEventId) {
+function findResumeStartIndex(bucket, lastEventId) {
   let lo = 0;
   let hi = bucket.length;
   while (lo < hi) {

package/dist/adapters/redis.d.mts

@@ -1,9 +1,10 @@
 import { RedisClientType } from 'redis';
-import { Publisher, PublisherOptions, PublisherSubscribeListenerOptions } from '../index.mjs';
-import { RPCSerializer } from '@orpc/client';
+import { BaseRedisPublisher, BaseRedisPublisherOptions, RedisStreamTrimOptions, RedisStreamEntry } from './base-redis.mjs';
 import '@orpc/shared';
+import '../index.mjs';
+import '@orpc/client';
 
-interface RedisPublisherOptions extends PublisherOptions {
+interface RedisPublisherOptions extends BaseRedisPublisherOptions {
     /**
      * Redis subscriber instance.
      * Pub/Sub takes over the connection, so a client with subscriptions
@@ -12,63 +13,21 @@ interface RedisPublisherOptions extends PublisherOptions {
      * @default redis.duplicate()
      */
     subscriber?: undefined | RedisClientType<any, any, any, any, any>;
-    /**
-     * 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;
-    };
 }
-declare class RedisPublisher<T extends Record<string, object>> extends Publisher<T> {
+/**
+ * Publisher adapter for Redis. Distributes events across processes via
+ * Redis Pub/Sub, with optional resume support backed by Redis Streams.
+ *
+ * @see {@link https://orpc.dev/docs/helpers/publisher#adapters | Publisher Helpers - Adapters}
+ */
+declare class RedisPublisher<T extends Record<string, object>> extends BaseRedisPublisher<T> {
     private readonly redis;
     private readonly subscriber;
-    private readonly prefix;
-    private readonly serializer;
-    private readonly replayEnabled;
-    private readonly replaySeconds;
-    /**
-     * The exactness of the `XTRIM` command.
-     * Used for testing purpose.
-     */
-    private readonly xTrimExactness;
-    constructor(redis: RedisClientType<any, any, any, any, any>, options?: RedisPublisherOptions);
-    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 serializePayload;
-    private deserializePayload;
+    constructor(redis: RedisClientType<any, any, any, any, any>, { subscriber, ...options }?: RedisPublisherOptions);
+    protected publishMessage(channel: string, message: string): Promise<void>;
+    protected subscribeChannel(channel: string, listener: (message: unknown) => void): Promise<() => Promise<void>>;
+    protected addStreamEntry(key: string, data: string, trim?: RedisStreamTrimOptions): Promise<string>;
+    protected readStreamEntries(key: string, lastId: string): Promise<RedisStreamEntry[]>;
 }
 
 export { RedisPublisher };

package/dist/adapters/redis.d.ts

@@ -1,9 +1,10 @@
 import { RedisClientType } from 'redis';
-import { Publisher, PublisherOptions, PublisherSubscribeListenerOptions } from '../index.js';
-import { RPCSerializer } from '@orpc/client';
+import { BaseRedisPublisher, BaseRedisPublisherOptions, RedisStreamTrimOptions, RedisStreamEntry } from './base-redis.js';
 import '@orpc/shared';
+import '../index.js';
+import '@orpc/client';
 
-interface RedisPublisherOptions extends PublisherOptions {
+interface RedisPublisherOptions extends BaseRedisPublisherOptions {
     /**
      * Redis subscriber instance.
      * Pub/Sub takes over the connection, so a client with subscriptions
@@ -12,63 +13,21 @@ interface RedisPublisherOptions extends PublisherOptions {
      * @default redis.duplicate()
      */
     subscriber?: undefined | RedisClientType<any, any, any, any, any>;
-    /**
-     * 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;
-    };
 }
-declare class RedisPublisher<T extends Record<string, object>> extends Publisher<T> {
+/**
+ * Publisher adapter for Redis. Distributes events across processes via
+ * Redis Pub/Sub, with optional resume support backed by Redis Streams.
+ *
+ * @see {@link https://orpc.dev/docs/helpers/publisher#adapters | Publisher Helpers - Adapters}
+ */
+declare class RedisPublisher<T extends Record<string, object>> extends BaseRedisPublisher<T> {
     private readonly redis;
     private readonly subscriber;
-    private readonly prefix;
-    private readonly serializer;
-    private readonly replayEnabled;
-    private readonly replaySeconds;
-    /**
-     * The exactness of the `XTRIM` command.
-     * Used for testing purpose.
-     */
-    private readonly xTrimExactness;
-    constructor(redis: RedisClientType<any, any, any, any, any>, options?: RedisPublisherOptions);
-    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 serializePayload;
-    private deserializePayload;
+    constructor(redis: RedisClientType<any, any, any, any, any>, { subscriber, ...options }?: RedisPublisherOptions);
+    protected publishMessage(channel: string, message: string): Promise<void>;
+    protected subscribeChannel(channel: string, listener: (message: unknown) => void): Promise<() => Promise<void>>;
+    protected addStreamEntry(key: string, data: string, trim?: RedisStreamTrimOptions): Promise<string>;
+    protected readStreamEntries(key: string, lastId: string): Promise<RedisStreamEntry[]>;
 }
 
 export { RedisPublisher };