zod-helper

A powerful utility library for working with Zod schemas, focused on form generation, field manipulation, and schema transformation with full TypeScript support.

Features

• 🔄 Convert Zod schemas to JSON schema format
• 📝 Generate type-safe form fields from Zod schemas
• 🔢 Group and categorize form fields using various strategies
• 📊 Organize fields by type, requirement, or custom groups
• 🏗️ Support for nested objects and array structures
• 🎯 Type-safe field position reordering
• 🧩 Full TypeScript support with proper type inference
• 🔌 Simple, chainable API

Installation

npm install zod-helper
# or
yarn add zod-helper
# or
pnpm add zod-helper

Quick Start

import { z } from 'zod';
import { ZodFormClassed } from 'zod-helper';

// Define your Zod schema
const userSchema = z.object({
  name: z.string().describe('Full name of the user'),
  email: z.string().email().describe('Email address'),
  age: z.number().min(18).describe('Age (must be 18+)'),
  role: z.enum(['admin', 'user', 'guest']).describe('User role'),
  preferences: z.object({
    theme: z.enum(['light', 'dark', 'system']).default('system'),
    notifications: z.boolean().default(true),
    language: z.string().default('en-US'),
  }).describe('User preferences'),
});

// Create a ZodFormClassed instance
const zodForm = new ZodFormClassed(userSchema);

// Rearrange field positions
zodForm.changeJsonFieldPositions({
  nested: {
    age: { position: 0 },
    name: { position: 1 },
    email: { position: 2 },
  },
});

// Group fields by keys with type safety
zodForm.groupByZodKeys(
  {
    'Personal Info': ['name', 'email', 'age'],
    'Account Settings': ['role'],
    'Preferences': [/^preferences/],
  },
  true // recursive grouping
);

// Access the processed fields
const groupedFields = zodForm.getGroupedFields;
const formFields = zodForm.getInputFields;
const jsonSchema = zodForm.getJsonSchema;

Core API

ZodFormClassed<T>

The main class for working with Zod schemas:

import { ZodFormClassed } from 'zod-helper';

const form = new ZodFormClassed(myZodSchema);

Methods

• changeJsonFieldPositions(positionMeta): Reorder fields in the schema
• groupByZodKeys(keys, recursive): Group fields with type-safe keys
• getInputFields: Get the form fields generated from the schema
• getJsonSchema: Get the JSON schema representation
• getGroupedFields: Get the grouped form fields

Utility Functions

Schema Conversion

import { convertToJsonObject } from 'zod-helper';

const jsonSchema = convertToJsonObject(myZodSchema);

Form Field Generation

import { convertToFormsFields } from 'zod-helper';

const formFields = convertToFormsFields(jsonSchema);

Field Grouping

import { 
  groupByType, 
  groupByRequired,
  groupBySchemaKeys,
  createCustomGroups 
} from 'zod-helper';

// Group by field type (string, number, boolean, etc.)
const typeGroups = groupByType(formFields);

// Group by required/optional status
const requiredGroups = groupByRequired(formFields);

// Group by schema keys
const keyGroups = groupBySchemaKeys(formFields, {
  'Personal': ['name', 'email', 'phone'],
  'Professional': [/^job/, /^work/, 'office'],
});

// Create custom groups
const customGroups = createCustomGroups(formFields, [
  { name: 'Text Fields', pattern: /^name|email|description/ },
  { name: 'Numeric Fields', pattern: /^age|amount|count/ }
]);

Advanced Usage

Type-Safe Field Positions

import { ZodFormClassed } from 'zod-helper';

const userForm = new ZodFormClassed(userSchema);

// TypeScript will enforce valid field paths
userForm.changeJsonFieldPositions({
  nested: {
    // Fields at root level
    name: { position: 0 },
    email: { position: 1 },
    // Nested fields
    preferences: { 
      position: 2,
      nested: {
        theme: { position: 0 },
        notifications: { position: 1 },
      }
    }
  }
});

Working with Arrays and Objects

The library fully supports nested arrays and objects:

const productSchema = z.object({
  name: z.string(),
  variants: z.array(z.object({
    color: z.string(),
    size: z.string(),
    stock: z.number()
  }))
});

const productForm = new ZodFormClassed(productSchema);

// Group by keys with recursive processing
productForm.groupByZodKeys({
  'Product Info': ['name'],
  'Variant Details': ['variants']
}, true);

TypeScript Support

This library is built with full TypeScript support. You'll get:

• Autocomplete for schema field names
• Type checking for field grouping
• Type-safe position adjustments
• Proper type inference for nested structures

Use Cases

• Generate form UI from Zod schemas
• Create dynamic form builders
• Transform Zod schemas for various backends
• Build structured validation UIs
• Organize form fields into logical groups

License

MIT