@gabrielbryk/json-schema-to-zod 2.10.1 → 2.11.0

package/docs/proposals/discriminated-union-with-default.md

@@ -0,0 +1,248 @@
+# Proposal: Discriminated Union with Default Case Detection
+
+## Status: Blocked by Zod v4 Type System
+
+**TL;DR**: The runtime optimization works, but Zod v4's type system prevents `ZodDiscriminatedUnion` from being nested inside `ZodUnion`. Until this is resolved upstream, we cannot implement this optimization while maintaining type safety.
+
+## Summary
+
+Enhance `parseOneOf` to detect and optimize JSON Schema patterns where a oneOf contains multiple variants with constant discriminator values plus a "catch-all" default variant using `not: { enum: [...] }`.
+
+## Motivation
+
+Consider this common JSON Schema pattern (from Serverless Workflow spec):
+
+```yaml
+callTask:
+  oneOf:
+    - title: CallAsyncAPI
+      properties:
+        call: { const: "asyncapi" }
+    - title: CallGRPC
+      properties:
+        call: { const: "grpc" }
+    - title: CallHTTP
+      properties:
+        call: { const: "http" }
+    # ... more known variants
+    - title: CallFunction  # Default/catch-all
+      properties:
+        call:
+          not:
+            enum: ["asyncapi", "grpc", "http", "openapi", "a2a", "mcp"]
+```
+
+The `CallFunction` variant uses `not: { enum: [...] }` where the enum values **exactly match** the const values of other variants. This is semantically a discriminated union with a default case.
+
+### Current Output
+
+```typescript
+z.union([
+  asyncApiSchema,
+  grpcSchema,
+  httpSchema,
+  openapiSchema,
+  a2aSchema,
+  mcpSchema,
+  callFunctionSchema  // Default case
+])
+```
+
+This uses O(n) sequential matching - Zod tries each schema until one passes.
+
+### Proposed Output
+
+```typescript
+z.union([
+  z.discriminatedUnion("call", [
+    asyncApiSchema,
+    grpcSchema,
+    httpSchema,
+    openapiSchema,
+    a2aSchema,
+    mcpSchema
+  ]),
+  callFunctionSchema  // Default case
+])
+```
+
+**Benefits:**
+- Known values (`"asyncapi"`, `"grpc"`, etc.) use O(1) discriminated union lookup
+- Unknown values fail fast from discriminatedUnion, then try the default case
+- More efficient runtime validation for the common case
+
+## Detection Algorithm
+
+### Step 1: Identify Discriminator Candidates
+
+For each property key that appears in all oneOf options:
+1. Collect options where the property has a constant value (`const` or `enum: [single]`)
+2. Identify if exactly ONE option has `not: { enum: [...] }` for the same property
+
+### Step 2: Validate Default Case Pattern
+
+The "default case" pattern is valid when:
+1. All other options have constant discriminator values
+2. Exactly one option has `not: { enum: values }`
+3. The `values` in the negated enum **exactly match** the const values from other options
+4. The discriminator property is required in all options
+
+### Step 3: Generate Optimized Output
+
+```typescript
+type DiscriminatorResult =
+  | { type: 'full'; key: string }
+  | { type: 'withDefault'; key: string; defaultIndex: number; constValues: string[] }
+  | undefined;
+```
+
+## Implementation
+
+### Changes to `parseOneOf.ts`
+
+1. **Enhance `findImplicitDiscriminator`** to detect the default case pattern:
+
+```typescript
+const findImplicitDiscriminator = (
+  options: JsonSchema[],
+  refs: Refs
+): DiscriminatorResult => {
+  // ... existing logic to collect properties and required fields
+
+  for (const key of candidateKeys) {
+    const constValues: string[] = [];
+    let defaultIndex: number | undefined;
+    let defaultEnumValues: string[] | undefined;
+
+    for (let i = 0; i < resolvedOptions.length; i++) {
+      const prop = resolvedOptions[i].properties[key];
+
+      if (prop.const) {
+        constValues.push(prop.const);
+      } else if (prop.not?.enum) {
+        // Potential default case
+        if (defaultIndex !== undefined) {
+          // Multiple defaults - can't optimize
+          break;
+        }
+        defaultIndex = i;
+        defaultEnumValues = prop.not.enum;
+      } else {
+        // Neither const nor not.enum - can't use discriminated union
+        break;
+      }
+    }
+
+    // Check if default enum matches const values
+    if (defaultIndex !== undefined && defaultEnumValues) {
+      const constSet = new Set(constValues);
+      const enumSet = new Set(defaultEnumValues);
+      if (setsEqual(constSet, enumSet)) {
+        return { type: 'withDefault', key, defaultIndex, constValues };
+      }
+    }
+
+    // All have const values
+    if (constValues.length === resolvedOptions.length) {
+      return { type: 'full', key };
+    }
+  }
+
+  return undefined;
+};
+```
+
+2. **Update `parseOneOf`** to handle the `withDefault` case:
+
+```typescript
+export const parseOneOf = (schema, refs) => {
+  const discriminator = findImplicitDiscriminator(schema.oneOf, refs);
+
+  if (discriminator?.type === 'withDefault') {
+    const { key, defaultIndex, constValues } = discriminator;
+
+    // Parse all options
+    const allParsed = schema.oneOf.map((s, i) => parseSchema(s, {...}));
+
+    // Separate known variants from default
+    const knownVariants = allParsed.filter((_, i) => i !== defaultIndex);
+    const defaultVariant = allParsed[defaultIndex];
+
+    // Generate discriminated union with default fallback
+    const discriminatedExpr = `z.discriminatedUnion("${key}", [${knownVariants.map(v => v.expression).join(", ")}])`;
+
+    return {
+      expression: `z.union([${discriminatedExpr}, ${defaultVariant.expression}])`,
+      type: `z.ZodUnion<readonly [z.ZodDiscriminatedUnion<"${key}", readonly [${knownVariants.map(v => v.type).join(", ")}]>, ${defaultVariant.type}]>`
+    };
+  }
+
+  // ... existing logic for full discriminated union or regular union
+};
+```
+
+## Zod v4 Type System Limitation
+
+**Problem**: In Zod v4, `ZodDiscriminatedUnion` cannot be used as a member of `ZodUnion` at the type level.
+
+When we generate:
+```typescript
+z.union([
+  z.discriminatedUnion("call", [known1, known2, ...]),
+  defaultVariant
+])
+```
+
+The runtime works correctly, but TypeScript fails with:
+```
+Type 'ZodDiscriminatedUnion<...>' is not assignable to type 'SomeType'.
+The types of '_zod.values' are incompatible between these types.
+```
+
+**Root Cause**: Zod v4's internal `SomeType` constraint doesn't include `ZodDiscriminatedUnion`. This appears to be an intentional design decision, as discriminated unions are meant to be "leaf" schemas, not composable with regular unions.
+
+**Workaround Attempted**: Use a type annotation listing all individual variants while keeping the optimized runtime expression. This fails because Zod v4's strict tuple checking requires the type annotation tuple length to match the runtime tuple length.
+
+**Potential Solutions**:
+1. **Wait for Zod v4 update**: If Zod adds `ZodDiscriminatedUnion` to `SomeType`, this would work
+2. **Use type assertion**: Cast the result with `as unknown as ZodUnion<...>` - unsafe but functional
+3. **Request Zod feature**: Open an issue requesting discriminated union composability
+
+For now, we fall back to regular `z.union()` for schemas with a default case.
+
+## Edge Cases
+
+1. **Multiple default cases**: If more than one option has `not: { enum }`, fall back to regular union
+2. **Partial enum match**: If `not: { enum }` doesn't exactly match other const values, fall back to regular union
+3. **Non-string discriminators**: Only string values are supported (same as current discriminated union)
+4. **Nested allOf**: Must resolve properties from allOf members (already implemented)
+
+## Type Safety
+
+The generated type correctly represents the union structure:
+
+```typescript
+z.ZodUnion<readonly [
+  z.ZodDiscriminatedUnion<"call", readonly [
+    z.ZodIntersection<typeof TaskBase, z.ZodObject<{call: z.ZodLiteral<"asyncapi">, ...}>>,
+    z.ZodIntersection<typeof TaskBase, z.ZodObject<{call: z.ZodLiteral<"grpc">, ...}>>,
+    // ... other known variants
+  ]>,
+  z.ZodIntersection<typeof TaskBase, z.ZodObject<{call: z.ZodAny, ...}>>  // Default
+]>
+```
+
+## Testing
+
+Add test cases for:
+1. Basic discriminated union with default case
+2. Default case with exact enum match
+3. Default case with partial enum match (should fall back to union)
+4. Multiple potential defaults (should fall back to union)
+5. Real-world workflow spec CallTask schema
+
+## Future Considerations
+
+- Could extend to support multiple "catch-all" patterns beyond `not: { enum }`
+- Could support numeric discriminators if needed
+- Could potentially use Zod's `.catch()` for even more efficient default handling

