refactor: zod plugin

Author: mrlubos

CLAUDE.md

@@ -88,6 +88,15 @@ scripts/               # Build and test scripts
 - Object/interface keys sorted alphabetically
 - Destructured keys sorted alphabetically
 
+## Refactoring Guidelines
+
+When refactoring existing code:
+
+- **Preserve all JSDoc comments** - Read the original file first and keep all existing documentation
+- **Match existing code patterns** - Look at similar files in the codebase for conventions
+- **Prefer `edit` over `write`** - Making targeted edits preserves comments better than rewriting files
+- **Check reference implementations** - For plugin work, use Valibot as a reference for proper patterns
+
 ## Pre-commit Checklist
 
 Run before committing (Husky runs format + lint automatically, but also verify):

packages/openapi-ts/src/plugins/zod/mini/processor.ts

@@ -1,10 +1,10 @@
-import { ref, refs } from '@hey-api/codegen-core';
+import { ref } from '@hey-api/codegen-core';
 import type { IR } from '@hey-api/shared';
 import { createSchemaProcessor, createSchemaWalker, pathToJsonPointer } from '@hey-api/shared';
 
 import { exportAst } from '../shared/export';
 import type { ProcessorContext, ProcessorResult } from '../shared/processor';
-import type { PluginState, ZodAppliedResult } from '../shared/types';
+import type { ZodFinal } from '../shared/types';
 import type { ZodPlugin } from '../types';
 import { createVisitor } from './walker';
 
@@ -37,32 +37,22 @@ export function createProcessor(plugin: ZodPlugin['Instance']): ProcessorResult
     if (!processor.markEmitted(ctx.path)) return;
 
     return processor.withContext({ anchor: ctx.namingAnchor, tags: ctx.tags }, () => {
-      const state = refs<PluginState>({
-        hasLazyExpression: false,
-        path: ctx.path,
-        tags: ctx.tags,
-      });
-
       const visitor = createVisitor({
         schemaExtractor: extractor,
-        state,
       });
       const walk = createSchemaWalker(visitor);
 
       const result = walk(ctx.schema, {
         path: ref(ctx.path),
         plugin,
       });
-      const ast =
-        (visitor.applyModifiers(result, {
-          path: ref(ctx.path),
-          plugin,
-        }) as ZodAppliedResult) ?? result.expression;
-      if (result.hasLazyExpression) {
-        state.hasLazyExpression['~ref'] = true;
-      }
 
-      exportAst({ ...ctx, ast, plugin, state });
+      const final = visitor.applyModifiers(result, {
+        path: ref(ctx.path),
+        plugin,
+      }) as ZodFinal;
+
+      exportAst({ ...ctx, final, plugin });
     });
   }
 

packages/openapi-ts/src/plugins/zod/mini/toAst/array.ts

@@ -1,91 +1,65 @@
-import type { SchemaWithType } from '@hey-api/shared';
+import type { SchemaVisitorContext, SchemaWithType, Walker } from '@hey-api/shared';
 import { childContext, deduplicateSchema } from '@hey-api/shared';
 
 import { $ } from '../../../../ts-dsl';
 import { identifiers } from '../../constants';
-import type {
-  Ast,
-  IrSchemaToAstOptions,
-  ZodAppliedResult,
-  ZodSchemaResult,
-} from '../../shared/types';
+import type { Chain } from '../../shared/chain';
+import type { CompositeHandlerResult, ZodFinal, ZodResult } from '../../shared/types';
+import type { ZodPlugin } from '../../types';
 import { unknownToAst } from './unknown';
 
