feat(server): event publisher (#603)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **New Features**
- Introduced a new event publishing and subscription system, enabling
real-time event broadcasting and consumption with support for both
callback listeners and async iterators.
- Added options for event buffering and cancellation when consuming
events asynchronously.

- **Documentation**
- Extended documentation with a new section detailing usage patterns and
code examples for the event publishing system.

- **Tests**
- Added comprehensive tests to verify type safety and runtime behavior
of the new event publishing system.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: dinwwwh

apps/content/docs/event-iterator.md

@@ -105,3 +105,54 @@ const example = os
     }
   })
 ```
+
+## Event Publisher
+
+oRPC includes a built-in `EventPublisher` for real-time features like chat, notifications, or live updates. It supports broadcasting and subscribing to named events.
+
+::: code-group
+
+```ts [Static Events]
+import { EventPublisher } from '@orpc/server'
+
+const publisher = new EventPublisher<{
+  'something-updated': {
+    id: string
+  }
+}>()
+
+const livePlanet = os
+  .handler(async function* ({ input, signal }) {
+    for await (const payload of publisher.subscribe('something-updated', { signal })) { // [!code highlight]
+      // handle payload here and yield something to client
+    }
+  })
+
+const update = os
+  .input(z.object({ id: z.string() }))
+  .handler(async function* ({ input }) {
+    publisher.publish('something-updated', { id: input.id }) // [!code highlight]
+  })
+```
+
+```ts [Dynamic Events]
+import { EventPublisher } from '@orpc/server'
+
+const publisher = new EventPublisher<Record<string, { message: string }>>()
+
+const onMessage = os
+  .input(z.object({ channel: z.string() }))
+  .handler(async function* ({ input, signal }) {
+    for await (const payload of publisher.subscribe(input.channel, { signal })) { // [!code highlight]
+      yield payload.message
+    }
+  })
+
+const sendMessage = os
+  .input(z.object({ channel: z.string(), message: z.string() }))
+  .handler(async function* ({ input }) {
+    publisher.publish(input.channel, { message: input.message }) // [!code highlight]
+  })
+```
+
+:::

packages/server/src/index.ts

@@ -39,6 +39,6 @@ export type {
   Schema,
 } from '@orpc/contract'
 export type { IntersectPick } from '@orpc/shared'
-export { onError, onFinish, onStart, onSuccess } from '@orpc/shared'
-export type { Registry, ThrowableError } from '@orpc/shared'
+export { EventPublisher, onError, onFinish, onStart, onSuccess } from '@orpc/shared'
+export type { EventPublisherOptions, EventPublisherSubscribeIteratorOptions, Registry, ThrowableError } from '@orpc/shared'
 export { getEventMeta, withEventMeta } from '@orpc/standard-server'

packages/shared/src/event-publisher.test-d.ts

@@ -0,0 +1,75 @@
+import { EventPublisher } from './event-publisher'
+
+describe('eventPublisher', () => {
+  it('key-value types', async () => {
+    const pub = new EventPublisher<{
+      'event-1': {
+        id: string
+      }
+      'event-2': {
+        name: string
+      }
+    }>()
+
+    pub.publish('event-1', { id: '1' })
+    pub.publish('event-2', { name: '1' })
+    // @ts-expect-error - wrong event
+    pub.publish('event-3', { name: '1' })
+    // @ts-expect-error - wrong payload
+    pub.publish('event-2', { name: 123 })
+
+    pub.subscribe('event-1', (payload) => {
+      expectTypeOf(payload).toEqualTypeOf<{
+        id: string
+      }>()
+    })
+
+    pub.subscribe('event-2', (payload) => {
+      expectTypeOf(payload).toEqualTypeOf<{
+        name: string
+      }>()
+    })
+
+    // @ts-expect-error - wrong event
+    pub.subscribe('event-3', (payload) => {})
+
+    for await (const payload of pub.subscribe('event-1')) {
+      expectTypeOf(payload).toEqualTypeOf<{
+        id: string
+      }>()
+    }
+
+    for await (const payload of pub.subscribe('event-2')) {
+      expectTypeOf(payload).toEqualTypeOf<{
+        name: string
+      }>()
+    }
+
+    // @ts-expect-error - wrong event
+    for await (const payload of pub.subscribe('event-3')) {
+      // empty
+    }
+  })
+
+  it('record types', async () => {
+    const pub = new EventPublisher<Record<string, { id: string }>>()
+
+    pub.publish('event-1', { id: '1' })
+    pub.publish('event-2', { id: '1' })
+    pub.publish('event-100', { id: '1' })
+    // @ts-expect-error - wrong event
+    pub.publish('event-100', { id: 123 })
+
+    pub.subscribe('event-933', (payload) => {
+      expectTypeOf(payload).toEqualTypeOf<{
+        id: string
+      }>()
+    })
+
+    for await (const payload of pub.subscribe('event-3439')) {
+      expectTypeOf(payload).toEqualTypeOf<{
+        id: string
+      }>()
+    }
+  })
+})