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 and JSON 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
• Schema Integration: Generate data directly from Zod or JSON Schema 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

# For JSON Schema integration (optional)
npm install ajv ajv-formats

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

JSON Schema Integration

import { JsonSchemaFactory } from 'interface-forge/json-schema';

const userSchema = {
    type: 'object',
    required: ['id', 'email'],
    properties: {
        id: { type: 'string', format: 'uuid' },
        email: { type: 'string', format: 'email' },
    },
} as const;

const userFactory = new JsonSchemaFactory(userSchema);
const user = userFactory.build(); // Automatically validates with AJV

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
• factory.sequence.increment() - Incrementing numeric sequences
• factory.sequence.template() - Template-based string sequences
• factory.sequence.date() - Date/time sequences

Documentation

Complete Documentation

• Getting Started
• Core Concepts
• Zod Integration
• JSON Schema 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.