chore: release version 0.5.2

- Fix: resolve crash in `z.date()` and `z.coerce.date()` handling in JSON Schema generation
- Update CHANGELOG for version 0.5.2
- Enhance README to document date field representation
- Add new tests for array, edge cases, enums, intersections, literals, objects, output schemas, primitives, records, route metadata, TypeScript types, unions, and zod date support
- Introduce helper functions for route testing
- Ensure proper handling of optional and nullable fields in schemas

Author: liorcodev

CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.2] - 2026-02-24
+
+### Fixed
+
+- **`z.date()` / `z.coerce.date()` crash** - Fixed a bug where procedures that used Zod date schemas
+  caused schema conversion to throw `"Transforms cannot be represented in JSON Schema"`, resulting
+  in no documentation being generated for those routes
+  - `z.date()` and `z.coerce.date()` fields are now correctly represented as
+    `{ type: "string", format: "date-time" }` in the generated JSON Schema, matching the ISO 8601
+    strings that tRPC transports over the wire
+  - Example values for date fields are rendered as a realistic ISO timestamp (e.g.
+    `"2024-01-01T00:00:00.000Z"`) instead of the generic `"string"` placeholder
+  - Other normally-unrepresentable types (transforms, functions) now fall back gracefully to an
+    unconstrained schema instead of hard-crashing
+
 ## [0.5.1] - 2026-01-28
 
 ### Fixed
@@ -118,7 +133,8 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - `Fixed` - Bug fixes
 - `Security` - Vulnerability fixes
 
-[Unreleased]: https://github.com/liorcohen/trpc-docs-generator/compare/v0.5.1...HEAD
+[Unreleased]: https://github.com/liorcohen/trpc-docs-generator/compare/v0.5.2...HEAD
+[0.5.2]: https://github.com/liorcohen/trpc-docs-generator/compare/v0.5.1...v0.5.2
 [0.5.1]: https://github.com/liorcohen/trpc-docs-generator/compare/v0.5.0...v0.5.1
 [0.5.0]: https://github.com/liorcohen/trpc-docs-generator/releases/tag/v0.5.0
 [0.1.0]: https://github.com/liorcohen/trpc-docs-generator/releases/tag/v0.1.0

README.md

@@ -90,6 +90,8 @@ Powered by Zod's `toJSONSchema()` method, the generator automatically:
 - Creates TypeScript type definitions
 - Identifies optional vs required fields
 - Handles complex types (unions, intersections, arrays, enums, records)
+- **Date fields** - `z.date()` and `z.coerce.date()` are represented as ISO 8601 strings
+  (`{ type: "string", format: "date-time" }`), matching how tRPC transports dates over the wire
 
 ### 🎨 Modern, Beautiful UI
 

bun.lock

