# Interface-Forge


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.

Support This Project

If you find interface-forge helpful, please consider sponsoring the development:

Your support helps maintain and improve this library for the community! 🚀

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

``bash


npm

`typescript
import { Factory } from 'interface-forge';

interface User {
id: string;
name: string;
email: string;
age: number;
}

const userFactory = new Factory((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' });
`

$3

`typescript
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
`

$3

`typescript
import { MongooseAdapter } from './adapters/mongoose';

const userFactory = new Factory(factoryFn).withAdapter(
new MongooseAdapter(UserModel),
);

// Create and save to database
const user = await userFactory.create();
const users = await userFactory.createMany(10);
`

$3

`typescript
const enhancedUserFactory = userFactory.compose({
profile: profileFactory, // Use another factory
posts: postFactory.batch(3), // Generate related data
isActive: true, // Static values
});
`

Core Features

$3

- build() / buildAsync() - Generate single objects
- batch() / batchAsync() - Generate multiple objects
- extend() - Create factory variations
- compose() - Combine multiple factories
- create() / createMany() - Database persistence

$3

- beforeBuild() - Transform data before generation
- afterBuild() - Transform data after generation
- Full async support for external API calls

$3

- Cache generated data for consistent tests
- Signature validation for factory changes
- Node.js only (browser fallback available)

$3

- CycleGenerator - Predictable value cycling
- SampleGenerator - Random sampling without repeats

Documentation

📚 Complete Documentation

- Getting Started
- Core Concepts
- Zod Integration
- Advanced Features
- API Reference

Examples

All examples are available in the ./examples directory:

| Feature | Example |
| -------------------- | --------------------------------------------------------------------- |
| Basic Usage | 01-basic-usage.ts |
| Factory Composition | 02-advanced-composition.ts |
| Testing Integration | 03-testing-examples.ts |
| Zod Schemas | 07-zod-basic.ts |
| Database Persistence | adapters/` |

Contributing

We welcome contributions! Please read our contributing guidelines.

License

MIT License - see LICENSE for details.