@orpc/experimental-publisher 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 oRPC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+<div align="center">
+  <image align="center" src="https://orpc.unnoq.com/logo.webp" width=280 alt="oRPC logo" />
+</div>
+
+<h1></h1>
+
+<div align="center">
+  <a href="https://codecov.io/gh/unnoq/orpc">
+    <img alt="codecov" src="https://codecov.io/gh/unnoq/orpc/branch/main/graph/badge.svg">
+  </a>
+  <a href="https://www.npmjs.com/package/@orpc/experimental-publisher">
+    <img alt="weekly downloads" src="https://img.shields.io/npm/dw/%40orpc%2Fexperimental-publisher?logo=npm" />
+  </a>
+  <a href="https://github.com/unnoq/orpc/blob/main/LICENSE">
+    <img alt="MIT License" src="https://img.shields.io/github/license/unnoq/orpc?logo=open-source-initiative" />
+  </a>
+  <a href="https://discord.gg/TXEbwRBvQn">
+    <img alt="Discord" src="https://img.shields.io/discord/1308966753044398161?color=7389D8&label&logo=discord&logoColor=ffffff" />
+  </a>
+  <a href="https://deepwiki.com/unnoq/orpc">
+    <img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki">
+  </a>
+</div>
+
+<h3 align="center">Typesafe APIs Made Simple 🪄</h3>
+
+**oRPC is a powerful combination of RPC and OpenAPI**, makes it easy to build APIs that are end-to-end type-safe and adhere to OpenAPI standards
+
+---
+
+## Highlights
+
+- **🔗 End-to-End Type Safety**: Ensure type-safe inputs, outputs, and errors from client to server.
+- **📘 First-Class OpenAPI**: Built-in support that fully adheres to the OpenAPI standard.
+- **📝 Contract-First Development**: Optionally define your API contract before implementation.
+- **🔍 First-Class OpenTelemetry**: Seamlessly integrate with OpenTelemetry for observability.
+- **⚙️ Framework Integrations**: Seamlessly integrate with TanStack Query (React, Vue, Solid, Svelte, Angular), SWR, Pinia Colada, and more.
+- **🚀 Server Actions**: Fully compatible with React Server Actions on Next.js, TanStack Start, and other platforms.
+- **🔠 Standard Schema Support**: Works out of the box with Zod, Valibot, ArkType, and other schema validators.
+- **🗃️ Native Types**: Supports native types like Date, File, Blob, BigInt, URL, and more.
+- **⏱️ Lazy Router**: Enhance cold start times with our lazy routing feature.
+- **📡 SSE & Streaming**: Enjoy full type-safe support for SSE and streaming.
+- **🌍 Multi-Runtime Support**: Fast and lightweight on Cloudflare, Deno, Bun, Node.js, and beyond.
+- **🔌 Extendability**: Easily extend functionality with plugins, middleware, and interceptors.
+
+## Documentation
+
+You can find the full documentation [here](https://orpc.unnoq.com).
+
+## Packages
+
+- [@orpc/contract](https://www.npmjs.com/package/@orpc/contract): Build your API contract.
+- [@orpc/server](https://www.npmjs.com/package/@orpc/server): Build your API or implement API contract.
+- [@orpc/client](https://www.npmjs.com/package/@orpc/client): Consume your API on the client with type-safety.
+- [@orpc/openapi](https://www.npmjs.com/package/@orpc/openapi): Generate OpenAPI specs and handle OpenAPI requests.
+- [@orpc/otel](https://www.npmjs.com/package/@orpc/otel): [OpenTelemetry](https://opentelemetry.io/) integration for observability.
+- [@orpc/nest](https://www.npmjs.com/package/@orpc/nest): Deeply integrate oRPC with [NestJS](https://nestjs.com/).
+- [@orpc/react](https://www.npmjs.com/package/@orpc/react): Utilities for integrating oRPC with React and React Server Actions.
+- [@orpc/tanstack-query](https://www.npmjs.com/package/@orpc/tanstack-query): [TanStack Query](https://tanstack.com/query/latest) integration.
+- [@orpc/experimental-react-swr](https://www.npmjs.com/package/@orpc/experimental-react-swr): [SWR](https://swr.vercel.app/) integration.
+- [@orpc/vue-colada](https://www.npmjs.com/package/@orpc/vue-colada): Integration with [Pinia Colada](https://pinia-colada.esm.dev/).
+- [@orpc/hey-api](https://www.npmjs.com/package/@orpc/hey-api): [Hey API](https://heyapi.dev/) integration.
+- [@orpc/zod](https://www.npmjs.com/package/@orpc/zod): More schemas that [Zod](https://zod.dev/) doesn't support yet.
+- [@orpc/valibot](https://www.npmjs.com/package/@orpc/valibot): OpenAPI spec generation from [Valibot](https://valibot.dev/).
+- [@orpc/arktype](https://www.npmjs.com/package/@orpc/arktype): OpenAPI spec generation from [ArkType](https://arktype.io/).
+
+## `@orpc/experimental-publisher`
+
+Event Publisher with multiple adapter support, resume support, and more.
+
+## Sponsors
+
+<p align="center">
+  <a href="https://cdn.jsdelivr.net/gh/unnoq/unnoq/sponsors.svg">
+    <img src='https://cdn.jsdelivr.net/gh/unnoq/unnoq/sponsors.svg'/>
+  </a>
+</p>
+
+## License
+
+Distributed under the MIT License. See [LICENSE](https://github.com/unnoq/orpc/blob/main/LICENSE) for more information.

package/dist/adapters/ioredis.d.mts

@@ -0,0 +1,76 @@
+import { StandardRPCJsonSerializerOptions, StandardRPCJsonSerializer, StandardRPCJsonSerializedMetaItem } from '@orpc/client/standard';
+import Redis from 'ioredis';
+import { PublisherOptions, Publisher, PublisherSubscribeListenerOptions } from '../index.mjs';
+import { getEventMeta } from '@orpc/standard-server';
+import '@orpc/shared';
+
+type SerializedPayload = {
+    json: object;
+    meta: StandardRPCJsonSerializedMetaItem[];
+    eventMeta: ReturnType<typeof getEventMeta>;
+};
+interface IORedisPublisherOptions extends PublisherOptions, StandardRPCJsonSerializerOptions {
+    /**
+     * Redis commander instance (used for execute short-lived commands)
+     */
+    commander: Redis;
+    /**
+     * redis listener instance (used for listening to events)
+     *
+     * @remark
+     * - `lazyConnect: true` option is supported
+     */
+    listener: Redis;
+    /**
+     * How long (in seconds) to retain events for replay.
+     *
+     * @remark
+     * This allows new subscribers to "catch up" on missed events using `lastEventId`.
+     * Note that event cleanup is deferred for performance reasons — meaning some
+     * expired events may still be available for a short period of time, and listeners
+     * might still receive them.
+     *
+     * @default NaN (disabled)
+     */
+    resumeRetentionSeconds?: number;
+    /**
+     * The prefix to use for Redis keys.
+     *
+     * @default orpc:publisher:
+     */
+    prefix?: string;
+}
+declare class IORedisPublisher<T extends Record<string, object>> extends Publisher<T> {
+    protected readonly commander: Redis;
+    protected readonly listener: Redis;
+    protected readonly prefix: string;
+    protected readonly serializer: StandardRPCJsonSerializer;
+    protected readonly retentionSeconds: number;
+    protected readonly listenerPromiseMap: Map<string, Promise<any>>;
+    protected readonly listenersMap: Map<string, Set<(payload: any) => void>>;
+    protected redisListener: ((channel: string, message: string) => void) | undefined;
+    protected get isResumeEnabled(): boolean;
+    /**
+     * The exactness of the `XTRIM` command.
+     *
+     * @internal
+     */
+    xtrimExactness: '~' | '=';
+    /**
+     * Useful for measuring memory usage.
+     *
+     * @internal
+     *
+     */
+    get size(): number;
+    constructor({ commander, listener, resumeRetentionSeconds, prefix, ...options }: IORedisPublisherOptions);
+    protected lastCleanupTimes: Map<string, number>;
+    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, options?: PublisherSubscribeListenerOptions): Promise<() => Promise<void>>;
+    protected prefixKey(key: string): string;
+    protected serializePayload(payload: object): SerializedPayload;
+    protected deserializePayload(id: string | undefined, { json, meta, eventMeta }: SerializedPayload): any;
+}
+
+export { IORedisPublisher };
+export type { IORedisPublisherOptions };

package/dist/adapters/ioredis.d.ts

@@ -0,0 +1,76 @@
+import { StandardRPCJsonSerializerOptions, StandardRPCJsonSerializer, StandardRPCJsonSerializedMetaItem } from '@orpc/client/standard';
+import Redis from 'ioredis';
+import { PublisherOptions, Publisher, PublisherSubscribeListenerOptions } from '../index.js';
+import { getEventMeta } from '@orpc/standard-server';
+import '@orpc/shared';
+
+type SerializedPayload = {
+    json: object;
+    meta: StandardRPCJsonSerializedMetaItem[];
+    eventMeta: ReturnType<typeof getEventMeta>;
+};
+interface IORedisPublisherOptions extends PublisherOptions, StandardRPCJsonSerializerOptions {
+    /**
+     * Redis commander instance (used for execute short-lived commands)
+     */
+    commander: Redis;
+    /**
+     * redis listener instance (used for listening to events)
+     *
+     * @remark
+     * - `lazyConnect: true` option is supported
+     */
+    listener: Redis;
+    /**
+     * How long (in seconds) to retain events for replay.
+     *
+     * @remark
+     * This allows new subscribers to "catch up" on missed events using `lastEventId`.
+     * Note that event cleanup is deferred for performance reasons — meaning some
+     * expired events may still be available for a short period of time, and listeners
+     * might still receive them.
+     *
+     * @default NaN (disabled)
+     */
+    resumeRetentionSeconds?: number;
+    /**
+     * The prefix to use for Redis keys.
+     *
+     * @default orpc:publisher:
+     */
+    prefix?: string;
+}
+declare class IORedisPublisher<T extends Record<string, object>> extends Publisher<T> {
+    protected readonly commander: Redis;
+    protected readonly listener: Redis;
+    protected readonly prefix: string;
+    protected readonly serializer: StandardRPCJsonSerializer;
+    protected readonly retentionSeconds: number;
+    protected readonly listenerPromiseMap: Map<string, Promise<any>>;
+    protected readonly listenersMap: Map<string, Set<(payload: any) => void>>;
+    protected redisListener: ((channel: string, message: string) => void) | undefined;
+    protected get isResumeEnabled(): boolean;
+    /**
+     * The exactness of the `XTRIM` command.
+     *
+     * @internal
+     */
+    xtrimExactness: '~' | '=';
+    /**
+     * Useful for measuring memory usage.
+     *
+     * @internal
+     *
+     */
+    get size(): number;
+    constructor({ commander, listener, resumeRetentionSeconds, prefix, ...options }: IORedisPublisherOptions);
+    protected lastCleanupTimes: Map<string, number>;
+    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, options?: PublisherSubscribeListenerOptions): Promise<() => Promise<void>>;
+    protected prefixKey(key: string): string;
+    protected serializePayload(payload: object): SerializedPayload;
+    protected deserializePayload(id: string | undefined, { json, meta, eventMeta }: SerializedPayload): any;
+}
+
+export { IORedisPublisher };
+export type { IORedisPublisherOptions };

package/dist/adapters/ioredis.mjs

@@ -0,0 +1,171 @@
+import { StandardRPCJsonSerializer } from '@orpc/client/standard';
+import { stringifyJSON } from '@orpc/shared';
+import { getEventMeta, withEventMeta } from '@orpc/standard-server';
+import { P as Publisher } from '../shared/experimental-publisher.BOyYBkgn.mjs';
+
+class IORedisPublisher extends Publisher {
+  commander;
+  listener;
+  prefix;
+  serializer;
+  retentionSeconds;
+  listenerPromiseMap = /* @__PURE__ */ new Map();
+  listenersMap = /* @__PURE__ */ new Map();
+  redisListener;
+  get isResumeEnabled() {
+    return Number.isFinite(this.retentionSeconds) && this.retentionSeconds > 0;
+  }
+  /**
+   * The exactness of the `XTRIM` command.
+   *
+   * @internal
+   */
+  xtrimExactness = "~";
+  /**
+   * Useful for measuring memory usage.
+   *
+   * @internal
+   *
+   */
+  get size() {
+    let size = this.redisListener ? 1 : 0;
+    for (const listeners of this.listenersMap) {
+      size += listeners[1].size || 1;
+    }
+    return size;
+  }
+  constructor({ commander, listener, resumeRetentionSeconds, prefix, ...options }) {
+    super(options);
+    this.commander = commander;
+    this.listener = listener;
+    this.prefix = prefix ?? "orpc:publisher:";
+    this.retentionSeconds = resumeRetentionSeconds ?? Number.NaN;
+    this.serializer = new StandardRPCJsonSerializer(options);
+  }
+  lastCleanupTimes = /* @__PURE__ */ new Map();
+  async publish(event, payload) {
+    const key = this.prefixKey(event);
+    const serialized = this.serializePayload(payload);
+    let id;
+    if (this.isResumeEnabled) {
+      const now = Date.now();
+      for (const [key2, lastCleanupTime] of this.lastCleanupTimes) {
+        if (lastCleanupTime + this.retentionSeconds * 1e3 < now) {
+          this.lastCleanupTimes.delete(key2);
+        }
+      }
+      if (!this.lastCleanupTimes.has(key)) {
+        this.lastCleanupTimes.set(key, now);
+        const result = await this.commander.multi().xadd(key, "*", "data", stringifyJSON(serialized)).xtrim(key, "MINID", this.xtrimExactness, `${now - this.retentionSeconds * 1e3}-0`).expire(key, this.retentionSeconds * 2).exec();
+        if (result) {
+          for (const [error] of result) {
+            if (error) {
+              throw error;
+            }
+          }
+        }
+        id = result[0][1];
+      } else {
+        const result = await this.commander.xadd(key, "*", "data", stringifyJSON(serialized));
+        id = result;
+      }
+    }
+    await this.commander.publish(key, stringifyJSON({ ...serialized, id }));
+  }
+  async subscribeListener(event, originalListener, options) {
+    const key = this.prefixKey(event);
+    const lastEventId = options?.lastEventId;
+    let pendingPayloads = [];
+    const resumePayloadIds = /* @__PURE__ */ new Set();
+    const listener = (payload) => {
+      if (pendingPayloads) {
+        pendingPayloads.push(payload);
+        return;
+      }
+      const payloadId = getEventMeta(payload)?.id;
+      if (payloadId !== void 0 && resumePayloadIds.has(payloadId)) {
+        return;
+      }
+      originalListener(payload);
+    };
+    if (!this.redisListener) {
+      this.redisListener = (channel, message) => {
+        try {
+          const listeners2 = this.listenersMap.get(channel);
+          if (listeners2) {
+            const { id, ...rest } = JSON.parse(message);
+            const payload = this.deserializePayload(id, rest);
+            for (const listener2 of listeners2) {
+              listener2(payload);
+            }
+          }
+        } catch {
+        }
+      };
+      this.listener.on("message", this.redisListener);
+    }
+    await this.listenerPromiseMap.get(key);
+    let listeners = this.listenersMap.get(key);
+    if (!listeners) {
+      try {
+        const promise = this.listener.subscribe(key);
+        this.listenerPromiseMap.set(key, promise);
+        await promise;
+        this.listenersMap.set(key, listeners = /* @__PURE__ */ new Set());
+      } finally {
+        this.listenerPromiseMap.delete(key);
+      }
+    }
+    listeners.add(listener);
+    void (async () => {
+      try {
+        if (this.isResumeEnabled && typeof lastEventId === "string") {
+          const results = await this.commander.xread("STREAMS", key, lastEventId);
+          if (results && results[0]) {
+            const [_, items] = results[0];
+            for (const [id, fields] of items) {
+              const serialized = fields[1];
+              const payload = this.deserializePayload(id, JSON.parse(serialized));
+              resumePayloadIds.add(id);
+              originalListener(payload);
+            }
+          }
+        }
+      } catch {
+      } finally {
+        const pending = pendingPayloads;
+        pendingPayloads = void 0;
+        for (const payload of pending) {
+          listener(payload);
+        }
+      }
+    })();
+    return async () => {
+      listeners.delete(listener);
+      if (listeners.size === 0) {
+        this.listenersMap.delete(key);
+        if (this.redisListener && this.listenersMap.size === 0) {
+          this.listener.off("message", this.redisListener);
+          this.redisListener = void 0;
+        }
+        await this.listener.unsubscribe(key);
+      }
+    };
+  }
+  prefixKey(key) {
+    return `${this.prefix}${key}`;
+  }
+  serializePayload(payload) {
+    const eventMeta = getEventMeta(payload);
+    const [json, meta] = this.serializer.serialize(payload);
+    return { json, meta, eventMeta };
+  }
+  deserializePayload(id, { json, meta, eventMeta }) {
+    return withEventMeta(
+      this.serializer.deserialize(json, meta),
+      id === void 0 ? { ...eventMeta } : { ...eventMeta, id }
+    );
+  }
+}
+
+export { IORedisPublisher };

package/dist/adapters/memory.d.mts

@@ -0,0 +1,39 @@
+import { PublisherOptions, Publisher, PublisherSubscribeListenerOptions } from '../index.mjs';
+import '@orpc/shared';
+
+interface MemoryPublisherOptions extends PublisherOptions {
+    /**
+     * How long (in seconds) to retain events for replay.
+     *
+     * @remark
+     * This allows new subscribers to "catch up" on missed events using `lastEventId`.
+     * Note that event cleanup is deferred for performance reasons — meaning some
+     * expired events may still be available for a short period of time, and listeners
+     * might still receive them.
+     *
+     * @default NaN (disabled)
+     */
+    resumeRetentionSeconds?: number;
+}
+declare class MemoryPublisher<T extends Record<string, object>> extends Publisher<T> {
+    private readonly eventPublisher;
+    private readonly idGenerator;
+    private readonly retentionSeconds;
+    private readonly events;
+    /**
+     * Useful for measuring memory usage.
+     *
+     * @internal
+     *
+     */
+    get size(): number;
+    protected get isResumeEnabled(): boolean;
+    constructor({ resumeRetentionSeconds, ...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>>;
+    protected lastCleanupTime: number | null;
+    protected cleanup(): void;
+}
+
+export { MemoryPublisher };
+export type { MemoryPublisherOptions };

package/dist/adapters/memory.d.ts

@@ -0,0 +1,39 @@
+import { PublisherOptions, Publisher, PublisherSubscribeListenerOptions } from '../index.js';
+import '@orpc/shared';
+
+interface MemoryPublisherOptions extends PublisherOptions {
+    /**
+     * How long (in seconds) to retain events for replay.
+     *
+     * @remark
+     * This allows new subscribers to "catch up" on missed events using `lastEventId`.
+     * Note that event cleanup is deferred for performance reasons — meaning some
+     * expired events may still be available for a short period of time, and listeners
+     * might still receive them.
+     *
+     * @default NaN (disabled)
+     */
+    resumeRetentionSeconds?: number;
+}
+declare class MemoryPublisher<T extends Record<string, object>> extends Publisher<T> {
+    private readonly eventPublisher;
+    private readonly idGenerator;
+    private readonly retentionSeconds;
+    private readonly events;
+    /**
+     * Useful for measuring memory usage.
+     *
+     * @internal
+     *
+     */
+    get size(): number;
+    protected get isResumeEnabled(): boolean;
+    constructor({ resumeRetentionSeconds, ...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>>;
+    protected lastCleanupTime: number | null;
+    protected cleanup(): void;
+}
+
+export { MemoryPublisher };
+export type { MemoryPublisherOptions };

package/dist/adapters/memory.mjs

@@ -0,0 +1,82 @@
+import { EventPublisher, SequentialIdGenerator, compareSequentialIds } from '@orpc/shared';
+import { withEventMeta, getEventMeta } from '@orpc/standard-server';
+import { P as Publisher } from '../shared/experimental-publisher.BOyYBkgn.mjs';
+
+class MemoryPublisher extends Publisher {
+  eventPublisher = new EventPublisher();
+  idGenerator = new SequentialIdGenerator();
+  retentionSeconds;
+  events = /* @__PURE__ */ new Map();
+  /**
+   * Useful for measuring memory usage.
+   *
+   * @internal
+   *
+   */
+  get size() {
+    let size = this.eventPublisher.size;
+    for (const events of this.events) {
+      size += events[1].length || 1;
+    }
+    return size;
+  }
+  get isResumeEnabled() {
+    return Number.isFinite(this.retentionSeconds) && this.retentionSeconds > 0;
+  }
+  constructor({ resumeRetentionSeconds, ...options } = {}) {
+    super(options);
+    this.retentionSeconds = resumeRetentionSeconds ?? Number.NaN;
+  }
+  async publish(event, payload) {
+    this.cleanup();
+    if (this.isResumeEnabled) {
+      const now = Date.now();
+      const expiresAt = now + this.retentionSeconds * 1e3;
+      let events = this.events.get(event);
+      if (!events) {
+        this.events.set(event, events = []);
+      }
+      payload = withEventMeta(payload, { ...getEventMeta(payload), id: this.idGenerator.generate() });
+      events.push({ expiresAt, payload });
+    }
+    this.eventPublisher.publish(event, payload);
+  }
+  async subscribeListener(event, listener, options) {
+    if (this.isResumeEnabled && typeof options?.lastEventId === "string") {
+      const events = this.events.get(event);
+      if (events) {
+        for (const { payload } of events) {
+          const id = getEventMeta(payload)?.id;
+          if (typeof id === "string" && compareSequentialIds(id, options.lastEventId) > 0) {
+            listener(payload);
+          }
+        }
+      }
+    }
+    const syncUnsub = this.eventPublisher.subscribe(event, listener);
+    return async () => {
+      syncUnsub();
+    };
+  }
+  lastCleanupTime = null;
+  cleanup() {
+    if (!this.isResumeEnabled) {
+      return;
+    }
+    const now = Date.now();
+    if (this.lastCleanupTime !== null && this.lastCleanupTime + this.retentionSeconds * 1e3 > now) {
+      return;
+    }
+    this.lastCleanupTime = now;
+    for (const [event, events] of this.events) {
+      const validEvents = events.filter((event2) => event2.expiresAt > now);
+      if (validEvents.length > 0) {
+        this.events.set(event, validEvents);
+      } else {
+        this.events.delete(event);
+      }
+    }
+  }
+}
+
+export { MemoryPublisher };

package/dist/adapters/upstash-redis.d.mts

@@ -0,0 +1,64 @@
+import { StandardRPCJsonSerializerOptions, StandardRPCJsonSerializer, StandardRPCJsonSerializedMetaItem } from '@orpc/client/standard';
+import { Redis } from '@upstash/redis';
+import { PublisherOptions, Publisher, PublisherSubscribeListenerOptions } from '../index.mjs';
+import { getEventMeta } from '@orpc/standard-server';
+import '@orpc/shared';
+
+type SerializedPayload = {
+    json: object;
+    meta: StandardRPCJsonSerializedMetaItem[];
+    eventMeta: ReturnType<typeof getEventMeta>;
+};
+interface UpstashRedisPublisherOptions extends PublisherOptions, StandardRPCJsonSerializerOptions {
+    /**
+     * How long (in seconds) to retain events for replay.
+     *
+     * @remark
+     * This allows new subscribers to "catch up" on missed events using `lastEventId`.
+     * Note that event cleanup is deferred for performance reasons — meaning some
+     * expired events may still be available for a short period of time, and listeners
+     * might still receive them.
+     *
+     * @default NaN (disabled)
+     */
+    resumeRetentionSeconds?: number;
+    /**
+     * The prefix to use for Redis keys.
+     *
+     * @default orpc:publisher:
+     */
+    prefix?: string;
+}
+declare class UpstashRedisPublisher<T extends Record<string, object>> extends Publisher<T> {
+    protected readonly redis: Redis;
+    protected readonly prefix: string;
+    protected readonly serializer: StandardRPCJsonSerializer;
+    protected readonly retentionSeconds: number;
+    protected readonly listenersMap: Map<string, Set<(payload: any) => void>>;
+    protected readonly subscriptionPromiseMap: Map<string, Promise<void>>;
+    protected readonly subscriptionsMap: Map<string, any>;
+    protected get isResumeEnabled(): boolean;
+    /**
+     * The exactness of the `XTRIM` command.
+     *
+     * @internal
+     */
+    xtrimExactness: '~' | '=';
+    /**
+     * Useful for measuring memory usage.
+     *
+     * @internal
+     *
+     */
+    get size(): number;
+    constructor(redis: Redis, { resumeRetentionSeconds, prefix, ...options }?: UpstashRedisPublisherOptions);
+    protected lastCleanupTimes: Map<string, number>;
+    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, options?: PublisherSubscribeListenerOptions): Promise<() => Promise<void>>;
+    protected prefixKey(key: string): string;
+    protected serializePayload(payload: object): SerializedPayload;
+    protected deserializePayload(id: string | undefined, { json, meta, eventMeta }: SerializedPayload): any;
+}
+
+export { UpstashRedisPublisher };
+export type { UpstashRedisPublisherOptions };

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

@@ -0,0 +1,64 @@
+import { StandardRPCJsonSerializerOptions, StandardRPCJsonSerializer, StandardRPCJsonSerializedMetaItem } from '@orpc/client/standard';
+import { Redis } from '@upstash/redis';
+import { PublisherOptions, Publisher, PublisherSubscribeListenerOptions } from '../index.js';
+import { getEventMeta } from '@orpc/standard-server';
+import '@orpc/shared';
+
+type SerializedPayload = {
+    json: object;
+    meta: StandardRPCJsonSerializedMetaItem[];
+    eventMeta: ReturnType<typeof getEventMeta>;
+};
+interface UpstashRedisPublisherOptions extends PublisherOptions, StandardRPCJsonSerializerOptions {
+    /**
+     * How long (in seconds) to retain events for replay.
+     *
+     * @remark
+     * This allows new subscribers to "catch up" on missed events using `lastEventId`.
+     * Note that event cleanup is deferred for performance reasons — meaning some
+     * expired events may still be available for a short period of time, and listeners
+     * might still receive them.
+     *
+     * @default NaN (disabled)
+     */
+    resumeRetentionSeconds?: number;
+    /**
+     * The prefix to use for Redis keys.
+     *
+     * @default orpc:publisher:
+     */
+    prefix?: string;
+}
+declare class UpstashRedisPublisher<T extends Record<string, object>> extends Publisher<T> {
+    protected readonly redis: Redis;
+    protected readonly prefix: string;
+    protected readonly serializer: StandardRPCJsonSerializer;
+    protected readonly retentionSeconds: number;
+    protected readonly listenersMap: Map<string, Set<(payload: any) => void>>;
+    protected readonly subscriptionPromiseMap: Map<string, Promise<void>>;
+    protected readonly subscriptionsMap: Map<string, any>;
+    protected get isResumeEnabled(): boolean;
+    /**
+     * The exactness of the `XTRIM` command.
+     *
+     * @internal
+     */
+    xtrimExactness: '~' | '=';
+    /**
+     * Useful for measuring memory usage.
+     *
+     * @internal
+     *
+     */
+    get size(): number;
+    constructor(redis: Redis, { resumeRetentionSeconds, prefix, ...options }?: UpstashRedisPublisherOptions);
+    protected lastCleanupTimes: Map<string, number>;
+    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, options?: PublisherSubscribeListenerOptions): Promise<() => Promise<void>>;
+    protected prefixKey(key: string): string;
+    protected serializePayload(payload: object): SerializedPayload;
+    protected deserializePayload(id: string | undefined, { json, meta, eventMeta }: SerializedPayload): any;
+}
+
+export { UpstashRedisPublisher };
+export type { UpstashRedisPublisherOptions };

package/dist/adapters/upstash-redis.mjs

@@ -0,0 +1,175 @@
+import { StandardRPCJsonSerializer } from '@orpc/client/standard';
+import { getEventMeta, withEventMeta } from '@orpc/standard-server';
+import { P as Publisher } from '../shared/experimental-publisher.BOyYBkgn.mjs';
+import '@orpc/shared';
+
+class UpstashRedisPublisher extends Publisher {
+  constructor(redis, { resumeRetentionSeconds, prefix, ...options } = {}) {
+    super(options);
+    this.redis = redis;
+    this.prefix = prefix ?? "orpc:publisher:";
+    this.retentionSeconds = resumeRetentionSeconds ?? Number.NaN;
+    this.serializer = new StandardRPCJsonSerializer(options);
+  }
+  prefix;
+  serializer;
+  retentionSeconds;
+  listenersMap = /* @__PURE__ */ new Map();
+  subscriptionPromiseMap = /* @__PURE__ */ new Map();
+  subscriptionsMap = /* @__PURE__ */ new Map();
+  // Upstash subscription objects
+  get isResumeEnabled() {
+    return Number.isFinite(this.retentionSeconds) && this.retentionSeconds > 0;
+  }
+  /**
+   * The exactness of the `XTRIM` command.
+   *
+   * @internal
+   */
+  xtrimExactness = "~";
+  /**
+   * Useful for measuring memory usage.
+   *
+   * @internal
+   *
+   */
+  get size() {
+    let size = 0;
+    for (const listeners of this.listenersMap) {
+      size += listeners[1].size || 1;
+    }
+    return size;
+  }
+  lastCleanupTimes = /* @__PURE__ */ new Map();
+  async publish(event, payload) {
+    const key = this.prefixKey(event);
+    const serialized = this.serializePayload(payload);
+    let id;
+    if (this.isResumeEnabled) {
+      const now = Date.now();
+      for (const [key2, lastCleanupTime] of this.lastCleanupTimes) {
+        if (lastCleanupTime + this.retentionSeconds * 1e3 < now) {
+          this.lastCleanupTimes.delete(key2);
+        }
+      }
+      if (!this.lastCleanupTimes.has(key)) {
+        this.lastCleanupTimes.set(key, now);
+        const results = await this.redis.multi().xadd(key, "*", { data: serialized }).xtrim(key, { strategy: "MINID", exactness: this.xtrimExactness, threshold: `${now - this.retentionSeconds * 1e3}-0` }).expire(key, this.retentionSeconds * 2).exec();
+        id = results[0];
+      } else {
+        const result = await this.redis.xadd(key, "*", { data: serialized });
+        id = result;
+      }
+    }
+    await this.redis.publish(key, { ...serialized, id });
+  }
+  async subscribeListener(event, originalListener, options) {
+    const key = this.prefixKey(event);
+    const lastEventId = options?.lastEventId;
+    let pendingPayloads = [];
+    const resumePayloadIds = /* @__PURE__ */ new Set();
+    const listener = (payload) => {
+      if (pendingPayloads) {
+        pendingPayloads.push(payload);
+        return;
+      }
+      const payloadId = getEventMeta(payload)?.id;
+      if (payloadId !== void 0 && resumePayloadIds.has(payloadId)) {
+        return;
+      }
+      originalListener(payload);
+    };
+    await this.subscriptionPromiseMap.get(key);
+    let subscription = this.subscriptionsMap.get(key);
+    if (!subscription) {
+      subscription = this.redis.subscribe(key);
+      subscription.on("message", (event2) => {
+        try {
+          const listeners2 = this.listenersMap.get(event2.channel);
+          if (listeners2) {
+            const { id, ...rest } = event2.message;
+            const payload = this.deserializePayload(id, rest);
+            for (const listener2 of listeners2) {
+              listener2(payload);
+            }
+          }
+        } catch {
+        }
+      });
+      let resolvePromise;
+      let rejectPromise;
+      const promise = new Promise((resolve, reject) => {
+        resolvePromise = resolve;
+        rejectPromise = reject;
+      });
+      subscription.on("error", (error) => {
+        rejectPromise(error);
+      });
+      subscription.on("subscribe", () => {
+        resolvePromise();
+      });
+      try {
+        this.subscriptionPromiseMap.set(key, promise);
+        await promise;
+        this.subscriptionsMap.set(key, subscription);
+      } finally {
+        this.subscriptionPromiseMap.delete(key);
+      }
+    }
+    let listeners = this.listenersMap.get(key);
+    if (!listeners) {
+      this.listenersMap.set(key, listeners = /* @__PURE__ */ new Set());
+    }
+    listeners.add(listener);
+    void (async () => {
+      try {
+        if (this.isResumeEnabled && typeof lastEventId === "string") {
+          const results = await this.redis.xread(key, lastEventId);
+          if (results && results[0]) {
+            const [_, items] = results[0];
+            for (const [id, fields] of items) {
+              const serialized = fields[1];
+              const payload = this.deserializePayload(id, serialized);
+              resumePayloadIds.add(id);
+              originalListener(payload);
+            }
+          }
+        }
+      } catch {
+      } finally {
+        const pending = pendingPayloads;
+        pendingPayloads = void 0;
+        for (const payload of pending) {
+          listener(payload);
+        }
+      }
+    })();
+    return async () => {
+      listeners.delete(listener);
+      if (listeners.size === 0) {
+        this.listenersMap.delete(key);
+        const subscription2 = this.subscriptionsMap.get(key);
+        if (subscription2) {
+          this.subscriptionsMap.delete(key);
+          await subscription2.unsubscribe();
+        }
+      }
+    };
+  }
+  prefixKey(key) {
+    return `${this.prefix}${key}`;
+  }
+  serializePayload(payload) {
+    const eventMeta = getEventMeta(payload);
+    const [json, meta] = this.serializer.serialize(payload);
+    return { json, meta, eventMeta };
+  }
+  deserializePayload(id, { json, meta, eventMeta }) {
+    return withEventMeta(
+      this.serializer.deserialize(json, meta),
+      id === void 0 ? { ...eventMeta } : { ...eventMeta, id }
+    );
+  }
+}
+
+export { UpstashRedisPublisher };

package/dist/index.d.mts

@@ -0,0 +1,76 @@
+import { AsyncIteratorClass } from '@orpc/shared';
+
+interface PublisherOptions {
+    /**
+     * Maximum number of events to buffer for async iterator 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;
+}
+interface PublisherSubscribeIteratorOptions extends PublisherSubscribeListenerOptions, PublisherOptions {
+    /**
+     * 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)
+     * })
+     *
+     * // 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 async iterator.
+     * Useful for `for await...of` loops with optional buffering and abort support.
+     *
+     * @example
+     * ```ts
+     * for await (const payload of publisher.subscribe('event', { signal })) {
+     *   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,76 @@
+import { AsyncIteratorClass } from '@orpc/shared';
+
+interface PublisherOptions {
+    /**
+     * Maximum number of events to buffer for async iterator 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;
+}
+interface PublisherSubscribeIteratorOptions extends PublisherSubscribeListenerOptions, PublisherOptions {
+    /**
+     * 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)
+     * })
+     *
+     * // 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 async iterator.
+     * Useful for `for await...of` loops with optional buffering and abort support.
+     *
+     * @example
+     * ```ts
+     * for await (const payload of publisher.subscribe('event', { signal })) {
+     *   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/experimental-publisher.BOyYBkgn.mjs';
+import '@orpc/shared';

package/dist/shared/experimental-publisher.BOyYBkgn.mjs

@@ -0,0 +1,57 @@
+import { AsyncIteratorClass } from '@orpc/shared';
+
+class Publisher {
+  maxBufferedEvents;
+  constructor(options = {}) {
+    this.maxBufferedEvents = options.maxBufferedEvents ?? 100;
+  }
+  subscribe(event, listenerOrOptions, listenerOptions) {
+    if (typeof listenerOrOptions === "function") {
+      return this.subscribeListener(event, listenerOrOptions, listenerOptions);
+    }
+    const signal = listenerOrOptions?.signal;
+    const maxBufferedEvents = listenerOrOptions?.maxBufferedEvents ?? this.maxBufferedEvents;
+    signal?.throwIfAborted();
+    const bufferedEvents = [];
+    const pullResolvers = [];
+    const unsubscribePromise = this.subscribe(event, (payload) => {
+      const resolver = pullResolvers.shift();
+      if (resolver) {
+        resolver[0]({ done: false, value: payload });
+      } else {
+        bufferedEvents.push(payload);
+        if (bufferedEvents.length > maxBufferedEvents) {
+          bufferedEvents.shift();
+        }
+      }
+    });
+    const abortListener = (event2) => {
+      pullResolvers.forEach((resolver) => resolver[1](event2.target.reason));
+      pullResolvers.length = 0;
+      bufferedEvents.length = 0;
+      unsubscribePromise.then((unsubscribe) => unsubscribe()).catch(() => {
+      });
+    };
+    signal?.addEventListener("abort", abortListener, { once: true });
+    return new AsyncIteratorClass(async () => {
+      await unsubscribePromise;
+      if (signal?.aborted) {
+        throw signal.reason;
+      }
+      if (bufferedEvents.length > 0) {
+        return { done: false, value: bufferedEvents.shift() };
+      }
+      return new Promise((resolve, reject) => {
+        pullResolvers.push([resolve, reject]);
+      });
+    }, async () => {
+      signal?.removeEventListener("abort", abortListener);
+      pullResolvers.forEach((resolver) => resolver[0]({ done: true, value: void 0 }));
+      pullResolvers.length = 0;
+      bufferedEvents.length = 0;
+      await unsubscribePromise.then((unsubscribe) => unsubscribe());
+    });
+  }
+}
+
+export { Publisher as P };

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@orpc/experimental-publisher",
+  "type": "module",
+  "version": "0.0.0",
+  "license": "MIT",
+  "homepage": "https://orpc.unnoq.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unnoq/orpc.git",
+    "directory": "packages/publisher"
+  },
+  "keywords": [
+    "unnoq",
+    "orpc"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./memory": {
+      "types": "./dist/adapters/memory.d.mts",
+      "import": "./dist/adapters/memory.mjs",
+      "default": "./dist/adapters/memory.mjs"
+    },
+    "./ioredis": {
+      "types": "./dist/adapters/ioredis.d.mts",
+      "import": "./dist/adapters/ioredis.mjs",
+      "default": "./dist/adapters/ioredis.mjs"
+    },
+    "./upstash-redis": {
+      "types": "./dist/adapters/upstash-redis.d.mts",
+      "import": "./dist/adapters/upstash-redis.mjs",
+      "default": "./dist/adapters/upstash-redis.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "@upstash/redis": ">=1.35.6",
+    "ioredis": ">=5.8.1"
+  },
+  "peerDependenciesMeta": {
+    "@upstash/redis": {
+      "optional": true
+    },
+    "ioredis": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@orpc/client": "1.9.4",
+    "@orpc/shared": "1.9.4",
+    "@orpc/standard-server": "1.9.4"
+  },
+  "devDependencies": {
+    "@upstash/redis": "^1.35.6",
+    "ioredis": "^5.8.1"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "build:watch": "pnpm run build --watch",
+    "type:check": "tsc -b"
+  }
+}