feat(valibot): ValibotToJsonSchemaConverter (#261)

closes: https://github.com/unnoq/orpc/issues/162

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

## Summary by CodeRabbit

- **New Features**
- Expanded API specification generation to support an additional schema
library option, allowing users to choose between multiple schema
integrations.
- Streamlined setup by removing an outdated dependency from installation
commands.
  - Introduced experimental warnings for emerging features.

- **Documentation**
- Updated guides and installation instructions to reflect broader schema
support.
- Added comprehensive documentation outlining the new integration for
enhanced developer experience.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: dinwwwh

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

@@ -12,43 +12,47 @@ oRPC uses the [OpenAPI Specification](https://spec.openapis.org/oas/v3.1.0) to d
 ::: code-group
 
 ```sh [npm]
-npm install @orpc/openapi@latest @orpc/zod@latest
+npm install @orpc/openapi@latest
 ```
 
 ```sh [yarn]
-yarn add @orpc/openapi@latest @orpc/zod@latest
+yarn add @orpc/openapi@latest
 ```
 
 ```sh [pnpm]
-pnpm add @orpc/openapi@latest @orpc/zod@latest
+pnpm add @orpc/openapi@latest
 ```
 
 ```sh [bun]
-bun add @orpc/openapi@latest @orpc/zod@latest
+bun add @orpc/openapi@latest
 ```
 
 ```sh [deno]
-deno install npm:@orpc/openapi@latest npm:@orpc/zod@latest
+deno install npm:@orpc/openapi@latest
 ```
 
 :::
 
 ## Generating Specifications
 
-oRPC supports only OpenAPI 3.1.1 and uses [Zod](https://github.com/colinhacks/zod) as its sole schema library. You can generate specifications from either a [Router](/docs/router) or a [Contract](/docs/contract-first/define-contract):
+oRPC supports OpenAPI 3.1.1 and integrates seamlessly with popular schema libraries like [Zod](https://github.com/colinhacks/zod), and [Valibot](https://valibot.dev). You can generate specifications from either a [Router](/docs/router) or a [Contract](/docs/contract-first/define-contract):
 
 :::info
-Interested in [Valibot](https://valibot.dev) support? Help us prioritize this feature by casting your vote on [Github](https://github.com/unnoq/orpc/issues/162)
+Interested in support for additional schema libraries? [Let us know](https://github.com/unnoq/orpc/discussions/categories/ideas)!
 :::
 
 ```ts twoslash
 import { contract, router } from './shared/planet'
 // ---cut---
 import { OpenAPIGenerator } from '@orpc/openapi'
 import { ZodToJsonSchemaConverter } from '@orpc/zod'
+import { experimental_ValibotToJsonSchemaConverter as ValibotToJsonSchemaConverter } from '@orpc/valibot'
 
 const openAPIGenerator = new OpenAPIGenerator({
-  schemaConverters: [new ZodToJsonSchemaConverter()],
+  schemaConverters: [
+    new ZodToJsonSchemaConverter(), // <-- if you use Zod
+    new ValibotToJsonSchemaConverter(), // <-- if you use Valibot
+  ],
 })
 
 const specFromContract = await openAPIGenerator.generate(contract, {
@@ -66,6 +70,10 @@ const specFromRouter = await openAPIGenerator.generate(router, {
 })
 ```
 
+:::warning
+Features prefixed with `experimental_` are unstable and may lack some functionality.
+:::
+
 ## Operation Metadata
 
 You can enrich your API documentation by specifying operation metadata using the `.route` or `.tag`:

apps/content/package.json

@@ -12,6 +12,7 @@
     "@orpc/contract": "workspace:*",
     "@orpc/react-query": "workspace:*",
     "@orpc/server": "workspace:*",
+    "@orpc/valibot": "workspace:*",
     "@orpc/vue-colada": "workspace:*",
     "@orpc/vue-query": "workspace:*",
     "@orpc/zod": "workspace:*",

packages/valibot/.gitignore

@@ -0,0 +1,26 @@
+# Hidden folders and files
+.*
+!.gitignore
+!.*.example
+
+# Common generated folders
+logs/
+node_modules/
+out/
+dist/
+dist-ssr/
+build/
+coverage/
+temp/
+
+# Common generated files
+*.log
+*.log.*
+*.tsbuildinfo
+*.vitest-temp.json
+vite.config.ts.timestamp-*
+vitest.config.ts.timestamp-*
+
+# Common manual ignore files
+*.local
+*.pem

packages/valibot/README.md

@@ -0,0 +1,98 @@
+<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/valibot">
+    <img alt="weekly downloads" src="https://img.shields.io/npm/dw/%40orpc%2Fvalibot?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>
+</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, ensuring a smooth and enjoyable developer experience.
+
+---
+
+## Highlights
+
+- **End-to-End Type Safety 🔒**: Ensure complete type safety from inputs to outputs and errors, bridging server and client seamlessly.
+- **First-Class OpenAPI 📄**: Adheres to the OpenAPI standard out of the box, ensuring seamless integration and comprehensive API documentation.
+- **Contract-First Development 📜**: (Optional) Define your API contract upfront and implement it with confidence.
+- **Exceptional Developer Experience ✨**: Enjoy a streamlined workflow with robust typing and clear, in-code documentation.
+- **Multi-Runtime Support 🌍**: Run your code seamlessly on Cloudflare, Deno, Bun, Node.js, and more.
+- **Framework Integrations 🧩**: Supports Tanstack Query (React, Vue, Solid, Svelte), Pinia Colada, and more.
+- **Server Actions ⚡️**: Fully compatible with React Server Actions on Next.js, TanStack Start, and more.
+- **Standard Schema Support 🗂️**: Effortlessly work with Zod, Valibot, ArkType, and others right out of the box.
+- **Fast & Lightweight 💨**: Built on native APIs across all runtimes – optimized for speed and efficiency.
+- **Native Types 📦**: Enjoy built-in support for Date, File, Blob, BigInt, URL and more with no extra setup.
+- **Lazy Router ⏱️**: Improve cold start times with our lazy routing feature.
+- **SSE & Streaming 📡**: Provides SSE and streaming features – perfect for real-time notifications and AI-powered streaming responses.
+- **Reusability 🔄**: Write once and reuse your code across multiple purposes effortlessly.
+- **Extendability 🔌**: Easily enhance oRPC with plugins, middleware, and interceptors.
+- **Reliability 🛡️**: Well-tested, fully TypeScript, production-ready, and MIT licensed for peace of mind.
+- **Simplicity 💡**: Enjoy straightforward, clean code with no hidden magic.
+
+## 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/react-query](https://www.npmjs.com/package/@orpc/react-query): Integration with [React Query](https://tanstack.com/query/latest/docs/framework/react/overview).
+- [@orpc/vue-query](https://www.npmjs.com/package/@orpc/vue-query): Integration with [Vue Query](https://tanstack.com/query/latest/docs/framework/vue/overview).
+- [@orpc/solid-query](https://www.npmjs.com/package/@orpc/solid-query): Integration with [Solid Query](https://tanstack.com/query/latest/docs/framework/solid/overview).
+- [@orpc/svelte-query](https://www.npmjs.com/package/@orpc/svelte-query): Integration with [Svelte Query](https://tanstack.com/query/latest/docs/framework/svelte/overview).
+- [@orpc/vue-colada](https://www.npmjs.com/package/@orpc/vue-colada): Integration with [Pinia Colada](https://pinia-colada.esm.dev/).
+- [@orpc/openapi](https://www.npmjs.com/package/@orpc/openapi): Generate OpenAPI specs and handle OpenAPI requests.
+- [@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/zod): OpenAPI spec generation from [Valibot](https://valibot.dev/).
+
+## `@orpc/valibot`
+
+Provides `ValibotToJsonSchemaConverter` for generating OpenAPI specs from [Valibot](https://valibot.dev/).
+
+### Generate OpenAPI Spec
+
+```ts
+import { OpenAPIGenerator } from '@orpc/openapi'
+import { experimental_ValibotToJsonSchemaConverter as ValibotToJsonSchemaConverter } from '@orpc/valibot'
+
+const openAPIGenerator = new OpenAPIGenerator({
+  schemaConverters: [
+    new ValibotToJsonSchemaConverter()
+  ],
+})
+
+const specFromContract = await openAPIGenerator.generate(contract, {
+  info: {
+    title: 'My App',
+    version: '0.0.0',
+  },
+})
+
+const specFromRouter = await openAPIGenerator.generate(router, {
+  info: {
+    title: 'My App',
+    version: '0.0.0',
+  },
+})
+```
+
+## License
+
+Distributed under the MIT License. See [LICENSE](https://github.com/unnoq/orpc/blob/main/LICENSE) for more information.

packages/valibot/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@orpc/valibot",
+  "type": "module",
+  "version": "0.0.0",
+  "license": "MIT",
+  "homepage": "https://orpc.unnoq.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unnoq/orpc.git",
+    "directory": "packages/valibot"
+  },
+  "keywords": [
+    "unnoq",
+    "orpc"
+  ],
+  "publishConfig": {
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.mts",
+        "import": "./dist/index.mjs",
+        "default": "./dist/index.mjs"
+      }
+    }
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "unbuild",
+    "build:watch": "pnpm run build --watch",
+    "type:check": "tsc -b"
+  },
+  "peerDependencies": {
+    "@orpc/contract": "workspace:*",
+    "@orpc/server": "workspace:*",
+    "valibot": "*"
+  },
+  "dependencies": {
+    "@orpc/openapi": "workspace:*",
+    "@orpc/shared": "workspace:*",
+    "@valibot/to-json-schema": "1.0.0-rc.0"
+  }
+}

packages/valibot/src/converter.test.ts

@@ -0,0 +1,29 @@
+import * as v from 'valibot'
+import { z } from 'zod'
+import { experimental_ValibotToJsonSchemaConverter as ValibotToJsonSchemaConverter } from './converter'
+
+it('valibotToJsonSchemaConverter.convert', async () => {
+  const converter = new ValibotToJsonSchemaConverter()
+  expect(converter.convert(v.string(), { strategy: 'input' })).toEqual(
+    [true, {
+      $schema: 'http://json-schema.org/draft-07/schema#',
+      type: 'string',
+    }],
+  )
+  expect(converter.convert(v.object({ a: v.string() }), { strategy: 'input' })).toEqual(
+    [true, {
+      $schema: 'http://json-schema.org/draft-07/schema#',
+      type: 'object',
+      properties: { a: { type: 'string' } },
+      required: ['a'],
+    }],
+  )
+})
+
+it('valibotToJsonSchemaConverter.condition', async () => {
+  const converter = new ValibotToJsonSchemaConverter()
+  expect(converter.condition(v.string())).toBe(true)
+  expect(converter.condition(v.optional(v.string()))).toBe(true)
+  expect(converter.condition(z.string())).toBe(false)
+  expect(converter.condition(z.string().optional())).toBe(false)
+})

packages/valibot/src/converter.ts

@@ -0,0 +1,25 @@
+import type { AnySchema } from '@orpc/contract'
+import type { ConditionalSchemaConverter, JSONSchema, SchemaConvertOptions } from '@orpc/openapi'
+import { type ConversionConfig, toJsonSchema } from '@valibot/to-json-schema'
+
+export interface experimental_ValibotToJsonSchemaConverterOptions extends Pick<ConversionConfig, 'errorMode'> {
+
+}
+
+export class experimental_ValibotToJsonSchemaConverter implements ConditionalSchemaConverter {
+  private readonly errorMode: experimental_ValibotToJsonSchemaConverterOptions['errorMode']
+
+  constructor(options: experimental_ValibotToJsonSchemaConverterOptions = {}) {
+    this.errorMode = options.errorMode ?? 'ignore'
+  }
+
+  condition(schema: AnySchema | undefined): boolean {
+    return schema !== undefined && schema['~standard'].vendor === 'valibot'
+  }
+
+  convert(schema: AnySchema | undefined, _options: SchemaConvertOptions): [required: boolean, jsonSchema: Exclude<JSONSchema, boolean>] {
+    const jsonSchema = toJsonSchema(schema as any, { errorMode: this.errorMode })
+
+    return [true, jsonSchema as any]
+  }
+}

packages/valibot/src/index.ts

@@ -0,0 +1 @@
+export * from './converter'

packages/valibot/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "extends": "../../tsconfig.lib.json",
+  "compilerOptions": {
+    "rootDir": "src"
+  },
+  "references": [
+    { "path": "../openapi" },
+    { "path": "../contract" },
+    { "path": "../server" },
+    { "path": "../shared" }
+  ],
+  "include": ["src"],
+  "exclude": [
+    "**/*.test.*",
+    "**/*.test-d.ts",
+    "**/__tests__/**",
+    "**/__mocks__/**",
+    "**/__snapshots__/**"
+  ]
+}