A TypeScript library for creating strongly typed mock data factories. Built on Faker.js with advanced composition patterns, database persistence, fixture caching, and optional Zod schema integration.
Features
- 🔒 Type-Safe: Full TypeScript support with compile-time validation
- 🚀 Zero Learning Curve: Extends Faker.js - all Faker methods work out of the box
- 🔄 Advanced Composition: Build complex object relationships with
compose() and extend()
- 🗄️ Database Integration: Built-in persistence with Mongoose, Prisma, TypeORM adapters
- 📁 Fixture Caching: Cache generated data for consistent test scenarios
- 📐 Zod Integration: Generate data directly from schemas with validation
- 🔗 Hooks & Transforms: Pre/post-build data transformation and validation
- 🎲 Deterministic: Seed generators for reproducible test data
📚 Complete Documentation | 📂 Examples
Installation
# npm
npm install --save-dev interface-forge
# yarn
yarn add --dev interface-forge
# pnpm
pnpm add --save-dev interface-forge
# For Zod integration (optional)
npm install zod
Quick Start
Basic Factory
import { Factory } from 'interface-forge';
interface User {
id: string;
name: string;
email: string;
age: number;
}
const userFactory = new Factory<User>((faker) => ({
id: faker.string.uuid(),
name: faker.person.fullName(),
email: faker.internet.email(),
age: faker.number.int({ min: 18, max: 65 }),
}));
// Generate single object
const user = userFactory.build();
// Generate multiple objects
const users = userFactory.batch(5);
// Override properties
const admin = userFactory.build({ name: 'Admin User' });
Zod Integration
import { z } from 'zod/v4';
import { ZodFactory } from 'interface-forge/zod';
const userSchema = z.object({
id: z.string().uuid(),
name: z.string().min(2),
email: z.string().email(),
age: z.number().min(18).max(65),
});
const userFactory = new ZodFactory(userSchema);
const user = userFactory.build(); // Automatically validates against schema
Database Persistence
import { MongooseAdapter } from './adapters/mongoose';
const userFactory = new Factory<User>(factoryFn).withAdapter(
new MongooseAdapter(UserModel),
);
// Create and save to database
const user = await userFactory.create();
const users = await userFactory.createMany(10);
Advanced Composition
const enhancedUserFactory = userFactory.compose<EnhancedUser>({
profile: profileFactory, // Use another factory
posts: postFactory.batch(3), // Generate related data
isActive: true, // Static values
});
Core Features
Factory Methods
build() / buildAsync() - Generate single objectsbatch() / batchAsync() - Generate multiple objectsextend() - Create factory variationscompose() - Combine multiple factoriescreate() / createMany() - Database persistence
Hooks & Validation
beforeBuild() - Transform data before generationafterBuild() - Transform data after generation- Full async support for external API calls
Fixture Caching
- Cache generated data for consistent tests
- Signature validation for factory changes
- Node.js only (browser fallback available)
Utility Generators
CycleGenerator - Predictable value cyclingSampleGenerator - Random sampling without repeats
Documentation
📚 Complete Documentation
Examples
All examples are available in the ./examples directory:
Contributing
We welcome contributions! Please read our contributing guidelines.
License
MIT License - see LICENSE for details.
