feat(server): stable hibernation apis (#854)

dinwwwh · web-flow · commit a320605bbe6c · 2025-08-11T16:17:09.000+07:00
&lt;!-- This is an auto-generated comment: release notes by coderabbit.ai
--&gt;

## Summary by CodeRabbit

- Refactor
- Stabilized Hibernation public API by removing experimental_ prefixes.
Use HibernationPlugin, HibernationEventIterator, and
encodeHibernationRPCEvent.
  - Updated type names accordingly; no behavioral changes.

- Documentation
- Updated guides and examples to reflect new Hibernation API names and
imports.

- Tests
  - Adjusted imports and spies to use the stable Hibernation API names.

- Chores
- Aligned internal references and instanceof checks with the new stable
Hibernation API.

&lt;!-- end of auto-generated comment: release notes by coderabbit.ai --&gt;
diff --git a/apps/content/docs/plugins/hibernation.md b/apps/content/docs/plugins/hibernation.md
@@ -10,7 +10,7 @@ The Hibernation Plugin helps you fully leverage Hibernation APIs, making it espe
 ## Setup
 
 ```ts
-import { experimental_HibernationPlugin as HibernationPlugin } from '@orpc/server/hibernation'
+import { HibernationPlugin } from '@orpc/server/hibernation'
 
 const handler = new RPCHandler(router, {
   plugins: [
@@ -26,7 +26,7 @@ The plugin provide `HibernationEventIterator` and `encodeHibernationRPCEvent` to
 1. Return an `HibernationEventIterator` from your handler
 
    ```ts
-   import { experimental_HibernationEventIterator as HibernationEventIterator } from '@orpc/server/hibernation'
+   import { HibernationEventIterator } from '@orpc/server/hibernation'
 
    export const onMessage = os.handler(async ({ context }) => {
      return new HibernationEventIterator<{ message: string }>((id) => {
@@ -39,7 +39,7 @@ The plugin provide `HibernationEventIterator` and `encodeHibernationRPCEvent` to
 2. Send events to clients with `encodeHibernationRPCEvent`
 
    ```ts
-   import { experimental_encodeHibernationRPCEvent as encodeHibernationRPCEvent } from '@orpc/server/hibernation'
+   import { encodeHibernationRPCEvent } from '@orpc/server/hibernation'
 
    export const sendMessage = os.handler(async ({ input, context }) => {
      const websockets = context.getWebSockets()
@@ -70,9 +70,9 @@ This example demonstrates how to set up a chat room using [Cloudflare Durable Ob
 ```ts [Durable Object]
 import { RPCHandler } from '@orpc/server/websocket'
 import {
-  experimental_encodeHibernationRPCEvent as encodeHibernationRPCEvent,
-  experimental_HibernationEventIterator as HibernationEventIterator,
-  experimental_HibernationPlugin as HibernationPlugin,
+  encodeHibernationRPCEvent,
+  HibernationEventIterator,
+  HibernationPlugin,
 } from '@orpc/server/hibernation'
 import { onError, os } from '@orpc/server'
 import { DurableObject } from 'cloudflare:workers'
diff --git a/packages/durable-event-iterator/src/durable-object/handler.test.ts b/packages/durable-event-iterator/src/durable-object/handler.test.ts
@@ -1,5 +1,5 @@
 import { call, createProcedureClient } from '@orpc/server'
-import { experimental_HibernationEventIterator as HibernationEventIterator } from '@orpc/server/hibernation'
+import { HibernationEventIterator } from '@orpc/server/hibernation'
 import { createCloudflareWebsocket, createDurableObjectState } from '../../tests/shared'
 import { DURABLE_EVENT_ITERATOR_HIBERNATION_ID_KEY, DURABLE_EVENT_ITERATOR_TOKEN_PAYLOAD_KEY } from './consts'
 import { DurableEventIteratorObjectEventStorage } from './event-storage'
diff --git a/packages/durable-event-iterator/src/durable-object/handler.ts b/packages/durable-event-iterator/src/durable-object/handler.ts
@@ -3,7 +3,7 @@ import type { DurableObject } from 'cloudflare:workers'
 import type { TokenAttachment } from '../object'
 import type { DurableEventIteratorObjectWebsocketAttachment, DurableEventIteratorObjectWebsocketManager } from './websocket-manager'
 import { implement, ORPCError } from '@orpc/server'
-import { experimental_HibernationEventIterator as HibernationEventIterator } from '@orpc/server/hibernation'
+import { HibernationEventIterator } from '@orpc/server/hibernation'
 import { get } from '@orpc/shared'
 import { durableEventIteratorContract } from '../client/contract'
 import { DURABLE_EVENT_ITERATOR_HIBERNATION_ID_KEY, DURABLE_EVENT_ITERATOR_TOKEN_PAYLOAD_KEY } from './consts'
diff --git a/packages/durable-event-iterator/src/durable-object/object.ts b/packages/durable-event-iterator/src/durable-object/object.ts
@@ -4,7 +4,7 @@ import type { DurableEventIteratorTokenPayload } from '../schemas'
 import type { DurableEventIteratorObjectEventStorageOptions } from './event-storage'
 import type { DurableEventIteratorObjectRouterContext } from './handler'
 import type { DurableEventIteratorObjectWebsocketAttachment, DurableEventIteratorObjectWebsocketManagerOptions } from './websocket-manager'
-import { experimental_HibernationPlugin as HibernationPlugin } from '@orpc/server/hibernation'
+import { HibernationPlugin } from '@orpc/server/hibernation'
 import { RPCHandler } from '@orpc/server/websocket'
 import { toArray } from '@orpc/shared'
 import { DurableObject } from 'cloudflare:workers'
diff --git a/packages/durable-event-iterator/src/durable-object/websocket-manager.test.ts b/packages/durable-event-iterator/src/durable-object/websocket-manager.test.ts
@@ -5,7 +5,7 @@ import { DURABLE_EVENT_ITERATOR_HIBERNATION_ID_KEY, DURABLE_EVENT_ITERATOR_TOKEN
 import { DurableEventIteratorObjectEventStorage } from './event-storage'
 import { DurableEventIteratorObjectWebsocketManager } from './websocket-manager'
 
-const encodeHibernationRPCEventSpy = vi.spyOn(Hibernation, 'experimental_encodeHibernationRPCEvent')
+const encodeHibernationRPCEventSpy = vi.spyOn(Hibernation, 'encodeHibernationRPCEvent')
 
 beforeEach(() => {
   vi.clearAllMocks()
diff --git a/packages/durable-event-iterator/src/durable-object/websocket-manager.ts b/packages/durable-event-iterator/src/durable-object/websocket-manager.ts
@@ -2,7 +2,7 @@ import type { StandardRPCJsonSerializerOptions } from '@orpc/client/standard'
 import type { TokenAttachment } from '../object'
 import type { DurableEventIteratorTokenPayload } from '../schemas'
 import type { DurableEventIteratorObjectEventStorage } from './event-storage'
-import { experimental_encodeHibernationRPCEvent as encodeHibernationRPCEvent } from '@orpc/server/hibernation'
+import { encodeHibernationRPCEvent } from '@orpc/server/hibernation'
 import { DURABLE_EVENT_ITERATOR_HIBERNATION_ID_KEY, DURABLE_EVENT_ITERATOR_TOKEN_PAYLOAD_KEY } from './consts'
 
 export interface DurableEventIteratorObjectWebsocketManagerOptions extends StandardRPCJsonSerializerOptions {
diff --git a/packages/server/src/hibernation/event-iterator.test.ts b/packages/server/src/hibernation/event-iterator.test.ts
@@ -3,7 +3,7 @@ import { ORPCError } from '@orpc/client'
 import { StandardRPCJsonSerializer, StandardRPCSerializer } from '@orpc/client/standard'
 import { withEventMeta } from '@orpc/standard-server'
 import { encodeResponseMessage, MessageType } from '@orpc/standard-server-peer'
-import { experimental_encodeHibernationRPCEvent as encodeHibernationRPCEvent } from './event-iterator'
+import { encodeHibernationRPCEvent } from './event-iterator'
 
 class Planet {
   constructor(public readonly name: string, public readonly diameter: number) {}
diff --git a/packages/server/src/hibernation/event-iterator.ts b/packages/server/src/hibernation/event-iterator.ts
@@ -5,7 +5,7 @@ import { stringifyJSON } from '@orpc/shared'
 import { getEventMeta } from '@orpc/standard-server'
 import { MessageType } from '@orpc/standard-server-peer'
 
-export interface experimental_EncodeHibernationRPCEventOptions extends StandardRPCJsonSerializerOptions {
+export interface EncodeHibernationRPCEventOptions extends StandardRPCJsonSerializerOptions {
   /**
    * The type of event, each type corresponds a different operation
    *
@@ -23,10 +23,10 @@ export interface experimental_EncodeHibernationRPCEventOptions extends StandardR
  *
  * @see {@link https://orpc.unnoq.com/docs/plugins/hibernation Hibernation Plugin}
  */
-export function experimental_encodeHibernationRPCEvent(
+export function encodeHibernationRPCEvent(
   id: string,
   payload: unknown,
-  options: experimental_EncodeHibernationRPCEventOptions = {},
+  options: EncodeHibernationRPCEventOptions = {},
 ): string {
   const { event = 'message', ...rest } = options
 
diff --git a/packages/server/src/hibernation/index.ts b/packages/server/src/hibernation/index.ts
@@ -1,3 +1,3 @@
 export * from './event-iterator'
 export * from './plugin'
-export { experimental_HibernationEventIterator, type experimental_HibernationEventIteratorCallback } from '@orpc/standard-server'
+export { HibernationEventIterator, type HibernationEventIteratorCallback } from '@orpc/standard-server'
diff --git a/packages/server/src/hibernation/plugin.test.ts b/packages/server/src/hibernation/plugin.test.ts
@@ -1,7 +1,7 @@
-import { experimental_HibernationEventIterator as HibernationEventIterator } from '@orpc/standard-server'
+import { HibernationEventIterator } from '@orpc/standard-server'
 import { StandardRPCHandler } from '../adapters/standard'
 import { os } from '../builder'
-import { experimental_HibernationPlugin as HibernationPlugin } from './plugin'
+import { HibernationPlugin } from './plugin'
 
 beforeEach(() => {
   vi.resetAllMocks()
diff --git a/packages/server/src/hibernation/plugin.ts b/packages/server/src/hibernation/plugin.ts
@@ -1,18 +1,18 @@
 import type { StandardHandlerOptions, StandardHandlerPlugin } from '../adapters/standard'
 import type { Context } from '../context'
 import type { Router } from '../router'
-import { experimental_HibernationEventIterator } from '@orpc/standard-server'
+import { HibernationEventIterator } from '@orpc/standard-server'
 
-export interface experimental_HibernationPluginContext {
-  iterator?: experimental_HibernationEventIterator<any>
+export interface HibernationPluginContext {
+  iterator?: HibernationEventIterator<any>
 }
 
 /**
  * Enable Hibernation APIs
  *
  * @see {@link https://orpc.unnoq.com/docs/plugins/hibernation Hibernation Plugin}
  */
-export class experimental_HibernationPlugin<T extends Context> implements StandardHandlerPlugin<T> {
+export class HibernationPlugin<T extends Context> implements StandardHandlerPlugin<T> {
   readonly CONTEXT_SYMBOL = Symbol('ORPC_HIBERNATION_CONTEXT')
 
   order = 2_000_000 // make sure execute after the batch plugin
@@ -22,13 +22,13 @@ export class experimental_HibernationPlugin<T extends Context> implements Standa
     options.clientInterceptors ??= []
 
     options.interceptors.unshift(async (options) => {
-      const hibernationContext: experimental_HibernationPluginContext = {}
+      const hibernationContext: HibernationPluginContext = {}
 
       const result = await options.next({
         ...options,
         context: {
-          [this.CONTEXT_SYMBOL]: hibernationContext,
           ...options.context,
+          [this.CONTEXT_SYMBOL]: hibernationContext,
         },
       })
 
@@ -46,15 +46,15 @@ export class experimental_HibernationPlugin<T extends Context> implements Standa
     })
 
     options.clientInterceptors.unshift(async (options) => {
-      const hibernationContext = options.context[this.CONTEXT_SYMBOL] as experimental_HibernationPluginContext | undefined
+      const hibernationContext = options.context[this.CONTEXT_SYMBOL] as HibernationPluginContext | undefined
 
       if (!hibernationContext) {
         throw new TypeError('[HibernationPlugin] Hibernation context has been corrupted or modified by another plugin or interceptor')
       }
 
       const output = await options.next()
 
-      if (output instanceof experimental_HibernationEventIterator) {
+      if (output instanceof HibernationEventIterator) {
         hibernationContext.iterator = output
       }
 
diff --git a/packages/server/src/procedure-client.ts b/packages/server/src/procedure-client.ts
@@ -8,7 +8,7 @@ import type { AnyProcedure, Procedure, ProcedureHandlerOptions } from './procedu
 import { ORPCError } from '@orpc/client'
 import { ValidationError } from '@orpc/contract'
 import { asyncIteratorWithSpan, intercept, isAsyncIteratorObject, resolveMaybeOptionalOptions, runWithSpan, toArray, value } from '@orpc/shared'
-import { experimental_HibernationEventIterator as HibernationEventIterator } from '@orpc/standard-server'
+import { HibernationEventIterator } from '@orpc/standard-server'
 import { mergeCurrentContext } from './context'
 import { createORPCErrorConstructorMap, validateORPCError } from './error'
 import { unlazy } from './lazy'
diff --git a/packages/standard-server-peer/src/server.test.ts b/packages/standard-server-peer/src/server.test.ts
@@ -1,5 +1,5 @@
 import { isAsyncIteratorObject } from '@orpc/shared'
-import { getEventMeta, experimental_HibernationEventIterator as HibernationEventIterator, withEventMeta } from '@orpc/standard-server'
+import { getEventMeta, HibernationEventIterator, withEventMeta } from '@orpc/standard-server'
 import { decodeResponseMessage, encodeRequestMessage, MessageType } from './codec'
 import { ServerPeer } from './server'
 
diff --git a/packages/standard-server-peer/src/server.ts b/packages/standard-server-peer/src/server.ts
@@ -3,7 +3,7 @@ import type { StandardRequest, StandardResponse } from '@orpc/standard-server'
 import type { EventIteratorPayload } from './codec'
 import type { EncodedMessage, EncodedMessageSendFn } from './types'
 import { AbortError, AsyncIdQueue, getGlobalOtelConfig, isAsyncIteratorObject, runWithSpan } from '@orpc/shared'
-import { experimental_HibernationEventIterator, isEventIteratorHeaders } from '@orpc/standard-server'
+import { HibernationEventIterator, isEventIteratorHeaders } from '@orpc/standard-server'
 import { decodeRequestMessage, encodeResponseMessage, MessageType } from './codec'
 import { resolveEventIterator, toEventIterator } from './event-iterator'
 
@@ -159,7 +159,7 @@ export class ServerPeer {
       await this.send(id, MessageType.RESPONSE, response)
 
       if (!signal.aborted && isAsyncIteratorObject(response.body)) {
-        if (response.body instanceof experimental_HibernationEventIterator) {
+        if (response.body instanceof HibernationEventIterator) {
           response.body.hibernationCallback?.(id)
         }
         else {
diff --git a/packages/standard-server/src/hibernation.test.ts b/packages/standard-server/src/hibernation.test.ts
@@ -1,4 +1,4 @@
-import { experimental_HibernationEventIterator as HibernationEventIterator } from './hibernation'
+import { HibernationEventIterator } from './hibernation'
 
 it('hibernationEventIterator', async () => {
   const callback = vi.fn()
diff --git a/packages/standard-server/src/hibernation.ts b/packages/standard-server/src/hibernation.ts
@@ -1,17 +1,17 @@
 import { AsyncIteratorClass } from '@orpc/shared'
 
-export interface experimental_HibernationEventIteratorCallback {
+export interface HibernationEventIteratorCallback {
   (id: string): void
 }
 
-export class experimental_HibernationEventIterator<T, TReturn = unknown, TNext = unknown> extends AsyncIteratorClass<T, TReturn, TNext> {
+export class HibernationEventIterator<T, TReturn = unknown, TNext = unknown> extends AsyncIteratorClass<T, TReturn, TNext> {
   /**
    * this property is not transferred to the client, so it should be optional for type safety
    */
-  public readonly hibernationCallback?: experimental_HibernationEventIteratorCallback
+  public readonly hibernationCallback?: HibernationEventIteratorCallback
 
   constructor(
-    hibernationCallback: experimental_HibernationEventIteratorCallback,
+    hibernationCallback: HibernationEventIteratorCallback,
   ) {
     super(async () => {
       throw new Error('Cannot iterate over hibernating iterator directly')
