@orpc/server 1.4.5 → 1.5.0

package/dist/adapters/websocket/index.d.mts

@@ -8,10 +8,33 @@ import '@orpc/contract';
 import '@orpc/standard-server';
 import '@orpc/client/standard';
 
+type experimental_MinimalWebsocket = Pick<WebSocket, 'addEventListener' | 'send'>;
 declare class experimental_WebsocketHandler<T extends Context> {
-    private readonly standardHandler;
+    #private;
     constructor(standardHandler: StandardHandler<T>);
-    upgrade(ws: Pick<WebSocket, 'addEventListener' | 'send'>, ...rest: MaybeOptionalOptions<Omit<FriendlyStandardHandleOptions<T>, 'prefix'>>): void;
+    /**
+     * Upgrades a WebSocket to enable handling
+     *
+     * This attaches the necessary 'message' and 'close' listeners to the WebSocket
+     *
+     * @warning Do not use this method if you're using `.message()` or `.close()`
+     */
+    upgrade(ws: experimental_MinimalWebsocket, ...rest: MaybeOptionalOptions<Omit<FriendlyStandardHandleOptions<T>, 'prefix'>>): void;
+    /**
+     * Handles a single message received from a WebSocket.
+     *
+     * @warning Avoid calling this directly if `.upgrade()` is used.
+     *
+     * @param ws The WebSocket instance
+     * @param data The message payload, usually place in `event.data`
+     */
+    message(ws: experimental_MinimalWebsocket, data: string | ArrayBuffer | Blob, ...rest: MaybeOptionalOptions<Omit<FriendlyStandardHandleOptions<T>, 'prefix'>>): Promise<void>;
+    /**
+     * Closes the WebSocket peer and cleans up.
+     *
+     * @warning Avoid calling this directly if `.upgrade()` is used.
+     */
+    close(ws: experimental_MinimalWebsocket): void;
 }
 
 /**
@@ -25,3 +48,4 @@ declare class experimental_RPCHandler<T extends Context> extends experimental_We
 }
 
 export { experimental_RPCHandler, experimental_WebsocketHandler };
+export type { experimental_MinimalWebsocket };

package/dist/adapters/websocket/index.d.ts

@@ -8,10 +8,33 @@ import '@orpc/contract';
 import '@orpc/standard-server';
 import '@orpc/client/standard';
 
+type experimental_MinimalWebsocket = Pick<WebSocket, 'addEventListener' | 'send'>;
 declare class experimental_WebsocketHandler<T extends Context> {
-    private readonly standardHandler;
+    #private;
     constructor(standardHandler: StandardHandler<T>);
-    upgrade(ws: Pick<WebSocket, 'addEventListener' | 'send'>, ...rest: MaybeOptionalOptions<Omit<FriendlyStandardHandleOptions<T>, 'prefix'>>): void;
+    /**
+     * Upgrades a WebSocket to enable handling
+     *
+     * This attaches the necessary 'message' and 'close' listeners to the WebSocket
+     *
+     * @warning Do not use this method if you're using `.message()` or `.close()`
+     */
+    upgrade(ws: experimental_MinimalWebsocket, ...rest: MaybeOptionalOptions<Omit<FriendlyStandardHandleOptions<T>, 'prefix'>>): void;
+    /**
+     * Handles a single message received from a WebSocket.
+     *
+     * @warning Avoid calling this directly if `.upgrade()` is used.
+     *
+     * @param ws The WebSocket instance
+     * @param data The message payload, usually place in `event.data`
+     */
+    message(ws: experimental_MinimalWebsocket, data: string | ArrayBuffer | Blob, ...rest: MaybeOptionalOptions<Omit<FriendlyStandardHandleOptions<T>, 'prefix'>>): Promise<void>;
+    /**
+     * Closes the WebSocket peer and cleans up.
+     *
+     * @warning Avoid calling this directly if `.upgrade()` is used.
+     */
+    close(ws: experimental_MinimalWebsocket): void;
 }
 
 /**
@@ -25,3 +48,4 @@ declare class experimental_RPCHandler<T extends Context> extends experimental_We
 }
 
 export { experimental_RPCHandler, experimental_WebsocketHandler };
+export type { experimental_MinimalWebsocket };

package/dist/adapters/websocket/index.mjs

@@ -9,24 +9,54 @@ import '@orpc/client/standard';
 import '../../shared/server.DG7Tamti.mjs';
 
 class experimental_WebsocketHandler {
+  #peers = /* @__PURE__ */ new WeakMap();
+  #handler;
   constructor(standardHandler) {
-    this.standardHandler = standardHandler;
+    this.#handler = standardHandler;
   }