package/docs/proposals/inline-object-lifting.md

@@ -0,0 +1,77 @@
+# Inline Object Lifting (Top-Level Reusable Types)
+
+## Goal
+Lift inline, non-cyclic object schemas into top-level `$defs` so both bundle and single-file outputs emit reusable Zod schemas (e.g., CallTask `with` objects such as AsyncAPI become first-class exports). This is now the default behavior (opt-out via a flag). Move lifting into an IR transformation pipeline (not just a raw-schema pre-pass) for stronger guarantees and shared behavior.
+
+## Scope
+- Applies to both `jsonSchemaToZod` (single file) and `generateSchemaBundle` (multi-file).
+- Targets inline object-like schemas (properties/patternProperties/additionalProperties/items/allOf/anyOf/oneOf/if/then/else/dependentSchemas/contains/not).
+- Skip cyclic/self-referential candidates or ones where lifting would change semantics; err on not lifting when uncertain.
+
+## High-Level Flow (IR-centric)
+1) **Analyze to IR**: ingest JSON Schema → IR with refs, dependencies, SCCs, and registry (as per bundle refactor proposal).
+2) **Hoist transform (IR pass)**:
+   - Detect inline object-like nodes (properties/items/allOf/anyOf/oneOf/if/then/else/dependentSchemas/contains/not, etc.).
+   - Skip boolean schemas, `$ref`/`$dynamicRef`, and `$defs` members.
+   - Use IR dependency graph/ref registry for accurate ancestor/self cycle detection; if ambiguous, skip.
+   - Optionally deduplicate by structural hash (excluding titles/descriptions) so identical shapes share one hoisted def.
+3) **Name** via a centralized naming service:
+   - Base on nearest named parent (root/def) + path; include discriminator/const-enum hints; suffix on collisions.
+   - Allow `nameForPath` hook; all passes/emitters call the same service.
+4) **Rewrite IR**:
+   - Create top-level def nodes for hoisted shapes; replace inline nodes with ref nodes.
+   - Preserve annotations; keep ASCII identifiers.
+   - Emit debug metadata (path → def name) for tests/telemetry.
+5) **Emit**:
+   - Single-file: emit Zod using transformed IR.
+   - Bundle: build defInfoMap/plan targets/imports from transformed IR; lifted defs flow like native `$defs`.
+
+## Options
+- Extend `Options` and `GenerateBundleOptions` with:
+  - `liftInlineObjects?: { enable?: boolean; nameForPath?: (path, ctx) => string }`
+- Default: `enable` is true; set `enable: false` to opt out.
+- Use `name`/`rootName` as the base parent name; fallback to `Root` when absent.
+
+## Integration Points
+- **Shared IR pass**: integrate the hoist transform into the IR pipeline used by both `jsonSchemaToZod` and `generateSchemaBundle`.
+- **Single file**: run analysis → hoist pass → emit.
+- **Bundle**: run analysis → hoist pass → plan/emit; new defs appear in defInfoMap/imports.
+- **Nested types**: lifted items are no longer “nested” (expected when the flag is on).
+
+## Naming Strategy (default)
+- Centralized naming service (IR utility) used by all passes/emitters.
+- Base: nearest named ancestor (def name → PascalCase; root → `Root` or provided `name`/`rootName`).
+- Path segments: PascalCase property names; union branches include discriminator const/enum when present; else index (`Option1`).
+- Collision resolution: set of existing def names + assigned names; append numeric suffix.
+- Hook: `nameForPath(path, { parentName, branchInfo, existingNames })`.
+
+## Safety / Skip Rules
+- Skip boolean schemas, pure meta-only objects (no constraints), ambiguous `unevaluatedProperties` contexts where lifting could alter validation, and any detected cycles.
+- Use ref registry/IR deps for cycle detection; if unclear, do not lift.
+- Structural hash dedup optional: only if shapes match; otherwise, keep distinct.
+
+## Testing Plan
+- **Unit (hoist IR pass)**:
+  - Lifts simple inline property object → top-level def + ref node.
+  - Lifts inside allOf/oneOf/anyOf branches; names stable and unique.
+  - Handles items/additionalProperties/patternProperties.
+  - Skips self/ancestor-ref cycles (using ref registry).
+  - Collision handling and custom `nameForPath` hook.
+  - Optional structural hash dedup: identical shapes hoisted once.
+- **Integration**:
+- Default-on: workflow fixture shows CallTask `with` shapes as top-level defs; CallTask branches reference them; `pnpm test` + workflow snapshot pass.
+- Opt-out coverage: with `enable: false`, outputs match legacy layout (no lifting) to preserve backward compatibility when explicitly requested.
+- Maintain snapshots for both modes to contain churn while default-on is adopted.
+
+## Risks / Mitigations
+- **Semantics drift**: lifting could change validation if sibling keywords depend on inline position (e.g., `unevaluatedProperties`, composition). Mitigate with conservative skip logic; if context is ambiguous, do not lift. Default-on but easily opt-out with `enable: false`.
+- **Cycle misdetection**: identity-only checks can miss `$ref`/`$dynamicRef` loops. Mitigate by reusing ref registry/IR deps for ancestor/self detection in the hoist pass.
+- **Naming collisions**: new defs could clash with existing `$defs` or generated names. Mitigate with centralized naming service, suffixing, optional hook, and checks against defInfoMap inputs.
+- **Bundle import gaps**: lifted defs must flow into defInfoMap/planBundleTargets. Mitigate by running the hoist pass before planning so new defNames/imports are included.
+- **Single/bundle divergence**: if only bundle is wired, single-file outputs diverge. Mitigate by invoking the same IR hoist pass in `jsonSchemaToZod` and exposing the flag in shared `Options`.
+
+## Implementation Notes
+- New IR transform: `src/utils/liftInlineObjects.ts` (pure, no side effects) operating on IR nodes rather than raw schema where possible; if raw is needed, still leverage ref registry.
+- Returns `{ rootSchema, defs, addedDefNames, pathToDefName }` (or IR equivalents) for debugging/tests.
+- Central naming service (shared util) used by hoist, emitters, and other passes; reuse `toPascalCase` and keep ASCII identifiers.
+- Reuse traversal coverage from `findNestedTypesInSchema` to avoid missing positions; prefer IR graph traversal for accuracy.

