feat(openapi): custom openapi json serializer (#246)

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

- **New Features**
- Enhanced the JSON serialization engine to support custom serialization
strategies via configurable options.
- Updated API handlers to accept these serializer options, allowing for
more flexible data handling.
- Added a new documentation section for "OpenAPI JSON Serializer" to
guide users on customization.
- Expanded the list of supported data types for both `OpenAPIHandler`
and `RPCHandler` to include **Record (object)** and **Array**.

- **Tests**
- Added a comprehensive suite of unit tests covering built-in and custom
data types, including edge case handling (e.g., `undefined` values), to
ensure robust serialization behavior.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: dinwwwh

apps/content/.vitepress/config.ts

@@ -182,6 +182,13 @@ export default defineConfig({
             { text: 'OpenAPI Link', link: '/docs/openapi/client/openapi-link' },
           ],
         },
+        {
+          text: 'Advanced',
+          collapsed: true,
+          items: [
+            { text: 'OpenAPI JSON Serializer', link: '/docs/openapi/advanced/openapi-json-serializer' },
+          ],
+        },
       ],
       '/examples/': [
         { text: 'OpenAI Streaming', link: '/examples/openai-streaming' },

apps/content/docs/openapi/advanced/openapi-json-serializer.md

@@ -0,0 +1,63 @@
+---
+title: OpenAPI JSON Serializer
+description: Extend or override the standard OpenAPI JSON serializer.
+---
+
+# OpenAPI JSON Serializer
+
+This serializer processes JSON payloads for the [OpenAPIHandler](/docs/openapi/openapi-handler) and supports [native data types](/docs/openapi/openapi-handler#supported-data-types).
+
+## Extending Native Data Types
+
+Customize serialization by creating your own `StandardOpenAPICustomJsonSerializer` and adding it to the `customJsonSerializers` option.
+
+1. **Define Your Custom Serializer**
+
+   ```ts twoslash
+   import type { StandardOpenAPICustomJsonSerializer } from '@orpc/openapi-client/standard'
+
+   export class User {
+     constructor(
+       public readonly id: string,
+       public readonly name: string,
+       public readonly email: string,
+       public readonly age: number,
+     ) {}
+
+     toJSON() {
+       return {
+         id: this.id,
+         name: this.name,
+         email: this.email,
+         age: this.age,
+       }
+     }
+   }
+
+   export const userSerializer: StandardOpenAPICustomJsonSerializer = {
+     condition: data => data instanceof User,
+     serialize: data => data.toJSON(),
+   }
+   ```
+
+2. **Use Your Custom Serializer**
+
+   ```ts twoslash
+   import type { StandardOpenAPICustomJsonSerializer } from '@orpc/openapi-client/standard'
+   import { OpenAPIHandler } from '@orpc/openapi/fetch'
+   import { OpenAPIGenerator } from '@orpc/openapi'
+   declare const router: Record<never, never>
+   declare const userSerializer: StandardOpenAPICustomJsonSerializer
+   // ---cut---
+   const handler = new OpenAPIHandler(router, {
+     customJsonSerializers: [userSerializer],
+   })
+
+   const generator = new OpenAPIGenerator({
+     customJsonSerializers: [userSerializer],
+   })
+   ```
+
+   ::: info
+   It is recommended to add custom serializers to the `OpenAPIGenerator` for consistent serialization in the OpenAPI document.
+   :::

apps/content/docs/openapi/openapi-handler.md

@@ -20,6 +20,8 @@ The `OpenAPIHandler` enables communication with clients over RESTful APIs, adher
 - **BigInt** (`BigInt` → `string`)
 - **RegExp** (`RegExp` → `string`)
 - **URL** (`URL` → `string`)
+- **Record (object)**
+- **Array**
 - **Set** (`Set` → `array`)
 - **Map** (`Map` → `array`)
 - **Blob** (unsupported in `AsyncIteratorObject`)
@@ -30,6 +32,10 @@ The `OpenAPIHandler` enables communication with clients over RESTful APIs, adher
 If a payload contains `Blob` or `File` outside the root level, it must use `multipart/form-data`. In such cases, oRPC applies [Bracket Notation](/docs/openapi/bracket-notation) and converts other types to strings (exclude `null` and `undefined` will not be represented).
 :::
 
+:::tip
+You can extend the list of supported types by [creating a custom serializer](/docs/openapi/advanced/openapi-json-serializer#extending-native-data-types).
+:::
+
 ## Installation
 
 ::: code-group

apps/content/docs/rpc-handler.md

@@ -24,12 +24,18 @@ The `RPCHandler` enables communication with clients over oRPC's proprietary [RPC
 - **BigInt**
 - **RegExp**
 - **URL**
+- **Record (object)**
+- **Array**
 - **Set**
 - **Map**
 - **Blob** (unsupported in `AsyncIteratorObject`)
 - **File** (unsupported in `AsyncIteratorObject`)
 - **AsyncIteratorObject** (only at the root level; powers the [Event Iterator](/docs/event-iterator))
 
+:::tip
+You can extend the list of supported types by [creating a custom serializer](/docs/advanced/rpc-json-serializer#extending-native-data-types).
+:::
+
 ## Setup and Integration
 
 ```ts

packages/openapi-client/src/adapters/standard/openapi-json-serializer.test.ts

@@ -0,0 +1,249 @@
+import { StandardOpenAPIJsonSerializer } from './openapi-json-serializer'
+
+type TestCase = {
+  data: unknown
+  expected?: unknown
+}
+
+enum Test {
+  A = 1,
+  B = 2,
+  C = 'C',
+  D = 'D',
+}
+
+const builtInCases: TestCase[] = [
+  {
+    data: Test.B,
+    expected: Test.B,
+  },
+  {
+    data: 'some-string',
+    expected: 'some-string',
+  },
+  {
+    data: 123,
+    expected: 123,
+  },
+  {
+    data: Number.NaN,
+    expected: null,
+  },
+  {
+    data: true,
+    expected: true,
+  },
+  {
+    data: false,
+    expected: false,
+  },
+  {
+    data: null,
+    expected: null,
+  },
+  //   {
+  //     data: undefined,
+  //     expected: expect.toSatisfy(v => v === null || v === undefined), CANNOT ASSERT UNDEFINED IN OBJECT?
+  //   },
+  {
+    data: new Date('2023-01-01'),
+    expected: new Date('2023-01-01').toISOString(),
+  },
+  {
+    data: new Date('Invalid'),
+    expected: null,
+  },
+  {
+    data: 99999999999999999999999999999n,
+    expected: '99999999999999999999999999999',
+  },
+  {
+    data: /npa|npb/,
+    expected: '/npa|npb/',
+  },
+  {
+    data: /uic/gi,
+    expected: '/uic/gi',
+  },
+  {
+    data: new URL('https://unnoq.com'),
+    expected: new URL('https://unnoq.com').href,
+  },
+  {
+    data: { a: 1, b: 2, c: 3 },
+    expected: { a: 1, b: 2, c: 3 },
+  },
+  {
+    data: [1, 2, 3],
+    expected: [1, 2, 3],
+  },
+  {
+    data: new Map([[1, 2], [3, 4]]),
+    expected: [[1, 2], [3, 4]],
+  },
+  {
+    data: new Set([1, 2, 3]),
+    expected: [1, 2, 3],
+  },
+  {
+    data: new Blob(['blob'], { type: 'text/plain' }),
+    expected: expect.toSatisfy((file: any) => {
+      expect(file).toBeInstanceOf(Blob)
+      expect(file.type).toBe('text/plain')
+      expect(file.size).toBe(4)
+
+      return true
+    }),
+  },
+  {
+    data: new File(['"name"'], 'file.json', { type: 'application/json' }),
+    expected: expect.toSatisfy((file: any) => {
+      expect(file).toBeInstanceOf(File)
+      expect(file.name).toBe('file.json')
+      expect(file.type).toBe('application/json')
+      expect(file.size).toBe(6)
+
+      return true
+    }),
+  },
+]
+
+class Person {
+  constructor(
+    public name: string,
+    public date: Date,
+  ) { }
+
+  toJSON() {
+    return {
+      name: this.name,
+      date: this.date,
+    }
+  }
+}
+
+class Person2 {
+  constructor(
+    public name: string,
+    public data: any,
+  ) { }
+
+  toJSON() {
+    return {
+      name: this.name,
+      data: this.data,
+    }
+  }
+}
+
+const customSupportedDataTypes: TestCase[] = [
+  {
+    data: new Person('unnoq', new Date('2023-01-01')),
+    expected: { name: 'unnoq', date: '2023-01-01T00:00:00.000Z' },
+  },
+  {
+    data: new Person2('unnoq - 2', [{ nested: new Date('2023-01-02') }, /uic/gi]),
+    expected: { name: 'unnoq - 2', data: [{ nested: '2023-01-02T00:00:00.000Z' }, '/uic/gi'] },
+  },
+]
+
+describe.each<TestCase>([
+  ...builtInCases,
+  ...customSupportedDataTypes,
+])('serialize %p', ({ data, expected = data }) => {
+  const serializer = new StandardOpenAPIJsonSerializer({
+    customJsonSerializers: [
+      {
+        condition: data => data instanceof Person,
+        serialize: data => data.toJSON(),
+      },
+      {
+        condition: data => data instanceof Person2,
+        serialize: data => data.toJSON(),
+      },
+    ],
+  })
+
+  it('flat', () => {
+    const [json, hasBlob] = serializer.serialize(data)
+
+    expect(json).toEqual(expected)
+    expect(hasBlob).toBe(data instanceof Blob)
+  })
+
+  it('object', () => {
+    const [json, hasBlob] = serializer.serialize({ value: data })
+
+    expect(json).toEqual({ value: expected })
+    expect(hasBlob).toBe(data instanceof Blob)
+  })
+
+  it('array', () => {
+    const [json, hasBlob] = serializer.serialize([data])
+
+    expect(json).toEqual([expected])
+    expect(hasBlob).toBe(data instanceof Blob)
+  })
+
+  it('set', () => {
+    const [json, hasBlob] = serializer.serialize(new Set([data]))
+
+    expect(json).toEqual([expected])
+    expect(hasBlob).toBe(data instanceof Blob)
+  })
+
+  it('map', () => {
+    const [json, hasBlob] = serializer.serialize(new Map([[data, data]]))
+
+    expect(json).toEqual([[expected, expected]])
+    expect(hasBlob).toBe(data instanceof Blob)
+  })
+
+  it('complex', () => {
+    const [json, hasBlob] = serializer.serialize({
+      'date': new Date('2023-01-01'),
+      'regexp': /uic/gi,
+      'url': new URL('https://unnoq.com'),
+      '!@#$%^^&()[]>?<~_<:"~+!_': data,
+      'list': [data],
+      'map': new Map([[data, data]]),
+      'set': new Set([data]),
+      'nested': {
+        nested: data,
+      },
+    })
+
+    expect(json).toEqual({
+      'date': new Date('2023-01-01').toISOString(),
+      'regexp': (/uic/gi).toString(),
+      'url': new URL('https://unnoq.com').href,
+      '!@#$%^^&()[]>?<~_<:"~+!_': expected,
+      'list': [expected],
+      'map': [[expected, expected]],
+      'set': [expected],
+      'nested': {
+        nested: expected,
+      },
+    })
+
+    expect(hasBlob).toBe(data instanceof Blob)
+  })
+})
+
+describe('serialize undefined', () => {
+  const serializer = new StandardOpenAPIJsonSerializer()
+
+  it('in object', () => {
+    const [json, hasBlob] = serializer.serialize({ value: undefined })
+
+    expect(json).toEqual({ value: undefined })
+    expect(hasBlob).toBe(false)
+  })
+
+  it('in array', () => {
+    const [json, hasBlob] = serializer.serialize([undefined])
+
+    expect(json).toEqual([null])
+    expect(hasBlob).toBe(false)
+  })
+})

packages/openapi-client/src/adapters/standard/openapi-json-serializer.ts

@@ -2,8 +2,31 @@ import { isObject } from '@orpc/shared'
 
 export type StandardOpenAPIJsonSerialized = [json: unknown, hasBlob: boolean]
 
+export interface StandardOpenAPICustomJsonSerializer {
+  condition(data: unknown): boolean
+  serialize(data: any): unknown
+}
+
+export interface StandardOpenAPIJsonSerializerOptions {
+  customJsonSerializers?: readonly StandardOpenAPICustomJsonSerializer[]
+}
+
 export class StandardOpenAPIJsonSerializer {
+  private readonly customSerializers: readonly StandardOpenAPICustomJsonSerializer[]
+
+  constructor(options: StandardOpenAPIJsonSerializerOptions = {}) {
+    this.customSerializers = options.customJsonSerializers ?? []
+  }
+
   serialize(data: unknown, hasBlobRef: { value: boolean } = { value: false }): StandardOpenAPIJsonSerialized {
+    for (const custom of this.customSerializers) {
+      if (custom.condition(data)) {
+        const result = this.serialize(custom.serialize(data), hasBlobRef)
+
+        return result
+      }
+    }
+
     if (data instanceof Blob) {
       hasBlobRef.value = true
       return [data, hasBlobRef.value]