+  /**
+   * Upgrades a WebSocket to enable handling
+   *
+   * This attaches the necessary 'message' and 'close' listeners to the WebSocket
+   *
+   * @warning Do not use this method if you're using `.message()` or `.close()`
+   */
   upgrade(ws, ...rest) {
-    const peer = new ServerPeer(ws.send.bind(ws));
-    ws.addEventListener("message", async (event) => {
-      const message = event.data instanceof Blob ? await event.data.arrayBuffer() : event.data;
-      const [id, request] = await peer.message(message);
-      if (!request) {
-        return;
-      }
-      const options = resolveFriendlyStandardHandleOptions(resolveMaybeOptionalOptions(rest));
-      const { response } = await this.standardHandler.handle({ ...request, body: () => Promise.resolve(request.body) }, options);
-      await peer.response(id, response ?? { status: 404, headers: {}, body: "No procedure matched" });
-    });
-    ws.addEventListener("close", () => {
+    ws.addEventListener("message", (event) => this.message(ws, event.data, ...rest));
+    ws.addEventListener("close", () => this.close(ws));
+  }
+  /**
+   * Handles a single message received from a WebSocket.
+   *
+   * @warning Avoid calling this directly if `.upgrade()` is used.
+   *
+   * @param ws The WebSocket instance
+   * @param data The message payload, usually place in `event.data`
+   */
+  async message(ws, data, ...rest) {
+    let peer = this.#peers.get(ws);
+    if (!peer) {
+      this.#peers.set(ws, peer = new ServerPeer(ws.send.bind(ws)));
+    }
+    const message = data instanceof Blob ? await data.arrayBuffer() : data;
+    const [id, request] = await peer.message(message);
+    if (!request) {
+      return;
+    }
+    const options = resolveFriendlyStandardHandleOptions(resolveMaybeOptionalOptions(rest));
+    const { response } = await this.#handler.handle({ ...request, body: () => Promise.resolve(request.body) }, options);
+    await peer.response(id, response ?? { status: 404, headers: {}, body: "No procedure matched" });
+  }
+  /**
+   * Closes the WebSocket peer and cleans up.
+   *
+   * @warning Avoid calling this directly if `.upgrade()` is used.
+   */
+  close(ws) {
+    const peer = this.#peers.get(ws);
+    if (peer) {
       peer.close();
-    });
+    }
   }
 }
 

package/dist/hibernation/index.d.mts

