Support multiple validator options (Zod, Valibot, and ArkType) (#39)

Author: hobbescodes

.changeset/arktype-nullish-fix.md

@@ -0,0 +1,5 @@
+---
+"tangrams": patch
+---
+
+Fix ArkType emitter to generate nullish optional fields matching Zod/Valibot behavior

.changeset/multi-validator-support.md

@@ -0,0 +1,13 @@
+---
+"tangrams": minor
+---
+
+Add multi-validator support with Zod, Valibot, and ArkType
+
+- Add `validator` config option to choose between `"zod"` (default), `"valibot"`, or `"arktype"` for schema generation
+- Implement IR (Intermediate Representation) architecture that decouples spec parsing from code generation
+- Add dedicated emitters for each validator library with proper syntax and type inference
+- All three validators implement Standard Schema, ensuring compatibility with TanStack Form
+- Add `valibot` and `arktype` as optional peer dependencies
+- Update `buildQuery` function type to accept `null` values for nullish optional fields
+- Update documentation with validator configuration examples

.changeset/validator-runtime-fixes.md

@@ -0,0 +1,8 @@
+---
+"tangrams": patch
+---
+
+Fix validator schema generation issues discovered through runtime validation testing
+
+- Fix Valibot datetime format to use `v.pipe(v.string(), v.isoTimestamp())` instead of `v.isoDateTime()` for proper ISO 8601 validation with seconds and timezone
+- Fix property name double-quoting where names with special characters (e.g., `special-name`) were incorrectly quoted twice in generated schemas

README.md

@@ -16,7 +16,7 @@ tangrams is a comprehensive code generation tool for the TanStack ecosystem. It
 ## Features
 
 - **TanStack Query** - Generate type-safe `queryOptions` and `mutationOptions`
-- **TanStack Form** - Generate type-safe `formOptions` with Zod validation schemas
+- **TanStack Form** - Generate type-safe `formOptions` with validation schemas
 - **TanStack DB** - Generate `queryCollectionOptions` with auto-detected CRUD operations
 - **Standalone Functions** - Generate standalone async fetch functions
 - **TanStack Pacer** - Generate rate-limited operation wrappers _(coming soon)_
@@ -45,13 +45,18 @@ Install dependencies based on what you're generating:
 
 ```bash
 # TanStack Query (generates includes "query")
-bun add @tanstack/react-query zod
+bun add @tanstack/react-query
 
 # TanStack Form (generates includes "form")
-bun add @tanstack/react-form zod
+bun add @tanstack/react-form
 
 # TanStack DB (generates includes "db")
-bun add @tanstack/react-db @tanstack/query-db-collection @tanstack/react-query zod
+bun add @tanstack/react-db @tanstack/query-db-collection @tanstack/react-query
+
+# Validation library (choose one - zod is the default)
+bun add zod        # Default validator
+# bun add valibot  # Lightweight alternative
+# bun add arktype  # Type-first validation
 
 # GraphQL sources
 bun add graphql-request
@@ -112,7 +117,7 @@ For comprehensive documentation, configuration reference, and usage examples, vi
 
 - **[Getting Started](https://tangrams.dev/docs)** - Installation, configuration reference, and all available options
 - **[TanStack Query](https://tangrams.dev/docs/tanstack-query)** - Generate `queryOptions` and `mutationOptions`
-- **[TanStack Form](https://tangrams.dev/docs/tanstack-form)** - Generate `formOptions` with Zod validation
+- **[TanStack Form](https://tangrams.dev/docs/tanstack-form)** - Generate `formOptions` with schema validation
 - **[TanStack DB](https://tangrams.dev/docs/tanstack-db)** - Generate collections with local-first data sync
 
 ## CLI Reference

apps/docs/content/docs/index.mdx

@@ -17,7 +17,7 @@ Tangrams generates code that integrates seamlessly with the TanStack ecosystem:
 |-------|-------------------|-----------|
 | **Query Options** | `queryOptions()` with typed variables and responses | `useQuery`, `useSuspenseQuery` |
 | **Mutation Options** | `mutationOptions()` with typed inputs | `useMutation` |
-| **Form Options** | `formOptions()` with Zod validators | `useForm` |
+| **Form Options** | `formOptions()` with schema validation | `useForm` |
 | **DB Collections** | Collection options with persistence handlers | TanStack DB |
 
 ## Quick Start
@@ -95,6 +95,11 @@ export default defineConfig({
   // Output directory for all generated files (default: "./src/generated")
   output: "./src/generated",
 
+  // Validation library for generated schemas (default: "zod")
+  // Supported: "zod", "valibot", "arktype"
+  // All three implement Standard Schema for TanStack Form compatibility
+  validator: "zod",
+
   // Array of data sources to generate from
   sources: [
     // ===================
@@ -225,8 +230,61 @@ export default defineConfig({
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `output` | `string` | `"./src/generated"` | Output directory for all generated files |
+| `validator` | `"zod" \| "valibot" \| "arktype"` | `"zod"` | Validation library for generated schemas |
 | `sources` | `SourceConfig[]` | (required) | Array of data sources (minimum 1 required) |
 
+### Validator Libraries
+
+Tangrams supports three validation libraries that all implement [Standard Schema](https://github.com/standard-schema/standard-schema):
+
+| Library | Import | Description |
+|---------|--------|-------------|
+| **Zod** | `zod` | The default. Full-featured schema validation with great TypeScript inference. |
+| **Valibot** | `valibot` | Lightweight alternative with modular design and smaller bundle size. |
+| **ArkType** | `arktype` | Type-first validation with runtime safety and excellent TypeScript integration. |
+
+All three libraries work seamlessly with TanStack Form since they implement the Standard Schema protocol. Choose based on your preferences for bundle size, API style, or existing usage in your project.
+
+```typescript
+// Use Zod (default)
+export default defineConfig({
+  validator: "zod",
+  sources: [/* ... */],
+})
+
+// Use Valibot for smaller bundles
+export default defineConfig({
+  validator: "valibot",
+  sources: [/* ... */],
+})
+
+// Use ArkType for type-first validation
+export default defineConfig({
+  validator: "arktype",
+  sources: [/* ... */],
+})
+```
+
+Install your chosen validator as a peer dependency:
+
+<Tabs items={['Zod', 'Valibot', 'ArkType']}>
+  <Tab value="Zod">
+```bash
+bun add zod
+```
+  </Tab>
+  <Tab value="Valibot">
+```bash
+bun add valibot
+```
+  </Tab>
+  <Tab value="ArkType">
+```bash
+bun add arktype
+```
+  </Tab>
+</Tabs>
+
 ### GraphQL Source Options
 
 | Option | Type | Required | Description |
@@ -275,7 +333,7 @@ The `generates` array specifies which TanStack artifacts to generate:
 | Value | Description | Dependencies |
 |-------|-------------|--------------|
 | `"query"` | TanStack Query (`queryOptions`, `mutationOptions`) | None |
-| `"form"` | TanStack Form (`formOptions` with Zod validation) | None |
+| `"form"` | TanStack Form (`formOptions` with schema validation) | None |
 | `"db"` | TanStack DB (`queryCollectionOptions`) | Auto-enables `"query"` |
 
 **Examples:**
@@ -395,7 +453,7 @@ Generated files are organized by source name:
 src/generated/
 └── <source-name>/
     ├── client.ts          # API client (GraphQL or REST)
-    ├── schema.ts          # Zod schemas + TypeScript types
+    ├── schema.ts          # Validation schemas + TypeScript types
     ├── functions.ts       # Standalone fetch functions
     ├── query/
     │   └── operations.ts  # queryOptions, mutationOptions
@@ -442,5 +500,5 @@ When using `--watch`, Tangrams watches your config file, GraphQL documents, and
 Choose your TanStack library to get started:
 
 - [TanStack Query](/docs/tanstack-query) - Generate `queryOptions` and `mutationOptions`
-- [TanStack Form](/docs/tanstack-form) - Generate `formOptions` with Zod validation
+- [TanStack Form](/docs/tanstack-form) - Generate `formOptions` with schema validation
 - [TanStack DB](/docs/tanstack-db) - Generate collections with local-first data sync

apps/docs/content/docs/tanstack-db.mdx

@@ -11,20 +11,44 @@ Tangrams generates TanStack DB collection options that provide local-first data
 
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
 
+### Core
+
 <Tabs items={['bun', 'npm', 'pnpm']}>
   <Tab value="bun">
 ```bash
-bun add @tanstack/react-db @tanstack/query-db-collection @tanstack/react-query zod
+bun add @tanstack/react-db @tanstack/query-db-collection @tanstack/react-query
 ```
   </Tab>
   <Tab value="npm">
 ```bash
-npm install @tanstack/react-db @tanstack/query-db-collection @tanstack/react-query zod
+npm install @tanstack/react-db @tanstack/query-db-collection @tanstack/react-query
 ```
   </Tab>
   <Tab value="pnpm">
 ```bash
-pnpm add @tanstack/react-db @tanstack/query-db-collection @tanstack/react-query zod
+pnpm add @tanstack/react-db @tanstack/query-db-collection @tanstack/react-query
+```
+  </Tab>
+</Tabs>
+
+### Validation Library
+
+Install your chosen validator (Zod is the default). See [Validator Libraries](/docs#validator-libraries) for details.
+
+<Tabs items={['Zod', 'Valibot', 'ArkType']}>
+  <Tab value="Zod">
+```bash
+bun add zod
+```
+  </Tab>
+  <Tab value="Valibot">
+```bash
+bun add valibot
+```
+  </Tab>
+  <Tab value="ArkType">
+```bash
+bun add arktype
 ```
   </Tab>
 </Tabs>
@@ -162,7 +186,7 @@ bunx tangrams generate
 src/generated/
 └── <source>/
     ├── client.ts             # API client (shared)
-    ├── schema.ts             # Zod schemas + TypeScript types (inferred via z.infer)
+    ├── schema.ts             # Validation schemas + TypeScript types
     ├── functions.ts          # Standalone fetch functions (auto-generated)
     ├── query/
     │   └── operations.ts     # queryOptions and mutationOptions

apps/docs/content/docs/tanstack-form.mdx

@@ -1,30 +1,56 @@
 ---
 title: TanStack Form
-description: Generate formOptions for TanStack Form with Zod validation.
+description: Generate formOptions for TanStack Form with schema validation.
 ---
 
 # TanStack Form
 
-Tangrams generates `formOptions` with Zod validators from your mutations. These snap right into TanStack Form's `useForm` hook.
+Tangrams generates `formOptions` with validation schemas from your mutations. These snap right into TanStack Form's `useForm` hook.
+
+By default, Tangrams uses Zod for validation, but you can also use [Valibot or ArkType](/docs#validator-libraries) by setting the `validator` option in your config.
 
 ## Peer Dependencies
 
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
 
+### Core
+
 <Tabs items={['bun', 'npm', 'pnpm']}>
   <Tab value="bun">
 ```bash
-bun add @tanstack/react-form zod
+bun add @tanstack/react-form
 ```
   </Tab>
   <Tab value="npm">
 ```bash
-npm install @tanstack/react-form zod
+npm install @tanstack/react-form
 ```
   </Tab>
   <Tab value="pnpm">
 ```bash
-pnpm add @tanstack/react-form zod
+pnpm add @tanstack/react-form
+```
+  </Tab>
+</Tabs>
+
+### Validation Library
+
+Install your chosen validator (Zod is the default):
+
+<Tabs items={['Zod', 'Valibot', 'ArkType']}>
+  <Tab value="Zod">
+```bash
+bun add zod
+```
+  </Tab>
+  <Tab value="Valibot">
+```bash
+bun add valibot
+```
+  </Tab>
+  <Tab value="ArkType">
+```bash
+bun add arktype
 ```
   </Tab>
 </Tabs>
@@ -109,7 +135,7 @@ bunx tangrams generate
 ```
 src/generated/
 └── <source>/
-    ├── schema.ts         # Zod schemas for request bodies
+    ├── schema.ts         # Validation schemas for request bodies
     └── form/
         └── forms.ts      # formOptions exports
 ```
@@ -119,7 +145,7 @@ src/generated/
 For each mutation with a request body, Tangrams generates a `formOptions` export with:
 
 - **`defaultValues`** - Empty object with type assertion for type safety
-- **`validators`** - The Zod schema for validation (configurable timing)
+- **`validators`** - The validation schema (configurable timing)
 
 **Example `forms.ts`:**
 

apps/docs/content/docs/tanstack-query.mdx

@@ -18,17 +18,39 @@ Install the required dependencies based on your data source:
 <Tabs items={['bun', 'npm', 'pnpm']}>
   <Tab value="bun">
 ```bash
-bun add @tanstack/react-query zod
+bun add @tanstack/react-query
 ```
   </Tab>
   <Tab value="npm">
 ```bash
-npm install @tanstack/react-query zod
+npm install @tanstack/react-query
 ```
   </Tab>
   <Tab value="pnpm">
 ```bash
-pnpm add @tanstack/react-query zod
+pnpm add @tanstack/react-query
+```
+  </Tab>
+</Tabs>
+
+### Validation Library
+
+Install your chosen validator (Zod is the default). See [Validator Libraries](/docs#validator-libraries) for details.
+
+<Tabs items={['Zod', 'Valibot', 'ArkType']}>
+  <Tab value="Zod">
+```bash
+bun add zod
+```
+  </Tab>
+  <Tab value="Valibot">
+```bash
+bun add valibot
+```
+  </Tab>
+  <Tab value="ArkType">
+```bash
+bun add arktype
 ```
   </Tab>
 </Tabs>
@@ -191,7 +213,7 @@ bunx tangrams generate
 src/generated/
 └── <source>/
     ├── client.ts             # API client (shared)
-    ├── schema.ts             # Zod schemas + TypeScript types (inferred via z.infer)
+    ├── schema.ts             # Validation schemas + TypeScript types
     ├── functions.ts          # Standalone fetch functions (auto-generated)
     └── query/
         └── operations.ts     # queryOptions and mutationOptions
@@ -215,7 +237,7 @@ export const getClient = async () => {
 }
 ```
 
-**`schema.ts`** - Zod schemas and TypeScript types from your schema and operations:
+**`schema.ts`** - Validation schemas and TypeScript types from your schema and operations (shown with Zod, the default):
 
 ```typescript
 import * as z from "zod"
@@ -261,7 +283,7 @@ export const createUserMutationOptions = () =>
 
 ### OpenAPI Output
 
-**`<source>/schema.ts`** - Zod schemas and inferred TypeScript types:
+**`<source>/schema.ts`** - Validation schemas and inferred TypeScript types (shown with Zod, the default):
 
 ```typescript
 import * as z from "zod"
@@ -303,7 +325,7 @@ export const getClient = async () => {
 }
 ```
 
-**`operations.ts`** - Query and mutation options with Zod validation:
+**`operations.ts`** - Query and mutation options with schema validation:
 
 ```typescript
 export const listUsersQueryOptions = (params?: ListUsersParams) =>