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.

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.