@@ -0,0 +1,44 @@
+import { StandardRPCJsonSerializerOptions } from '@orpc/client/standard';
+import { a as StandardHandlerPlugin, b as StandardHandlerOptions } from '../shared/server.Dq8xr7PQ.mjs';
+import { experimental_HibernationEventIterator } from '@orpc/standard-server';
+export { experimental_HibernationEventIterator, experimental_HibernationEventIteratorCallback } from '@orpc/standard-server';
+import { C as Context, R as Router } from '../shared/server.DD2C4ujN.mjs';
+import '@orpc/client';
+import '@orpc/contract';
+import '@orpc/shared';
+
+interface experimental_EncodeHibernationRPCEventOptions extends StandardRPCJsonSerializerOptions {
+    /**
+     * The type of event, each type corresponds a different operation
+     *
+     * - 'message' = 'yield'
+     * - 'error' = 'throw'
+     * - 'done' = 'return'
+     *
+     * @default 'message'
+     */
+    event?: 'message' | 'error' | 'done';
+}
+/**
+ * Encodes a Hibernation RPC Event
+ *
+ * @see {@link https://orpc.unnoq.com/docs/plugins/hibernation Hibernation Plugin}
+ */
+declare function experimental_encodeHibernationRPCEvent(id: number, payload: unknown, options?: experimental_EncodeHibernationRPCEventOptions): string;
+
+interface experimental_HibernationContext {
+    iterator?: experimental_HibernationEventIterator<any>;
+}
+/**
+ * Enable Hibernation APIs
+ *
+ * @see {@link https://orpc.unnoq.com/docs/plugins/hibernation Hibernation Plugin}
+ */
+declare class experimental_HibernationPlugin<T extends Context> implements StandardHandlerPlugin<T> {
+    readonly HIBERNATION_CONTEXT_SYMBOL: symbol;
+    order: number;
+    init(options: StandardHandlerOptions<T>, _router: Router<any, T>): void;
+}
+
+export { experimental_HibernationPlugin, experimental_encodeHibernationRPCEvent };
+export type { experimental_EncodeHibernationRPCEventOptions, experimental_HibernationContext };

package/dist/hibernation/index.d.ts

@@ -0,0 +1,44 @@
+import { StandardRPCJsonSerializerOptions } from '@orpc/client/standard';
+import { a as StandardHandlerPlugin, b as StandardHandlerOptions } from '../shared/server.-ACo36I0.js';
+import { experimental_HibernationEventIterator } from '@orpc/standard-server';
+export { experimental_HibernationEventIterator, experimental_HibernationEventIteratorCallback } from '@orpc/standard-server';
+import { C as Context, R as Router } from '../shared/server.DD2C4ujN.js';
+import '@orpc/client';
+import '@orpc/contract';
+import '@orpc/shared';
+
+interface experimental_EncodeHibernationRPCEventOptions extends StandardRPCJsonSerializerOptions {
+    /**
+     * The type of event, each type corresponds a different operation
+     *
+     * - 'message' = 'yield'
+     * - 'error' = 'throw'
+     * - 'done' = 'return'
+     *
+     * @default 'message'
+     */
+    event?: 'message' | 'error' | 'done';
+}
+/**
+ * Encodes a Hibernation RPC Event
+ *
+ * @see {@link https://orpc.unnoq.com/docs/plugins/hibernation Hibernation Plugin}
+ */
+declare function experimental_encodeHibernationRPCEvent(id: number, payload: unknown, options?: experimental_EncodeHibernationRPCEventOptions): string;
+
+interface experimental_HibernationContext {
+    iterator?: experimental_HibernationEventIterator<any>;
+}
+/**
+ * Enable Hibernation APIs
+ *
+ * @see {@link https://orpc.unnoq.com/docs/plugins/hibernation Hibernation Plugin}
+ */
+declare class experimental_HibernationPlugin<T extends Context> implements StandardHandlerPlugin<T> {
+    readonly HIBERNATION_CONTEXT_SYMBOL: symbol;
+    order: number;
+    init(options: StandardHandlerOptions<T>, _router: Router<any, T>): void;
+}
+
+export { experimental_HibernationPlugin, experimental_encodeHibernationRPCEvent };
+export type { experimental_EncodeHibernationRPCEventOptions, experimental_HibernationContext };

package/dist/hibernation/index.mjs

