A TypeScript library for AI-powered JSON schema creation and test data generation.
- Overview
- Installation
- Usage
- Development
- Technology Stack
- Project Structure
- Core Features
- Testing
- Contributing
- MIT License
- Support
MockingJar Library is a TypeScript library that provides JSON schema creation and AI-powered data generation capabilities. Built with modern TypeScript, comprehensive testing, and integrated with Anthropic Claude AI, it enables developers to create complex JSON structures and generate realistic data through natural language prompts.
This library serves as the core engine for JSON schema manipulation, data generation, and validation, designed to be integrated into web applications, CLI tools, or other TypeScript/Node.js projects.
npm install mockingjar-libimport { Generator, Schema, Validation } from 'mockingjar-lib';
// Define a schema
const userSchema = {
name: 'User',
description: 'User profile data',
fields: [
{
id: '1',
name: 'name',
type: 'text',
logic: { required: true, minLength: 2, maxLength: 50 }
},
{
id: '2',
name: 'email',
type: 'email',
logic: { required: true }
},
{
id: '3',
name: 'age',
type: 'number',
logic: { min: 18, max: 100 }
}
]
};
// Generate data using the Generator module
const result = await Generator.generate(
'your-anthropic-api-key',
userSchema,
'Generate realistic user data for a social media platform',
{
count: 5,
maxAttempts: 3,
enableFallback: true,
timeout: 60000
}
);
if (result.success) {
console.log('Generated data:', result.data);
console.log('Metadata:', result.metadata);
} else {
console.error('Generation failed:', result.errors);
}import { Schema } from 'mockingjar-lib';
let mySchema = {
name: 'User',
fields: [
{
id: 'user-1',
name: 'name',
type: 'text',
logic: { required: true }
}
]
};
// Add a new field to the schema root
mySchema = Schema.add.field(mySchema);
// Add a field to an object (requires object field id)
mySchema = Schema.add.objectField('object-field-id', mySchema);
// Add a field to an array item object (requires array field id)
mySchema = Schema.add.arrayItemObjectField('array-field-id', mySchema);
// Update field type (requires field id and new type)
mySchema = Schema.update.fieldType(mySchema, 'field-id', 'email');
// Update array item field type (requires field id and new type)
mySchema = Schema.update.arrayItemFieldType(mySchema, 'array-field-id', 'number');
// Remove a field (requires field id)
mySchema = Schema.delete.field(mySchema, 'field-id');
// Convert schema to JSON preview
const jsonPreview = Schema.convert.schemaToJson(mySchema.fields, {
collapsedFields: new Set(['field-id-to-collapse']),
forPreview: true
});
// Convert JSON to schema
const convertedSchema = Schema.convert.jsonToSchema(
{ name: 'John', age: 30, email: '[email protected]' },
'User Schema'
);import { Validation } from 'mockingjar-lib';
const data = {
name: 'John Doe',
email: '[email protected]',
age: 30
};
const errors = Validation.validate(data, userSchema);
if (errors.length === 0) {
console.log('Data is valid!');
} else {
console.log('Validation errors:', errors);
// Each error contains: parent, affectedField, reason, structure
}For detailed usage, see USAGE.md.
- Node.js 16+
- npm package manager
- Anthropic API key for AI features
# Clone the repository
git clone https://github.com/firstpersoncode/mockingjar-lib
cd mockingjar-lib
# Install dependencies
npm install# Development
npm run dev # Watch mode compilation
npm run build # Production build with minification
npm run build:clean # Clean build from scratch
npm run build:no-minify # Build without minification
npm run start # Run compiled code
# Testing
npm run test # Run tests
npm run test:watch # Watch mode testing
npm run test:coverage # Test coverage report
npm run test:ci # CI-friendly test run
# Code Quality
npm run lint # Run ESLint
npm run lint:fix # Fix auto-fixable lint issues
npm run lint:check # Strict linting with zero warnings
# Type Checking
npm run compile # Type check without output
npm run compile:check # Fast type check with skip lib check- Make changes to source files in
src/ - Run tests with
npm run test:watch - Check types with
npm run compile:check - Lint code with
npm run lint:fix - Build with
npm run build:clean
- Runtime: Node.js 16+
- Language: TypeScript with strict mode
- Main Dependencies:
- Anthropic Claude SDK for AI integration
- Lodash for utility functions
- UUID for unique identifiers
- Testing: Jest with TypeScript support (ts-jest)
- Linting: ESLint with TypeScript parser and strict rules
- Type Checking: TypeScript compiler with strict configuration
- Build System: TypeScript compiler with minification
- Package Manager: npm with lockfile for dependency consistency
- Type Safety: Full TypeScript implementation with strict mode enabled
- Modular Design: Clean separation of concerns with focused modules
- Comprehensive Testing: 146 unit tests with 88% coverage for critical functionality
- AI Integration: Seamless integration with Anthropic Claude for intelligent data generation
mockingjar-lib/
├── src/ # Source code
│ ├── index.ts # Main entry point with module exports
│ ├── lib/ # Core business logic
│ └── types/ # TypeScript type definitions
├── __tests__/ # Comprehensive test suite
├── dist/ # Compiled JavaScript output
├── coverage/ # Test coverage reports
├── scripts/ # Build and utility scripts
└── README.md # Project documentation
The heart of the library containing all essential functionality:
- generator.ts: Advanced data generation engine with AI integration and error recovery
- validation.ts: Comprehensive JSON validation system with detailed error reporting
- schema.ts: Schema manipulation, conversion, and field management utilities
- anthropic.ts: AI integration layer with Anthropic Claude API for intelligent data generation
- _debugger.ts: Development tools for debugging generation processes
Complete type system for the library:
- schema.ts: Schema field and structure type definitions with comprehensive field types
- generation.ts: Generation process, results, and progress tracking types
146 unit tests covering all critical functionality:
- generator.test.js: Tests for data generation, AI integration, and error recovery
- schema.test.js: Tests for schema manipulation and CRUD operations
- validation.test.js: Tests for schema validation and error reporting
- json-to-schema-conversion.test.js: Tests for JSON-to-schema conversion
- deep-nested-deletion.test.js: Tests for deep nested structure deletion
- deep-array-item-deletion.test.js: Tests for complex array manipulation
- Field Management: Add, update, and remove fields with deep nesting support
- Schema Validation: Comprehensive type checking and constraint validation
- Error Recovery: Surgical regeneration of failed fields during generation
- AI Integration: Natural language prompts for contextual data generation
- Type Safety: Full TypeScript support with strict typing
- JSON Schema Management: Create and manipulate complex JSON schemas
- AI-Powered Data Generation: Generate realistic test data using natural language
- Validation System: Comprehensive JSON validation with detailed error reporting
- Error Recovery: Advanced error handling and surgical data regeneration
The library provides comprehensive tools for creating and managing JSON schemas through the Schema module:
Support for all essential data types with full constraint configuration:
- text: String values with optional length constraints and patterns
- number: Numeric values with min/max range validation
- boolean: True/false values
- date: Date/time values in various formats
- email: Email address validation with proper format checking
- url: URL format validation
- array: Arrays with configurable item types and size constraints
- object: Nested objects with child field definitions
- schema: References to existing schemas for composition and reuse
interface SchemaField {
id: string;
name: string;
type: 'text' | 'number' | 'boolean' | 'date' | 'email' | 'url' | 'array' | 'object' | 'schema';
logic?: {
required?: boolean;
minLength?: number;
maxLength?: number;
min?: number;
max?: number;
pattern?: string;
enum?: string[];
minItems?: number;
maxItems?: number;
};
children?: SchemaField[]; // For object type
arrayItemType?: SchemaField; // For array type
description?: string;
}Advanced data generation with AI integration and error recovery through the Generator module:
- Schema Analysis: Parse and understand the schema structure
- AI Prompt Creation: Generate context-aware prompts for Anthropic Claude
- Data Generation: Create realistic data based on schema constraints
- Validation: Comprehensive validation against schema rules
- Error Recovery: Surgical regeneration of invalid fields only
- Natural Language Prompts: Use descriptive prompts for contextual data
- Schema Compliance: Strict adherence to defined structure and constraints
- Selective Error Handling: Fix specific problems without affecting valid data
- Progress Tracking: Real-time generation progress feedback
- Metadata: Detailed generation statistics and performance metrics
Comprehensive JSON validation engine through the Validation module:
- Type & Constraint Validation: Strict checking for all field types, lengths, ranges, patterns
- Structure Validation: Nested object and array structure verification
- Field Detection: Identification of missing required fields and extra unidentified fields
- Array Validation: Item-level validation with error tracking
interface ValidationError {
parent: string | null;
affectedField: string;
reason: string;
structure: SchemaField | null;
}- Type Checking: Validate data types against schema definitions
- Constraint Validation: Check length, range, pattern, and enum constraints
- Nested Object Support: Deep validation of complex nested structures
- Array Validation: Item type and size constraint checking
- Detailed Error Messages: Specific, actionable error information
Advanced error handling with surgical regeneration:
- Error Detection: Identify specific validation failures
- Context Preservation: Keep all valid data intact
- Targeted Regeneration: Fix only the problematic fields
- Validation Loop: Continue until all data is valid or max attempts reached
The project includes a comprehensive test suite covering all critical functionality with 146 tests and 88% code coverage:
__tests__/
├── generator.test.js # Data generation tests
├── schema.test.js # Schema manipulation tests
├── validation.test.js # Schema validation and error handling tests
├── json-to-schema-conversion.test.js # JSON conversion tests
├── deep-nested-deletion.test.js # Deep structure tests
└── deep-array-item-deletion.test.js # Array manipulation tests
- Schema Validation: Comprehensive validation logic testing
- Schema Manipulation: Complete CRUD operations testing
- Data Generation: AI integration and generation process testing
- Error Recovery: Surgical regeneration and error handling
- Type Safety: TypeScript type checking and constraint validation
- Edge Cases: Deep nesting, complex arrays, and boundary conditions
# Run all tests
npm test
# Watch mode for development
npm run test:watch
# Generate coverage report
npm run test:coverage
# CI-friendly test run
npm run test:ciMockingJar Library thrives on community collaboration! We welcome contributions from developers of all experience levels.
- 🐛 Report Bugs - Found an issue? Help us fix it!
- 💡 Suggest Features - Share your ideas for improvements
- 📝 Improve Documentation - Help others understand the library better
- 🔧 Submit Code - Fix bugs, add features, or optimize performance
- 🧪 Write Tests - Help us maintain reliability and quality
- 🎨 Optimize Performance - Improve generation speed and memory usage
-
Fork and Clone
git clone https://github.com/firstpersoncode/mockingjar-lib cd mockingjar-lib -
Install Dependencies
npm install
-
Set Up Environment
cp .env.example .env # Add your Anthropic API key -
Run Tests
npm run test:watch
-
Start Development
npm run dev
- TypeScript: Strict mode enabled with comprehensive typing
- ESLint: Configured with TypeScript parser and strict rules
- Testing: Unit tests required for new features (maintain 88%+ coverage)
- Documentation: JSDoc comments for public APIs
- Commit Messages: Conventional commit format preferred
-
Create Feature Branch
git checkout -b feature/your-feature-name
-
Make Changes
- Write code following existing patterns
- Add/update tests as needed
- Update documentation if required
-
Quality Checks
npm run lint:fix npm run test:coverage npm run compile:check
-
Submit PR
- Clear description of changes
- Link to related issues
- Include test results
- Be respectful and inclusive in all interactions
- Ask questions - no question is too basic
- Share knowledge - help others learn and grow
- Stay curious - explore, experiment, and innovate
Ready to contribute? Open an issue, submit a pull request, or simply star the project to show your support!
Together, we're building the future of JSON data generation.
Copyright (c) 2025 MockingJar Library
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
For technical support, feature requests, or bug reports, please contact the development team or create an issue in the project repository.
MockingJar Library - Powering intelligent JSON schema creation and data generation.