-export function arrayToAst(
-  options: IrSchemaToAstOptions & {
-    applyModifiers: (result: ZodSchemaResult, opts: { optional?: boolean }) => ZodAppliedResult;
-    schema: SchemaWithType<'array'>;
-  },
-): Omit<Ast, 'typeName'> {
-  const { applyModifiers, plugin, walk } = options;
-  let { schema } = options;
-
-  const result: Partial<Omit<Ast, 'typeName'>> = {};
+export function arrayToAst({
+  applyModifiers,
+  plugin,
+  schema,
+  walk,
+  walkerCtx,
+}: {
+  applyModifiers: (result: ZodResult, opts: { optional?: boolean }) => ZodFinal;
+  plugin: ZodPlugin['Instance'];
+  schema: SchemaWithType<'array'>;
+  walk: Walker<ZodResult, ZodPlugin['Instance']>;
+  walkerCtx: SchemaVisitorContext<ZodPlugin['Instance']>;
+}): CompositeHandlerResult {
+  const childResults: Array<ZodResult> = [];
+  let schemaCopy = schema;
 
   const z = plugin.external('zod.z');
   const functionName = $(z).attr(identifiers.array);
 
-  if (!schema.items) {
-    result.expression = functionName.call(
+  let arrayExpression: ReturnType<typeof $.call> | undefined;
+
+  if (!schemaCopy.items) {
+    arrayExpression = functionName.call(
       unknownToAst({
-        ...options,
-        schema: {
-          type: 'unknown',
-        },
-      }).expression,
+        plugin,
+        schema: { type: 'unknown' },
+      }),
     );
   } else {
-    schema = deduplicateSchema({ schema });
+    schemaCopy = deduplicateSchema({ schema: schemaCopy });
 
-    // at least one item is guaranteed
-    const itemExpressions = schema.items!.map((item, index) => {
-      const itemResult = walk(
-        item,
-        childContext(
-          {
-            path: options.state.path,
-            plugin: options.plugin,
-          },
-          'items',
-          index,
-        ),
-      );
-      if (itemResult.hasLazyExpression) {
-        result.hasLazyExpression = true;
-      }
+    const itemExpressions: Array<Chain> = [];
+
+    schemaCopy.items!.forEach((item, index) => {
+      const itemResult = walk(item, childContext(walkerCtx, 'items', index));
+      childResults.push(itemResult);
 
       const finalExpr = applyModifiers(itemResult, { optional: false });
-      return finalExpr.expression;
+      itemExpressions.push(finalExpr.expression);
     });
 
     if (itemExpressions.length === 1) {
-      result.expression = functionName.call(...itemExpressions);
+      arrayExpression = functionName.call(...itemExpressions);
     } else {
-      if (schema.logicalOperator === 'and') {
-        const firstSchema = schema.items![0]!;
-        // we want to add an intersection, but not every schema can use the same API.
-        // if the first item contains another array or not an object, we cannot use
-        // `.intersection()` as that does not exist on `.union()` and non-object schemas.
-        let intersectionExpression: ReturnType<typeof $.expr | typeof $.call>;
-        if (
-          firstSchema.logicalOperator === 'or' ||
-          (firstSchema.type && firstSchema.type !== 'object')
-        ) {
-          intersectionExpression = $(z)
+      if (schemaCopy.logicalOperator === 'and') {
+        arrayExpression = functionName.call(
+          $(z)
             .attr(identifiers.intersection)
-            .call(...itemExpressions);
-        } else {
-          intersectionExpression = itemExpressions[0]!;
-          for (let i = 1; i < itemExpressions.length; i++) {
-            intersectionExpression = $(z)
-              .attr(identifiers.intersection)
-              .call(intersectionExpression, itemExpressions[i]);
-          }
-        }
-
-        result.expression = functionName.call(intersectionExpression);
+            .call(...itemExpressions),
+        );
       } else {
-        result.expression = $(z)
+        arrayExpression = $(z)
           .attr(identifiers.array)
           .call(
             $(z)
@@ -96,23 +70,28 @@ export function arrayToAst(
     }
   }
 
-  const checks: Array<ReturnType<typeof $.call>> = [];
-
-  if (schema.minItems === schema.maxItems && schema.minItems !== undefined) {
-    checks.push($(z).attr(identifiers.length).call($.fromValue(schema.minItems)));
+  if (schemaCopy.minItems === schemaCopy.maxItems && schemaCopy.minItems !== undefined) {
+    arrayExpression = arrayExpression
+      .attr(identifiers.length)
+      .call($.fromValue(schemaCopy.minItems));
   } else {
-    if (schema.minItems !== undefined) {
-      checks.push($(z).attr(identifiers.minLength).call($.fromValue(schema.minItems)));
+    const checks: Array<ReturnType<typeof $.call>> = [];
+
+    if (schemaCopy.minItems !== undefined) {
+      checks.push($(z).attr(identifiers.minLength).call($.fromValue(schemaCopy.minItems)));
     }
 
-    if (schema.maxItems !== undefined) {
-      checks.push($(z).attr(identifiers.maxLength).call($.fromValue(schema.maxItems)));
+    if (schemaCopy.maxItems !== undefined) {
+      checks.push($(z).attr(identifiers.maxLength).call($.fromValue(schemaCopy.maxItems)));
     }
-  }
 
-  if (checks.length > 0) {
-    result.expression = result.expression.attr(identifiers.check).call(...checks);
+    if (checks.length) {
+      arrayExpression = arrayExpression.attr(identifiers.check).call(...checks);
+    }
   }
 
-  return result as Omit<Ast, 'typeName'>;
+  return {
+    childResults,
+    expression: arrayExpression,
+  };
 }

packages/openapi-ts/src/plugins/zod/mini/toAst/boolean.ts

@@ -2,26 +2,21 @@ import type { SchemaWithType } from '@hey-api/shared';
 
 import { $ } from '../../../../ts-dsl';
 import { identifiers } from '../../constants';
-import type { Ast, IrSchemaToAstOptions } from '../../shared/types';
+import type { Chain } from '../../shared/chain';
+import type { ZodPlugin } from '../../types';
 
 export function booleanToAst({
   plugin,
   schema,
-}: Pick<IrSchemaToAstOptions, 'plugin'> & {
+}: {
+  plugin: ZodPlugin['Instance'];
   schema: SchemaWithType<'boolean'>;
-}): Omit<Ast, 'typeName'> {
-  const result: Partial<Omit<Ast, 'typeName'>> = {};
-  let chain: ReturnType<typeof $.call>;
-
+}): Chain {
   const z = plugin.external('zod.z');
 
   if (typeof schema.const === 'boolean') {
-    chain = $(z).attr(identifiers.literal).call($.literal(schema.const));
-    result.expression = chain;
-    return result as Omit<Ast, 'typeName'>;
+    return $(z).attr(identifiers.literal).call($.literal(schema.const));
   }
 
-  chain = $(z).attr(identifiers.boolean).call();
-  result.expression = chain;
-  return result as Omit<Ast, 'typeName'>;
+  return $(z).attr(identifiers.boolean).call();
 }

packages/openapi-ts/src/plugins/zod/mini/toAst/enum.ts

@@ -4,7 +4,7 @@ import { $ } from '../../../../ts-dsl';
 import { identifiers } from '../../constants';
 import type { EnumResolverContext } from '../../resolvers';
 import type { Chain } from '../../shared/chain';
-import type { Ast, IrSchemaToAstOptions } from '../../shared/types';
+import type { ZodPlugin } from '../../types';
 import { unknownToAst } from './unknown';
 
 function itemsNode(ctx: EnumResolverContext): ReturnType<EnumResolverContext['nodes']['items']> {
@@ -55,13 +55,15 @@ function baseNode(ctx: EnumResolverContext): Chain {
     return $(z)
       .attr(identifiers.enum)
       .call($.array(...enumMembers));
-  } else if (literalMembers.length === 1) {
+  }
+
+  if (literalMembers.length === 1) {
     return literalMembers[0]!;
-  } else {
-    return $(z)
-      .attr(identifiers.union)
-      .call($.array(...literalMembers));
   }
+
+  return $(z)
+    .attr(identifiers.union)
+    .call($.array(...literalMembers));
 }
 
 function enumResolver(ctx: EnumResolverContext): Chain {
@@ -80,31 +82,12 @@ function enumResolver(ctx: EnumResolverContext): Chain {
 export function enumToAst({
   plugin,
   schema,
-  state,
-}: Pick<IrSchemaToAstOptions, 'plugin' | 'state'> & {
+}: {
+  plugin: ZodPlugin['Instance'];
   schema: SchemaWithType<'enum'>;
-}): Omit<Ast, 'typeName'> {
+}): Chain {
   const z = plugin.external('zod.z');
 
-  const { literalMembers } = itemsNode({
-    $,
-    chain: { current: $(z) },
-    nodes: { base: baseNode, items: itemsNode },
-    plugin,
-    schema,
-    symbols: { z },
-    utils: { ast: {}, state },
-  });
-
-  if (!literalMembers.length) {
-    return unknownToAst({
-      plugin,
-      schema: {
-        type: 'unknown',
-      },
-    });
-  }
-
   const ctx: EnumResolverContext = {
     $,
     chain: {
@@ -119,16 +102,19 @@ export function enumToAst({
     symbols: {
       z,
     },
-    utils: {
-      ast: {},
-      state,
-    },
   };
 
-  const resolver = plugin.config['~resolvers']?.enum;
-  const node = resolver?.(ctx) ?? enumResolver(ctx);
+  const { literalMembers } = itemsNode(ctx);
 
-  return {
-    expression: node,
-  };
+  if (!literalMembers.length) {
+    return unknownToAst({
+      plugin,
+      schema: {
+        type: 'unknown',
+      },
+    });
+  }
+
+  const resolver = plugin.config['~resolvers']?.enum;
+  return resolver?.(ctx) ?? enumResolver(ctx);
 }

packages/openapi-ts/src/plugins/zod/mini/toAst/never.ts

@@ -2,15 +2,15 @@ import type { SchemaWithType } from '@hey-api/shared';
 
 import { $ } from '../../../../ts-dsl';
 import { identifiers } from '../../constants';
-import type { Ast, IrSchemaToAstOptions } from '../../shared/types';
+import type { Chain } from '../../shared/chain';
+import type { ZodPlugin } from '../../types';
 
 export function neverToAst({
   plugin,
-}: Pick<IrSchemaToAstOptions, 'plugin'> & {
+}: {
+  plugin: ZodPlugin['Instance'];
   schema: SchemaWithType<'never'>;
-}): Omit<Ast, 'typeName'> {
+}): Chain {
   const z = plugin.external('zod.z');
-  const result: Partial<Omit<Ast, 'typeName'>> = {};
-  result.expression = $(z).attr(identifiers.never).call();
-  return result as Omit<Ast, 'typeName'>;
+  return $(z).attr(identifiers.never).call();
 }