package/eslint.config.js

@@ -3,7 +3,7 @@ import pluginTs from "@typescript-eslint/eslint-plugin";
 
 export default [
   {
-    ignores: ["dist", "node_modules", "test/output/**"],
+    ignores: ["dist", "node_modules", "test/output/**", "*.config.js", "*.config.cjs", ".tmp-*"],
   },
   {
     files: ["**/*.ts", "**/*.tsx"],
@@ -18,7 +18,9 @@ export default [
       "@typescript-eslint": pluginTs,
     },
     rules: {
-      ...pluginTs.configs.recommended.rules,
+      // Use only non-type-aware rules from recommended
+      "@typescript-eslint/no-unused-vars": "error",
+      "@typescript-eslint/no-explicit-any": "warn",
       "@typescript-eslint/no-require-imports": "error",
       "@typescript-eslint/no-var-requires": "error",
     },

package/jest.config.mjs

@@ -0,0 +1,19 @@
+/** @type {import('@jest/types').Config.InitialOptions} */
+export default {
+  testEnvironment: "node",
+  testMatch: ["**/test/**/*.test.ts"],
+  extensionsToTreatAsEsm: [".ts"],
+  transform: {
+    "^.+\\.tsx?$": [
+      "ts-jest",
+      {
+        useESM: true,
+        tsconfig: "tsconfig.jest.json",
+        diagnostics: false,
+      },
+    ],
+  },
+  moduleNameMapper: {
+    "^(\\.{1,2}/.*)\\.js$": "$1",
+  },
+};

package/package.json

@@ -1,29 +1,26 @@
 {
   "name": "@gabrielbryk/json-schema-to-zod",
-  "version": "2.10.1",
+  "version": "2.11.0",
   "description": "Converts JSON schema objects or files into Zod schemas",
   "type": "module",
   "types": "./dist/types/index.d.ts",
-  "bin": "./dist/cjs/cli.js",
-  "main": "./dist/cjs/index.js",
-  "module": "./dist/esm/index.js",
+  "bin": "./dist/cli.js",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
   "exports": {
-    "import": {
+    ".": {
       "types": "./dist/types/index.d.ts",
-      "default": "./dist/esm/index.js"
+      "default": "./dist/index.js"
     },
-    "require": {
-      "types": "./dist/types/index.d.ts",
-      "default": "./dist/cjs/index.js"
-    }
+    "./package.json": "./package.json"
   },
   "c8": {
     "exclude": [
       "dist",
       "createIndex.ts",
       "jest.config.js",
-      "postcjs.js",
-      "postesm.js",
+      "jest.config.ts",
+      "jest.config.mjs",
       "test"
     ]
   },
@@ -66,25 +63,25 @@
     "@typescript-eslint/eslint-plugin": "^8.49.0",
     "@typescript-eslint/parser": "^8.49.0",
     "@types/json-schema": "^7.0.15",
+    "@types/jest": "^29.5.14",
     "@types/node": "^20.9.0",
-    "fast-diff": "^1.3.0",
     "eslint": "^9.39.1",
+    "jest": "^29.7.0",
     "js-yaml": "^4.1.0",
     "rimraf": "^5.0.5",
+    "ts-jest": "^29.3.4",
     "tsx": "^4.1.1",
     "typescript": "^5.2.2",
     "zod": "^4.1.13"
   },
   "scripts": {
-    "build:types": "tsc -p tsconfig.types.json",
-    "build:cjs": "tsc -p tsconfig.cjs.json && node postcjs.cjs",
-    "build:esm": "tsc -p tsconfig.esm.json && node postesm.cjs",
-    "build": "pnpm gen && pnpm test && rimraf ./dist && pnpm build:types && pnpm build:cjs && pnpm build:esm",
+    "build:esm": "tsc -p tsconfig.build.json",
+    "build": "pnpm gen && pnpm test && rimraf ./dist && pnpm build:esm",
     "dry": "pnpm build && pnpm publish --dry-run",
-    "dev": "tsx watch test/index.ts",
+    "dev": "NODE_OPTIONS=--experimental-vm-modules jest --watch",
     "gen": "tsx ./createIndex.ts",
-    "test": "tsx test/index.ts",
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest",
     "lint": "eslint \"src/**/*.{ts,tsx}\" \"test/**/*.ts\"",
-    "smoke:esm": "pnpm build:esm && node --input-type=module -e \"import { jsonSchemaToZod } from './dist/esm/index.js'; console.log(jsonSchemaToZod({type:'string'}));\""
+    "smoke:esm": "pnpm build:esm && node --input-type=module -e \"import { jsonSchemaToZod } from './dist/index.js'; console.log(jsonSchemaToZod({type:'string'}));\""
   }
 }

package/scripts/generateWorkflowSchema.ts

@@ -12,7 +12,6 @@ function main() {
   const schema = yaml.load(readFileSync(WORKFLOW_SOURCE, "utf8")) as any;
 
   const generated = jsonSchemaToZod(schema, {
-    module: "esm",
     name: "workflowSchema",
     exportRefs: true,
   });

package/dist/cjs/Types.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/cli.js

@@ -1,70 +0,0 @@
-#!/usr/bin/env node
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const jsonSchemaToZod_js_1 = require("./jsonSchemaToZod.js");
-const fs_1 = require("fs");
-const path_1 = require("path");
-const cliTools_js_1 = require("./utils/cliTools.js");
-const params = {
-    input: {
-        shorthand: "i",
-        value: "string",
-        required: process.stdin.isTTY &&
-            "input is required when no JSON or file path is piped",
-        description: "JSON or a source file path. Required if no data is piped.",
-    },
-    output: {
-        shorthand: "o",
-        value: "string",
-        description: "A file path to write to. If not supplied stdout will be used.",
-    },
-    name: {
-        shorthand: "n",
-        value: "string",
-        description: "The name of the schema in the output.",
-    },
-    depth: {
-        shorthand: "d",
-        value: "number",
-        description: "Maximum depth of recursion before falling back to z.any(). Defaults to 0.",
-    },
-    module: {
-        shorthand: "m",
-        value: ["esm", "cjs", "none"],
-        description: "Module syntax; 'esm', 'cjs' or 'none'. Defaults to 'esm'.",
-    },
-    type: {
-        shorthand: "t",
-        value: "string",
-        description: "The name of the (optional) inferred type export."
-    },
-    noImport: {
-        shorthand: "ni",
-        description: "Removes the `import { z } from 'zod';` or equivalent from the output."
-    },
-    withJsdocs: {
-        shorthand: "wj",
-        description: "Generate jsdocs off of the description property.",
-    },
-};
-async function main() {
-    const args = (0, cliTools_js_1.parseArgs)(params, process.argv, true);
-    const input = args.input || (await (0, cliTools_js_1.readPipe)());
-    const jsonSchema = (0, cliTools_js_1.parseOrReadJSON)(input);
-    const zodSchema = (0, jsonSchemaToZod_js_1.jsonSchemaToZod)(jsonSchema, {
-        name: args.name,
-        depth: args.depth,
-        module: args.module || "esm",
-        noImport: args.noImport,
-        type: args.type,
-        withJsdocs: args.withJsdocs,
-    });
-    if (args.output) {
-        (0, fs_1.mkdirSync)((0, path_1.dirname)(args.output), { recursive: true });
-        (0, fs_1.writeFileSync)(args.output, zodSchema);
-    }
-    else {
-        console.log(zodSchema);
-    }
-}
-void main();

package/dist/cjs/core/analyzeSchema.js

@@ -1,62 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.analyzeSchema = void 0;
-const parseSchema_js_1 = require("../parsers/parseSchema.js");
-const cycles_js_1 = require("../utils/cycles.js");
-const buildRefRegistry_js_1 = require("../utils/buildRefRegistry.js");
-const analyzeSchema = (schema, options = {}) => {
-    const { module, name, type, ...rest } = options;
-    if (type && (!name || module !== "esm")) {
-        throw new Error("Option `type` requires `name` to be set and `module` to be `esm`");
-    }
-    const normalized = {
-        module,
-        name,
-        type,
-        ...rest,
-        exportRefs: rest.exportRefs ?? true,
-        withMeta: rest.withMeta ?? true,
-    };
-    const refNameByPointer = new Map();
-    const usedNames = new Set();
-    if (name) {
-        usedNames.add(name);
-    }
-    const declarations = new Map();
-    const dependencies = new Map();
-    const { registry: refRegistry, rootBaseUri } = (0, buildRefRegistry_js_1.buildRefRegistry)(schema);
-    const pass1 = {
-        module,
-        name,
-        path: [],
-        seen: new Map(),
-        declarations,
-        dependencies,
-        inProgress: new Set(),
-        refNameByPointer,
-        usedNames,
-        root: schema,
-        currentSchemaName: name,
-        refRegistry,
-        rootBaseUri,
-        ...rest,
-        withMeta: normalized.withMeta,
-    };
-    (0, parseSchema_js_1.parseSchema)(schema, pass1);
-    const names = Array.from(declarations.keys());
-    const cycleRefNames = (0, cycles_js_1.detectCycles)(names, dependencies);
-    const { componentByName } = (0, cycles_js_1.computeScc)(names, dependencies);
-    return {
-        schema,
-        options: normalized,
-        refNameByPointer,
-        usedNames,
-        declarations,
-        dependencies,
-        cycleRefNames,
-        cycleComponentByName: componentByName,
-        refRegistry,
-        rootBaseUri,
-    };
-};
-exports.analyzeSchema = analyzeSchema;