CLAUDE.md

Typia for Claude AI Development

This document provides a comprehensive guide to the typia library codebase for Claude AI developers and contributors. Typia is a TypeScript transformer library that generates super-fast runtime validators and provides advanced features for TypeScript type manipulation.

🔍 Overview

Typia is a revolutionary TypeScript transformer library that converts pure TypeScript types into runtime functions. It achieves:

• 20,000x faster runtime validation than class-validator
• 200x faster JSON serialization than class-transformer
• Seamless LLM function calling integration (including Claude)
• Protocol Buffer encoding/decoding
• Random data generation

Core Philosophy

Instead of defining schemas separately, typia uses pure TypeScript types and transforms them at compile-time into optimized runtime functions.

🏗️ Architecture Overview

Directory Structure

src/
├── transformers/        # TypeScript AST transformation logic
├── programmers/         # Code generation for different features
├── factories/           # Metadata and AST node creation utilities
├── schemas/            # Schema definitions and metadata types
├── tags/               # Validation tag definitions
├── typings/            # TypeScript type utilities
├── utils/              # General utilities
├── executable/         # CLI tools
├── internal/           # Internal implementation details
├── json.ts             # JSON schema and serialization
├── llm.ts              # LLM function calling (including Claude)
├── protobuf.ts         # Protocol Buffer support
├── functional.ts       # Functional programming utilities
├── http.ts             # HTTP-related functionality
├── misc.ts             # Miscellaneous utilities
├── notations.ts        # Naming convention transformations
├── reflect.ts          # Runtime reflection
└── module.ts           # Main export module

🤖 Claude AI Integration

Typia provides first-class support for Claude AI through its LLM module (src/llm.ts):

Supported LLM Providers

• OpenAI GPT: IChatGptSchema
• Anthropic Claude: IClaudeSchema ⭐
• High-Flyer DeepSeek: IDeepSeekSchema
• Google Gemini: IGeminiSchema
• Meta Llama: ILlamaSchema

Claude Function Calling Example

import typia from "typia";

const claudeController = typia.llm.controller<BbsArticleService, "claude">(
  "bbs",
  new BbsArticleService(),
);

// The controller automatically generates Claude-compatible schemas
const application = claudeController.application;
// Execute functions called by Claude
const result = await claudeController.execute.create(parameters);

🔧 Key Components

1. Transformers (src/transformers/)

The heart of typia's compile-time transformation:

• CallExpressionTransformer.ts: Transforms typia.xxx() calls
• FileTransformer.ts: Main file transformation orchestrator
• NodeTransformer.ts: AST node transformation logic
• ImportTransformer.ts: Handles import transformations
• features/: Feature-specific transformers

2. Programmers (src/programmers/)

Code generators for different typia features:

• AssertProgrammer.ts: Generates assertion functions
• IsProgrammer.ts: Generates type guard functions
• ValidateProgrammer.ts: Generates validation functions
• RandomProgrammer.ts: Generates random data functions
• json/: JSON-related programmers
• llm/: LLM function calling programmers
• protobuf/: Protocol Buffer programmers

3. Factories (src/factories/)

Utilities for creating metadata and AST nodes:

• MetadataFactory.ts: Creates type metadata
• JsonMetadataFactory.ts: JSON schema metadata
• ProtobufFactory.ts: Protocol Buffer metadata
• ExpressionFactory.ts: TypeScript expression creation
• StatementFactory.ts: TypeScript statement creation

4. Schemas (src/schemas/)

Type definitions and metadata structures:

• metadata/: Core metadata types
• json/: JSON schema types
• protobuf/: Protocol Buffer schema types

🚀 Main Features

1. Runtime Validators

// These functions are transformed at compile-time:
typia.is<T>(input)           // Type guard (returns boolean)
typia.assert<T>(input)       // Assertion (throws on failure)
typia.validate<T>(input)     // Detailed validation
typia.assertGuard<T>(input)  // Type assertion guard

Generated Code Example:

// Input: typia.is<string>(input)
// Output: (input) => "string" === typeof input

2. JSON Operations

typia.json.schema<T>()         // Generate JSON schema
typia.json.stringify<T>(obj)   // Fast JSON serialization
typia.json.parse<T>(str)       // Type-safe JSON parsing

