Guardz Generator

Guardz Generator is a powerful tool for automatically generating runtime type guards from your TypeScript interfaces and type aliases, using the guardz library. It enables robust runtime type checking for your TypeScript codebase with minimal effort.

What Can Guardz Generator Do?

• Generate Type Guards: Automatically creates type guard functions for your TypeScript interfaces, type aliases, enums, and more.
• Supports Generics: Handles generic interfaces and type aliases, including nested generics.
• Handles Recursion: Detects and supports both direct and indirect recursive types, generating correct function-based guards.
• Advanced Enum Support: Generates guards for enums using the isEnum() pattern.
• Union & Composite Types: Supports union types, intersection types, and complex compositions.
• Cross-file & NPM Types: Resolves and generates guards for types imported from other files or npm packages, using local guards when available or falling back to isAsserted.
• Post-Processing: Optionally formats, lints, and type-checks generated files for code quality.
• Flexible CLI & API: Use via CLI or programmatically in your own scripts.

Installation

npm install guardz-generator

Usage

CLI

• Generate all type guards using a config file:

  npx guardz-generator
  # or specify a config file
  npx guardz-generator --config guardz.config.ts

• Generate for specific files:

  npx guardz-generator generate "src/**/*.ts"

• Generate for a specific type:

  npx guardz-generator generate "src/**/*.ts" -t UserDTO

• Skip post-processing:

  npx guardz-generator generate "src/**/*.ts" --no-post-process

Programmatic API

import { TypeGuardGenerator } from 'guardz-generator';

const generator = new TypeGuardGenerator(['src/**/*.ts']);
const files = generator.generateAllTypeGuards();
await generator.writeTypeGuardsToSameDirectory(files);

// Generate a specific type guard
const typeGuardCode = generator.generateTypeGuard('UserDTO');

Supported TypeScript Features

• Interfaces & Type Aliases: Generates guards for all your interfaces and type aliases.
• Generics: Handles generic types and nested generics.
• Enums: Generates guards using isEnum().
• Union & Intersection Types: Full support for unions, intersections, and composite types.
• Recursive Types: Handles direct and indirect recursion, including multi-way cycles.
• Tuples & Arrays: Generates guards for tuple and array types.
• Nullable & Optional Types: Correctly handles null, undefined, and optional properties.
• BigInt & Advanced Number Types: Supports bigint and advanced number types like PositiveInteger, NonNegativeInteger, etc.
• Cross-file & NPM Imports: Resolves types across files and npm packages, using local guards or isAsserted as needed.

Example Output

Given this TypeScript interface:

export interface User {
  id: number;
  name: string | null;
  status: UserStatus;
  profile?: UserProfile;
}

Guardz Generator produces:

export const isUser = isType<User>({
  id: isNumber,
  name: isNullOr(isString),
  status: isEnum(UserStatus),
  profile: isUndefinedOr(isUserProfile),
});

Advanced Capabilities

• Automatic Post-Processing: Optionally runs Prettier, ESLint, and TypeScript checks on generated files.
• Cycle Detection: Detects and handles recursive and cyclic type references.
• Custom Type Guards: Generate custom guards for any TypeScript type node.
• AST Utilities: Exposes utilities for advanced users (e.g., property extraction, recursion detection).

Why Use Guardz Generator?

• Save Time: No more hand-writing repetitive type guards.
• Increase Safety: Get runtime validation for your TypeScript types.
• Stay Up-to-date: Supports the latest TypeScript and guardz features.
• Flexible: Use in any project, with CLI or API.

License

MIT