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

# 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 objects
• batch() / batchAsync() - Generate multiple objects
• extend() - Create factory variations
• compose() - Combine multiple factories
• create() / createMany() - Database persistence

Hooks & Validation

• beforeBuild() - Transform data before generation
• afterBuild() - 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 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.