Support This Project

Features

Installation

# npm
pnpm add --save-dev interface-forge

# yarn
yarn add --dev interface-forge

# pnpm
pnpm add --save-dev interface-forge

# For Zod integration (optional)
pnpm add zod

# For JSON Schema integration (optional)
pnpm add ajv ajv-formats

# For GraphQL integration (optional)
pnpm add graphql

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

GraphQL Integration

import { createGraphQLFactories } from 'interface-forge/graphql';

const sdl = `
    type User { id: ID!, name: String!, roles: [Role!]! }
    type Post { author: User!, title: String }
    enum Role { ADMIN USER }
    scalar DateTime
`;

const factories = createGraphQLFactories(sdl, {
    customScalarGenerators: { DateTime: () => '2026-01-01T00:00:00Z' },
});

const post = factories.Post?.build();

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

Hooks & Validation

Lazy Evaluation

const UserFactory = new Factory<User>((factory) => ({
    id: factory.string.uuid(),
    token: factory.use(async () => await generateToken()),
}));

const user = await UserFactory.buildAsync();

Presets

const userFactory = new Factory<User>((faker) => ({
    name: faker.person.fullName(),
    role: 'user',
})).preset('admin', { role: 'admin' });

const admin = userFactory.build(undefined, { presets: ['admin'] });

Constraint Helpers

const orderFactory = new Factory<Order>((faker) => ({
    id: factory.constraints.unique('id', () => faker.string.uuid()),
    total: factory.constraints.between(1, 500, () => faker.number.float({ min: 0, max: 1000 })),
}));

Type Utilities

import { expectTypeOf } from 'expect-type';
import type { FactoryOutput } from 'interface-forge';

const adminFactory = userFactory.extend((factory) => ({
    permissions: ['read', 'write'],
}));

type Admin = User & { permissions: string[] };
expectTypeOf<FactoryOutput<typeof adminFactory>>().toEqualTypeOf<Admin>();

Fixture Caching

Utility Generators

Documentation

Examples

Contributing

License