@orpc/experimental-durable-iterator 0.0.0-next.01f0b7a

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-durable-iterator">
+    <img alt="weekly downloads" src="https://img.shields.io/npm/dw/%40orpc%2Fexperimental-durable-iterator?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-durable-iterator`
+
+[Durable Objects](https://developers.cloudflare.com/durable-objects/) integration for oRPC.
+
+## 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/client/index.d.mts

@@ -0,0 +1,69 @@
+export { C as ClientDurableIterator, b as ClientDurableIteratorRpc, a as ClientDurableIteratorRpcContext, c as CreateClientDurableIteratorOptions, d as createClientDurableIterator, g as getClientDurableIteratorToken } from '../shared/experimental-durable-iterator.DrenXxND.mjs';
+import { ClientContext } from '@orpc/client';
+import { StandardLinkInterceptorOptions, StandardLinkPlugin, StandardLinkOptions } from '@orpc/client/standard';
+import { RPCLinkOptions } from '@orpc/client/websocket';
+import { Value, Promisable } from '@orpc/shared';
+import { b as DurableIteratorTokenPayload } from '../shared/experimental-durable-iterator.DQjHfIr1.mjs';
+import '@orpc/client/plugins';
+import 'valibot';
+
+interface DurableIteratorLinkPluginContext {
+    isDurableIteratorResponse?: boolean;
+}
+interface DurableIteratorLinkPluginOptions<T extends ClientContext> extends Omit<RPCLinkOptions<object>, 'websocket'> {
+    /**
+     * The WebSocket URL to connect to the Durable Iterator Object.
+     */
+    url: Value<Promisable<string | URL>, [tokenPayload: DurableIteratorTokenPayload, options: StandardLinkInterceptorOptions<T>]>;
+    /**
+     * Generates a unique, unguessable websocket identifier.
+     *
+     * This ID is attached to the WebSocket connection so the server can
+     * recognize the same client across reconnects. It is called **once per client**
+     *
+     * @remarks
+     * - Use a strong random generator to avoid collisions or predictable IDs.
+     *
+     * @default (() => crypto.randomUUID())
+     */
+    createId?: (tokenPayload: DurableIteratorTokenPayload, options: StandardLinkInterceptorOptions<T>) => Promisable<string>;
+    /**
+     * Refresh the token this many seconds before it expires.
+     *
+     * @remarks
+     * - Pick a value larger than the expected token refresh time, network latency, and retry on failure
+     *   to ensure a seamless refresh without reconnecting the WebSocket.
+     * - 300 seconds (5 minutes) is typically enough; 600 seconds (10 minutes) is safer
+     * - Use a infinite value to disable refreshing
+     *
+     * @default NaN (disabled)
+     */
+    refreshTokenBeforeExpireInSeconds?: Value<Promisable<number>, [tokenPayload: DurableIteratorTokenPayload, options: StandardLinkInterceptorOptions<T>]>;
+    /**
+     * Minimum delay between token refresh attempts.
+     *
+     * @default 2 (seconds)
+     */
+    refreshTokenDelayInSeconds?: Value<Promisable<number>, [tokenPayload: DurableIteratorTokenPayload, options: StandardLinkInterceptorOptions<T>]>;
+}
+/**
+ * @see {@link https://orpc.unnoq.com/docs/integrations/durable-iterator Durable Iterator Integration}
+ */
+declare class DurableIteratorLinkPlugin<T extends ClientContext> implements StandardLinkPlugin<T> {
+    readonly CONTEXT_SYMBOL: symbol;
+    /**
+     * run before (modify result after) retry plugin because it can break the special iterator
+     */
+    order: number;
+    private readonly url;
+    private readonly createId;
+    private readonly refreshTokenBeforeExpireInSeconds;
+    private readonly refreshTokenDelayInSeconds;
+    private readonly linkOptions;
+    constructor({ url, refreshTokenBeforeExpireInSeconds, refreshTokenDelayInSeconds, ...options }: DurableIteratorLinkPluginOptions<T>);
+    init(options: StandardLinkOptions<T>): void;
+    private validateToken;
+}
+
+export { DurableIteratorLinkPlugin };
+export type { DurableIteratorLinkPluginContext, DurableIteratorLinkPluginOptions };

package/dist/client/index.d.ts

@@ -0,0 +1,69 @@
+export { C as ClientDurableIterator, b as ClientDurableIteratorRpc, a as ClientDurableIteratorRpcContext, c as CreateClientDurableIteratorOptions, d as createClientDurableIterator, g as getClientDurableIteratorToken } from '../shared/experimental-durable-iterator.C6YPLbUA.js';
+import { ClientContext } from '@orpc/client';
+import { StandardLinkInterceptorOptions, StandardLinkPlugin, StandardLinkOptions } from '@orpc/client/standard';
+import { RPCLinkOptions } from '@orpc/client/websocket';
+import { Value, Promisable } from '@orpc/shared';
+import { b as DurableIteratorTokenPayload } from '../shared/experimental-durable-iterator.DQjHfIr1.js';
+import '@orpc/client/plugins';
+import 'valibot';
+
+interface DurableIteratorLinkPluginContext {
+    isDurableIteratorResponse?: boolean;
+}
+interface DurableIteratorLinkPluginOptions<T extends ClientContext> extends Omit<RPCLinkOptions<object>, 'websocket'> {
+    /**
+     * The WebSocket URL to connect to the Durable Iterator Object.
+     */
+    url: Value<Promisable<string | URL>, [tokenPayload: DurableIteratorTokenPayload, options: StandardLinkInterceptorOptions<T>]>;
+    /**
+     * Generates a unique, unguessable websocket identifier.
+     *
+     * This ID is attached to the WebSocket connection so the server can
+     * recognize the same client across reconnects. It is called **once per client**
+     *
+     * @remarks
+     * - Use a strong random generator to avoid collisions or predictable IDs.
+     *
+     * @default (() => crypto.randomUUID())
+     */
+    createId?: (tokenPayload: DurableIteratorTokenPayload, options: StandardLinkInterceptorOptions<T>) => Promisable<string>;
+    /**
+     * Refresh the token this many seconds before it expires.
+     *
+     * @remarks
+     * - Pick a value larger than the expected token refresh time, network latency, and retry on failure
+     *   to ensure a seamless refresh without reconnecting the WebSocket.
+     * - 300 seconds (5 minutes) is typically enough; 600 seconds (10 minutes) is safer
+     * - Use a infinite value to disable refreshing
+     *
+     * @default NaN (disabled)
+     */
+    refreshTokenBeforeExpireInSeconds?: Value<Promisable<number>, [tokenPayload: DurableIteratorTokenPayload, options: StandardLinkInterceptorOptions<T>]>;
+    /**
+     * Minimum delay between token refresh attempts.
+     *
+     * @default 2 (seconds)
+     */
+    refreshTokenDelayInSeconds?: Value<Promisable<number>, [tokenPayload: DurableIteratorTokenPayload, options: StandardLinkInterceptorOptions<T>]>;
+}
+/**
+ * @see {@link https://orpc.unnoq.com/docs/integrations/durable-iterator Durable Iterator Integration}
+ */
+declare class DurableIteratorLinkPlugin<T extends ClientContext> implements StandardLinkPlugin<T> {
+    readonly CONTEXT_SYMBOL: symbol;
+    /**
+     * run before (modify result after) retry plugin because it can break the special iterator
+     */
+    order: number;
+    private readonly url;
+    private readonly createId;
+    private readonly refreshTokenBeforeExpireInSeconds;
+    private readonly refreshTokenDelayInSeconds;
+    private readonly linkOptions;
+    constructor({ url, refreshTokenBeforeExpireInSeconds, refreshTokenDelayInSeconds, ...options }: DurableIteratorLinkPluginOptions<T>);
+    init(options: StandardLinkOptions<T>): void;
+    private validateToken;
+}
+
+export { DurableIteratorLinkPlugin };
+export type { DurableIteratorLinkPluginContext, DurableIteratorLinkPluginOptions };

package/dist/client/index.mjs

@@ -0,0 +1,160 @@
+import { c as createClientDurableIterator } from '../shared/experimental-durable-iterator.B3M42lLK.mjs';
+export { g as getClientDurableIteratorToken } from '../shared/experimental-durable-iterator.B3M42lLK.mjs';
+import { createORPCClient } from '@orpc/client';
+import { ClientRetryPlugin } from '@orpc/client/plugins';
+import { RPCLink } from '@orpc/client/websocket';
+import { fallback, value, toArray, AsyncIteratorClass, retry, stringifyJSON } from '@orpc/shared';
+import { WebSocket } from 'partysocket';
+import { d as DURABLE_ITERATOR_ID_PARAM, c as DURABLE_ITERATOR_TOKEN_PARAM, D as DurableIteratorError, b as DURABLE_ITERATOR_PLUGIN_HEADER_KEY, a as DURABLE_ITERATOR_PLUGIN_HEADER_VALUE, p as parseDurableIteratorToken } from '../shared/experimental-durable-iterator.DZOLL3sf.mjs';
+import '@orpc/server/helpers';
+import 'valibot';
+
+class DurableIteratorLinkPlugin {
+  CONTEXT_SYMBOL = Symbol("ORPC_DURABLE_ITERATOR_LINK_PLUGIN_CONTEXT");
+  /**
+   * run before (modify result after) retry plugin because it can break the special iterator
+   */
+  order = 15e5;
+  url;
+  createId;
+  refreshTokenBeforeExpireInSeconds;
+  refreshTokenDelayInSeconds;
+  linkOptions;
+  constructor({ url, refreshTokenBeforeExpireInSeconds, refreshTokenDelayInSeconds, ...options }) {
+    this.url = url;
+    this.createId = fallback(options.createId, () => crypto.randomUUID());
+    this.refreshTokenBeforeExpireInSeconds = fallback(refreshTokenBeforeExpireInSeconds, Number.NaN);
+    this.refreshTokenDelayInSeconds = fallback(refreshTokenDelayInSeconds, 2);
+    this.linkOptions = options;
+  }
+  init(options) {
+    options.interceptors ??= [];
+    options.clientInterceptors ??= [];
+    options.interceptors.push(async (options2) => {
+      const pluginContext = {};
+      const next = () => options2.next({
+        ...options2,
+        context: {
+          [this.CONTEXT_SYMBOL]: pluginContext,
+          ...options2.context
+        }
+      });
+      const output = await next();
+      if (!pluginContext.isDurableIteratorResponse) {
+        return output;
+      }
+      options2?.signal?.throwIfAborted();
+      let isFinished = false;
+      let tokenAndPayload = this.validateToken(output, options2.path);
+      const id = await this.createId(tokenAndPayload.payload, options2);
+      const websocket = new WebSocket(async () => {
+        const url = new URL(await value(this.url, tokenAndPayload.payload, options2));
+        url.searchParams.append(DURABLE_ITERATOR_ID_PARAM, id);
+        url.searchParams.append(DURABLE_ITERATOR_TOKEN_PARAM, tokenAndPayload.token);
+        return url.toString();
+      });
+      const durableClient = createORPCClient(new RPCLink({
+        ...this.linkOptions,
+        websocket,
+        plugins: [
+          ...toArray(this.linkOptions.plugins),
+          new ClientRetryPlugin()
+        ]
+      }));
+      let refreshTokenBeforeExpireTimeoutId;
+      const refreshTokenBeforeExpire = async () => {
+        const beforeSeconds = await value(this.refreshTokenBeforeExpireInSeconds, tokenAndPayload.payload, options2);
+        const delayMilliseconds = await value(this.refreshTokenDelayInSeconds, tokenAndPayload.payload, options2) * 1e3;
+        if (isFinished || !Number.isFinite(beforeSeconds)) {
+          return;
+        }
+        refreshTokenBeforeExpireTimeoutId = setTimeout(
+          async () => {
+            const newTokenAndPayload = await retry({ times: Number.POSITIVE_INFINITY, delay: delayMilliseconds }, async (exit) => {
+              try {
+                const output2 = await next();
+                return this.validateToken(output2, options2.path);
+              } catch (err) {
+                if (isFinished) {
+                  exit(err);
+                }
+                throw err;
+              }
+            });
+            const canProactivelyUpdateToken = newTokenAndPayload.payload.chn === tokenAndPayload.payload.chn && stringifyJSON(newTokenAndPayload.payload.tags) === stringifyJSON(tokenAndPayload.payload.tags);
+            tokenAndPayload = newTokenAndPayload;
+            await refreshTokenBeforeExpire();
+            if (canProactivelyUpdateToken) {
+              await durableClient.updateToken({ token: tokenAndPayload.token });
+            } else {
+              websocket.reconnect();
+            }
+          },
+          Math.max(
+            refreshTokenBeforeExpireTimeoutId === void 0 ? 0 : delayMilliseconds,
+            (tokenAndPayload.payload.exp - beforeSeconds) * 1e3 - Date.now()
+          )
+        );
+      };
+      refreshTokenBeforeExpire();
+      const closeConnection = () => {
+        isFinished = true;
+        clearTimeout(refreshTokenBeforeExpireTimeoutId);
+        websocket.close();
+      };
+      options2?.signal?.addEventListener("abort", closeConnection, { once: true });
+      const iterator_ = await durableClient.subscribe(void 0, {
+        context: {
+          retry: Number.POSITIVE_INFINITY
+        },
+        lastEventId: options2.lastEventId
+        // we can use user provided lastEventId for initial connection
+      });
+      const cancelableIterator = new AsyncIteratorClass(
+        () => iterator_.next(),
+        async () => {
+          closeConnection();
+          options2.signal?.removeEventListener("abort", closeConnection);
+        }
+      );
+      const link = {
+        call(path, input, options3) {
+          return durableClient.call({
+            path,
+            // safely cast, server will validate later
+            input
+          }, options3);
+        }
+      };
+      const durableIterator = createClientDurableIterator(
+        cancelableIterator,
+        link,
+        {
+          getToken: () => tokenAndPayload.token
+        }
+      );
+      return durableIterator;
+    });
+    options.clientInterceptors.push(async (options2) => {
+      const pluginContext = options2.context[this.CONTEXT_SYMBOL];
+      if (!pluginContext) {
+        throw new DurableIteratorError("Plugin context has been corrupted or modified by another plugin or interceptor");
+      }
+      const response = await options2.next();
+      pluginContext.isDurableIteratorResponse = response.headers[DURABLE_ITERATOR_PLUGIN_HEADER_KEY] === DURABLE_ITERATOR_PLUGIN_HEADER_VALUE;
+      return response;
+    });
+  }
+  validateToken(token, path) {
+    if (typeof token !== "string") {
+      throw new DurableIteratorError(`Expected valid token for procedure ${path.join(".")}`);
+    }
+    try {
+      return { token, payload: parseDurableIteratorToken(token) };
+    } catch (error) {
+      throw new DurableIteratorError(`Expected valid token for procedure ${path.join(".")}`, { cause: error });
+    }
+  }
+}
+
+export { DurableIteratorLinkPlugin, createClientDurableIterator };