@@ -1,6 +1,6 @@
 {
   "name": "trpc-docs-generator",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "author": "Lior Cohen",
   "homepage": "https://github.com/liorcodev/trpc-docs-generator#readme",
   "repository": {
@@ -15,10 +15,12 @@
   "module": "./dist/index.js",
   "devDependencies": {
     "@trpc/server": "^11.9.0",
+    "@types/bun": "^1.3.9",
     "@types/node": "^25.0.10",
     "prettier": "^3.8.1",
     "sharp": "^0.34.5",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "zod": "^4.3.6"
   },
   "exports": {
     ".": {

package.json

@@ -204,6 +204,12 @@ function generateJSONExample(
       if (schema.enum && schema.enum.length > 0) {
         return `"${schema.enum[0]}"`;
       }
+      if (schema.format === 'date-time') {
+        return '"2024-01-01T00:00:00.000Z"';
+      }
+      if (schema.format === 'date') {
+        return '"2024-01-01"';
+      }
       return '"string"';
     }
 
@@ -370,7 +376,26 @@ function generateTypeScriptExample(schema: any, depth: number = 0): string {
 }
 
 /**
- * Convert a Zod schema to JSON schema string using Zod v4+ toJSONSchema method
+ * Determine whether a Zod schema node represents a date type.
+ * Works with both Zod v3 (_def.typeName) and Zod v4 (def.type).
+ */
+function isZodDateSchema(zodSchema: unknown): boolean {
+  if (!zodSchema || typeof zodSchema !== 'object') return false;
+  const s = zodSchema as Record<string, any>;
+  // Zod v3
+  if (s._def?.typeName === 'ZodDate') return true;
+  // Zod v4 – exposes a top-level .def object and also ._zod.def
+  if (s.def?.type === 'date') return true;
+  if (s._zod?.def?.type === 'date') return true;
+  return false;
+}
+
+/**
+ * Convert a Zod schema to JSON schema string using Zod v4+ toJSONSchema method.
+ * - Dates (z.date() / z.coerce.date()) are mapped to { type: "string", format: "date-time" }
+ *   because tRPC transports them as ISO 8601 strings.
+ * - Other unrepresentable types (transforms, functions) are silently mapped to {} instead of
+ *   crashing, by passing unrepresentable: 'any'.
  * @param schema - Zod schema object
  * @returns JSON schema as string or undefined if conversion fails
  */
@@ -379,9 +404,21 @@ function zodSchemaToString(schema: unknown): string | undefined {
   try {
     // Check if it has the toJSONSchema method (Zod v4+)
     if (schema && typeof schema === 'object' && 'toJSONSchema' in schema) {
-      const toJSONSchema = (schema as { toJSONSchema: () => unknown }).toJSONSchema;
+      const toJSONSchema = (schema as { toJSONSchema: (options?: unknown) => unknown })
+        .toJSONSchema;
       if (typeof toJSONSchema === 'function') {
-        const jsonSchema = toJSONSchema();
+        const jsonSchema = toJSONSchema.call(schema, {
+          // Don't throw on transforms/functions – fall back to an unconstrained schema instead.
+          unrepresentable: 'any',
+          override: (ctx: any) => {
+            // Map Zod date schemas → { type: "string", format: "date-time" }.
+            // This covers z.date() and z.coerce.date(), both of which transport as ISO strings.
+            // NOTE: ctx.jsonSchema must be mutated in-place; reassigning the reference has no effect.
+            if (isZodDateSchema(ctx.zodSchema)) {
+              Object.assign(ctx.jsonSchema, { type: 'string', format: 'date-time' });
+            }
+          }
+        });
         return JSON.stringify(jsonSchema, null, 2);
       }
     }

src/collect-routes.ts

@@ -0,0 +1,32 @@
+import { expect } from 'bun:test';
+import { type RouteInfo } from '../src/collect-routes';
+
+export function getRoute(routes: RouteInfo[], path: string): RouteInfo {
+  const route = routes.find(r => r.path === path);
+  expect(route).toBeDefined();
+  return route!;
+}
+
+export function inputSchema(routes: RouteInfo[], path: string): any {
+  const route = getRoute(routes, path);
+  expect(route.inputSchema).toBeDefined();
+  return JSON.parse(route.inputSchema!);
+}
+
+export function outputSchema(routes: RouteInfo[], path: string): any {
+  const route = getRoute(routes, path);
+  expect(route.outputSchema).toBeDefined();
+  return JSON.parse(route.outputSchema!);
+}
+
+export function inputExample(routes: RouteInfo[], path: string): any {
+  const route = getRoute(routes, path);
+  expect(route.inputExample).toBeDefined();
+  return JSON.parse(route.inputExample!);
+}
+
+export function inputTypeScript(routes: RouteInfo[], path: string): string {
+  const route = getRoute(routes, path);
+  expect(route.inputTypeScript).toBeDefined();
+  return route.inputTypeScript!;
+}

tests/_helpers.ts

@@ -0,0 +1,44 @@
+import { describe, test, expect } from 'bun:test';
+import { initTRPC } from '@trpc/server';
+import { z } from 'zod';
+import { collectRoutes } from '../src/collect-routes';
+import { inputSchema, inputExample, inputTypeScript } from './_helpers';
+
+const t = initTRPC.create();
+
+const router = t.router({
+  strArr: t.procedure.input(z.object({ tags: z.array(z.string()) })).query(() => ''),
+  numArr: t.procedure.input(z.object({ ids: z.array(z.number()) })).query(() => ''),
+  objArr: t.procedure
+    .input(z.object({ items: z.array(z.object({ id: z.number(), name: z.string() })) }))
+    .query(() => ''),
+});
+
+describe('array types', () => {
+  test('z.array(z.string()) → type:array in JSON schema', () => {
+    expect(inputSchema(collectRoutes(router), 'strArr').properties.tags.type).toBe('array');
+  });
+
+  test('z.array(z.string()) items → type:string', () => {
+    expect(inputSchema(collectRoutes(router), 'strArr').properties.tags.items.type).toBe('string');
+  });
+
+  test('z.array(z.string()) example is a JSON array', () => {
+    const ex = inputExample(collectRoutes(router), 'strArr');
+    expect(Array.isArray(ex.tags)).toBe(true);
+    expect(ex.tags[0]).toBe('string');
+  });
+
+  test('z.array(z.number()) items → type:number|integer', () => {
+    const schema = inputSchema(collectRoutes(router), 'numArr');
+    expect(['number', 'integer']).toContain(schema.properties.ids.items.type);
+  });
+
+  test('z.array(z.object(...)) items → type:object', () => {
+    expect(inputSchema(collectRoutes(router), 'objArr').properties.items.items.type).toBe('object');
+  });
+
+  test('z.array(z.string()) TypeScript type → string[] or Array<string>', () => {
+    expect(inputTypeScript(collectRoutes(router), 'strArr')).toMatch(/string\[\]|Array<string>/);
+  });
+});

tests/arrays.test.ts

@@ -0,0 +1,57 @@
+import { describe, test, expect } from 'bun:test';
+import { initTRPC } from '@trpc/server';
+import { z } from 'zod';
+import { collectRoutes } from '../src/collect-routes';
+import { getRoute, inputSchema, inputExample } from './_helpers';
+
+const t = initTRPC.create();
+
+const router = t.router({
+  // Deeply nested union inside object
+  complex: t.procedure
+    .input(
+      z.object({
+        filter: z.union([
+          z.object({ type: z.literal('id'), value: z.number() }),
+          z.object({ type: z.literal('name'), value: z.string() }),
+        ]),
+      })
+    )
+    .query(() => ''),
+
+  // All-optional object (no required fields at all)
+  allOptional: t.procedure
+    .input(z.object({ a: z.string().optional(), b: z.number().optional() }))
+    .query(() => ''),
+
+  // Nullable date
+  nullableDate: t.procedure.input(z.object({ at: z.date().nullable() })).query(() => ''),
+});
+
+describe('edge cases', () => {
+  test('complex nested union does not throw', () => {
+    expect(() => collectRoutes(router)).not.toThrow();
+  });
+
+  test('all-optional object: example is empty {}', () => {
+    expect(inputExample(collectRoutes(router), 'allOptional')).toEqual({});
+  });
+
+  test('all-optional object: both fields appear in inputOptionalFields', () => {
+    const route = getRoute(collectRoutes(router), 'allOptional');
+    const names = route.inputOptionalFields?.map(f => f.name) ?? [];
+    expect(names).toContain('a');
+    expect(names).toContain('b');
+  });
+
+  test('nullable z.date() does not throw', () => {
+    expect(() => collectRoutes(router)).not.toThrow();
+  });
+
+  test('nullable z.date() schema contains a date-time string variant', () => {
+    const atSchema = inputSchema(collectRoutes(router), 'nullableDate').properties.at;
+    const variants = atSchema.anyOf ?? atSchema.oneOf ?? [atSchema];
+    const dateVariant = variants.find((s: any) => s.format === 'date-time');
+    expect(dateVariant).toMatchObject({ type: 'string', format: 'date-time' });
+  });
+});

tests/edge-cases.test.ts

@@ -0,0 +1,38 @@
+import { describe, test, expect } from 'bun:test';
+import { initTRPC } from '@trpc/server';
+import { z } from 'zod';
+import { collectRoutes } from '../src/collect-routes';
+import { inputSchema, inputExample, inputTypeScript } from './_helpers';
+
+const t = initTRPC.create();
+
+const router = t.router({
+  byStatus: t.procedure
+    .input(z.object({ status: z.enum(['active', 'inactive', 'pending']) }))
+    .query(() => ''),
+});
+
+describe('enums', () => {
+  test('z.enum() → type:string in JSON schema', () => {
+    expect(inputSchema(collectRoutes(router), 'byStatus').properties.status.type).toBe('string');
+  });
+
+  test('z.enum() → enum array in JSON schema', () => {
+    expect(inputSchema(collectRoutes(router), 'byStatus').properties.status.enum).toEqual([
+      'active',
+      'inactive',
+      'pending',
+    ]);
+  });
+
+  test('z.enum() example uses first value', () => {
+    expect(inputExample(collectRoutes(router), 'byStatus').status).toBe('active');
+  });
+
+  test('z.enum() TypeScript type contains quoted union members', () => {
+    const ts = inputTypeScript(collectRoutes(router), 'byStatus');
+    expect(ts).toContain('"active"');
+    expect(ts).toContain('"inactive"');
+    expect(ts).toContain('"pending"');
+  });
+});

tests/enums.test.ts

@@ -0,0 +1,38 @@
+import { describe, test, expect } from 'bun:test';
+import { initTRPC } from '@trpc/server';
+import { z } from 'zod';
+import { collectRoutes } from '../src/collect-routes';
+import { inputSchema, inputExample, inputTypeScript } from './_helpers';
+
+const t = initTRPC.create();
+
+const Base = z.object({ id: z.number() });
+const Extra = z.object({ name: z.string() });
+
+const router = t.router({
+  merged: t.procedure.input(Base.and(Extra)).query(() => ''),
+});
+
+describe('intersection types', () => {
+  test('z.intersection does not throw', () => {
+    expect(() => collectRoutes(router)).not.toThrow();
+  });
+
+  test('intersection schema contains allOf', () => {
+    const schema = inputSchema(collectRoutes(router), 'merged');
+    expect(schema.allOf).toBeDefined();
+    expect(Array.isArray(schema.allOf)).toBe(true);
+  });
+
+  test('intersection example has fields from both sides', () => {
+    const ex = inputExample(collectRoutes(router), 'merged');
+    expect(ex).toHaveProperty('id');
+    expect(ex).toHaveProperty('name');
+  });
+
+  test('intersection TypeScript type contains both field names', () => {
+    const ts = inputTypeScript(collectRoutes(router), 'merged');
+    expect(ts).toContain('id');
+    expect(ts).toContain('name');
+  });
+});