@@ -0,0 +1,65 @@
+import { toORPCError } from '@orpc/client';
+import { StandardRPCJsonSerializer } from '@orpc/client/standard';
+import { stringifyJSON } from '@orpc/shared';
+import { getEventMeta, experimental_HibernationEventIterator } from '@orpc/standard-server';
+export { experimental_HibernationEventIterator } from '@orpc/standard-server';
+import { MessageType } from '@orpc/standard-server-peer';
+
+function experimental_encodeHibernationRPCEvent(id, payload, options = {}) {
+  const { event = "message", ...rest } = options;
+  const serializer = new StandardRPCJsonSerializer(rest);
+  const data = event === "error" ? toORPCError(payload).toJSON() : payload;
+  const [json, meta] = serializer.serialize(data);
+  return stringifyJSON({
+    i: id,
+    t: MessageType.EVENT_ITERATOR,
+    p: {
+      e: event,
+      d: { json, meta },
+      m: getEventMeta(payload)
+    }
+  });
+}
+
+class experimental_HibernationPlugin {
+  HIBERNATION_CONTEXT_SYMBOL = Symbol("HIBERNATION_CONTEXT");
+  order = 2e6;
+  // make sure execute after the batch plugin
+  init(options, _router) {
+    options.interceptors ??= [];
+    options.clientInterceptors ??= [];
+    options.interceptors.unshift(async (options2) => {
+      const hibernationContext = {};
+      const result = await options2.next({
+        ...options2,
+        context: {
+          [this.HIBERNATION_CONTEXT_SYMBOL]: hibernationContext,
+          ...options2.context
+        }
+      });
+      if (!result.matched || !hibernationContext.iterator) {
+        return result;
+      }
+      return {
+        ...result,
+        response: {
+          ...result.response,
+          body: hibernationContext.iterator
+        }
+      };
+    });
+    options.clientInterceptors.unshift(async (options2) => {
+      const hibernationContext = options2.context[this.HIBERNATION_CONTEXT_SYMBOL];
+      if (!hibernationContext) {
+        throw new TypeError("[HibernationPlugin] Hibernation context has been corrupted or modified by another plugin or interceptor");
+      }
+      const output = await options2.next();
+      if (output instanceof experimental_HibernationEventIterator) {
+        hibernationContext.iterator = output;
+      }
+      return output;
+    });
+  }
+}
+
+export { experimental_HibernationPlugin, experimental_encodeHibernationRPCEvent };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@orpc/server",
   "type": "module",
-  "version": "1.4.5",
+  "version": "1.5.0",
   "license": "MIT",
   "homepage": "https://orpc.unnoq.com",
   "repository": {
@@ -24,6 +24,11 @@
       "import": "./dist/plugins/index.mjs",
       "default": "./dist/plugins/index.mjs"
     },
+    "./hibernation": {
+      "types": "./dist/hibernation/index.d.mts",
+      "import": "./dist/hibernation/index.mjs",
+      "default": "./dist/hibernation/index.mjs"
+    },
     "./standard": {
       "types": "./dist/adapters/standard/index.d.mts",
       "import": "./dist/adapters/standard/index.mjs",
@@ -86,14 +91,14 @@
     }
   },
   "dependencies": {
-    "@orpc/client": "1.4.5",
-    "@orpc/contract": "1.4.5",
-    "@orpc/standard-server": "1.4.5",
-    "@orpc/standard-server-aws-lambda": "1.4.5",
-    "@orpc/shared": "1.4.5",
-    "@orpc/standard-server-fetch": "1.4.5",
-    "@orpc/standard-server-peer": "1.4.5",
-    "@orpc/standard-server-node": "1.4.5"
+    "@orpc/client": "1.5.0",
+    "@orpc/contract": "1.5.0",
+    "@orpc/shared": "1.5.0",
+    "@orpc/standard-server": "1.5.0",
+    "@orpc/standard-server-aws-lambda": "1.5.0",
+    "@orpc/standard-server-fetch": "1.5.0",
+    "@orpc/standard-server-node": "1.5.0",
+    "@orpc/standard-server-peer": "1.5.0"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1",