3. LLM Function Calling

typia.llm.application<Class, Model>()     // Generate LLM schemas
typia.llm.controller<Class, Model>()      // Create function controller
typia.llm.parameters<P, Model>()          // Generate parameter schemas
typia.llm.schema<T, Model>()              // Generate type schemas

4. Protocol Buffers

typia.protobuf.message<T>()          // Generate .proto message
typia.protobuf.encode<T>(obj)        // Encode to Uint8Array
typia.protobuf.decode<T>(buffer)     // Decode from Uint8Array

5. Random Data Generation

typia.random<T>(generator?)          // Generate random data matching type

🧪 Development Workflow

Building the Project

pnpm install      # Install dependencies
pnpm run build    # Compile TypeScript and bundle
pnpm run dev      # Development mode with watching

Testing

pnpm run test     # Run all tests

⚠️ Note: The test/src/features and test/schemas directories contain extensive test suites with high LOC - be cautious when iterating through them.

Code Quality

pnpm run eslint        # Lint code
pnpm run prettier      # Format code
pnpm run eslint:fix    # Auto-fix lint issues
pnpm run prettier:fix  # Auto-format code

🔍 Understanding the Transformation Process

1. Source Analysis

Typia analyzes TypeScript types at compile-time using the TypeScript Compiler API.

2. Metadata Generation

Types are converted into rich metadata structures that describe validation, serialization, and schema generation requirements.

3. Code Generation

Programmers generate optimized JavaScript code based on the metadata.

4. AST Transformation

The generated code replaces the original typia.xxx() calls in the AST.

🎯 Claude-Specific Features

Schema Generation for Claude

// Generate Claude-compatible function calling schema
const app = typia.llm.application<MyAPI, "claude">();

// The generated schema follows Claude's function calling format
interface ClaudeFunction {
  name: string;
  description: string;
  input_schema: object;  // Claude-specific schema format
}

Integration Patterns

1. API Controllers: Convert TypeScript classes to Claude function schemas
2. Structured Output: Generate schemas for Claude's structured output
3. Type Safety: Maintain TypeScript type safety in Claude interactions
4. Validation: Validate Claude responses against TypeScript types

🛠️ Contributing Guidelines

Adding New Features

1. Transformer: Add transformation logic in src/transformers/features/
2. Programmer: Implement code generation in src/programmers/
3. Factory: Add metadata generation in src/factories/
4. Tests: Add comprehensive tests (but be mindful of LOC in test directories)

Code Style

• Follow TypeScript best practices
• Use the existing ESLint and Prettier configurations
• Document complex transformation logic
• Maintain backward compatibility

Testing Strategy

• Unit tests for individual components
• Integration tests for complete transformations
• Performance benchmarks for runtime functions
• LLM provider compatibility tests

📚 Key Files for Claude Developers

Essential Reading

1. src/llm.ts - Core LLM functionality and Claude integration
2. src/programmers/llm/ - LLM-specific code generation
3. src/schemas/json/ - JSON schema types used by LLM features
4. src/transformers/features/llm/ - LLM transformation logic

Metadata Flow

1. TypeScript types → MetadataFactory.ts
2. Metadata → LLM programmers
3. Generated code → AST transformation
4. Final output → Claude-compatible schemas

🔗 Related Documentation

• Main Documentation
• LLM Function Calling Guide
• API Reference
• Benchmark Results

💡 Tips for Claude AI Development

1. Performance: Typia's transformations happen at compile-time, so runtime performance is exceptional
2. Type Safety: Always use TypeScript types as the source of truth
3. Schemas: Generated schemas are optimized for each LLM provider's format
4. Debugging: Use the dev mode to see generated code during development
5. Compatibility: Test with multiple LLM providers to ensure broad compatibility

🤝 Community and Support

• GitHub Issues: Report bugs and request features
• Discord: Join the community for discussions
• Documentation: Comprehensive guides at typia.io
• Examples: Check the examples/ directory for usage patterns

---

This documentation serves as a starting point for understanding typia's architecture and Claude AI integration. The codebase is well-structured and heavily documented, making it accessible for contributors and users working with Claude AI function calling features.