feat: release interface-forge 2.7.0

Author: Goldziher

CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable user-facing changes to this project are documented here.
 
+## [2.7.0] - 2026-05-28
+
+### Added
+
+- Added `interface-forge/json-schema` with `JsonSchemaFactory` for optional AJV-backed JSON Schema data generation and validation.
+- Added JSON Schema support for object, primitive, array, nested object, `enum`, `const`, common string/number/array constraints, selected formats, and shallow local `$defs`/`definitions` references.
+- Added `factory.sequence.increment()`, `factory.sequence.template()`, and `factory.sequence.date()` helpers for stateful sequence values in factory schemas.
+- Added `IncrementSequenceGenerator`, `TemplateSequenceGenerator`, and `DateSequenceGenerator` exports for direct generator usage.
+
+### Documentation
+
+- Added JSON Schema integration documentation and installation guidance.
+- Updated generator documentation to cover `factory.sequence` and direct generator usage.
+
 ## [2.6.7] - 2026-05-28
 
 ### Fixed

README.md

@@ -10,7 +10,7 @@
 
 </div>
 
-A TypeScript library for creating strongly typed mock data factories. Built on [Faker.js](https://fakerjs.dev/) with advanced composition patterns, database persistence, fixture caching, and optional [Zod](https://zod.dev/) schema integration.
+A TypeScript library for creating strongly typed mock data factories. Built on [Faker.js](https://fakerjs.dev/) with advanced composition patterns, database persistence, fixture caching, and optional [Zod](https://zod.dev/) and JSON Schema integration.
 
 ## Support This Project
 
@@ -27,7 +27,7 @@ Your support helps maintain and improve this library for the community! 🚀
 - **🔄 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
+- **📐 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
 
@@ -47,6 +47,9 @@ 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
@@ -97,6 +100,24 @@ const userFactory = new ZodFactory(userSchema);
 const user = userFactory.build(); // Automatically validates against schema
 ```
 
+### JSON Schema Integration
+
+```typescript
+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
 
 ```typescript
@@ -147,6 +168,9 @@ const enhancedUserFactory = userFactory.compose<EnhancedUser>({
 
 - `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
 
@@ -155,6 +179,7 @@ const enhancedUserFactory = userFactory.compose<EnhancedUser>({
 - [Getting Started](https://goldziher.github.io/interface-forge/docs/getting-started/installation)
 - [Core Concepts](https://goldziher.github.io/interface-forge/docs/core/factory-basics)
 - [Zod Integration](https://goldziher.github.io/interface-forge/docs/schema/zod-integration)
+- [JSON Schema Integration](https://goldziher.github.io/interface-forge/docs/schema/json-schema-integration)
 - [Advanced Features](https://goldziher.github.io/interface-forge/docs/advanced/persistence)
 - [API Reference](https://goldziher.github.io/interface-forge/docs/api)
 

docs/docs/api.md

@@ -55,6 +55,24 @@ const user = factory.build();
 - `withTypeHandler(typeName, handler)` - Add custom type handler
 - `withTypeHandlers(handlers)` - Add multiple type handlers
 
+### JsonSchemaFactory
+
+Generate data from JSON Schema and validate it with AJV.
+
+```typescript
+import { JsonSchemaFactory } from 'interface-forge/json-schema';
+
+const factory = new JsonSchemaFactory(userSchema);
+const user = factory.build();
+```
+
+**Methods:**
+
+- `build(overrides?)` - Generate and validate one object
+- `batch(count, overrides?)` - Generate and validate multiple objects
+- `buildAsync(overrides?)` - Async generation
+- `batchAsync(count, overrides?)` - Async batch generation
+
 ### Utility Classes
 
 **Ref\<T>** - Lazy references
@@ -75,6 +93,15 @@ const gen = new CycleGenerator(['a', 'b', 'c']);
 const gen = new SampleGenerator(['x', 'y', 'z']);
 ```
 
+**factory.sequence** - Stateful sequence helpers
+
+```typescript
+const userFactory = new Factory<User>((faker) => ({
+    id: faker.sequence.increment({ start: 1 }),
+    slug: faker.sequence.template('user-{0000}'),
+}));
+```
+
 ## Type Definitions
 
 ```typescript

docs/docs/core/generators.md

@@ -4,162 +4,123 @@ sidebar_position: 3
 
 # Utility Generators
 
-Control data patterns with specialized generators.
+Control repeated data patterns with generators.
+
+## Factory Sequence Helpers
+
+Use `factory.sequence` inside factory definitions for stateful values that advance across builds and batches:
+
+```typescript
+import { Factory } from 'interface-forge';
+
+const userFactory = new Factory<User>((faker) => ({
+    id: faker.sequence.increment({ start: 1000 }),
+    slug: faker.sequence.template('user-{0000}'),
+    createdAt: faker.sequence.date({
+        start: '2026-01-01T00:00:00.000Z',
+        unit: 'day',
+    }),
+    email: faker.internet.email(),
+}));
+
+const users = userFactory.batch(3);
+// ids: 1000, 1001, 1002
+// slugs: user-0001, user-0002, user-0003
+```
+
+Each helper call site has independent state. Create a new factory when you need to reset the sequence.
 
 ## CycleGenerator
 
 Cycle through predefined values sequentially:
 
 ```typescript
-import { CycleGenerator } from 'interface-forge';
+import { CycleGenerator, Factory } from 'interface-forge';
 
-const statusGenerator = new CycleGenerator(['pending', 'active', 'failed']);
+const statusGenerator = new CycleGenerator(['pending', 'active', 'failed']).generate();
 
 const taskFactory = new Factory<Task>((faker) => ({
     id: faker.string.uuid(),
-    status: statusGenerator.next(), // Cycles: pending → active → failed → pending
+    status: statusGenerator,
     title: faker.lorem.sentence(),
 }));
 
 const tasks = taskFactory.batch(6);
-// Statuses: pending, active, failed, pending, active, failed
+// statuses: pending, active, failed, pending, active, failed
 ```
 
 ## SampleGenerator
 
-Random selection without consecutive duplicates:
+Randomly sample values without consecutive duplicates:
 
 ```typescript
-import { SampleGenerator } from 'interface-forge';
+import { Factory, SampleGenerator } from 'interface-forge';
 
-const roleGenerator = new SampleGenerator(['user', 'admin', 'guest']);
+const roleGenerator = new SampleGenerator(['user', 'admin', 'guest']).generate();
 
 const userFactory = new Factory<User>((faker) => ({
     id: faker.string.uuid(),
-    role: roleGenerator.next(), // Random, but no consecutive duplicates
+    role: roleGenerator,
     name: faker.person.fullName(),
 }));
 ```
 
+## Specialized Sequence Classes
+
+The factory helpers are the ergonomic path for factory definitions. The underlying classes are also exported when you need to manage generator instances yourself:
+
+```typescript
+import {
+    DateSequenceGenerator,
+    IncrementSequenceGenerator,
+    TemplateSequenceGenerator,
+} from 'interface-forge';
+
+const ids = new IncrementSequenceGenerator({ start: 1, step: 2 }).generate();
+const slugs = new TemplateSequenceGenerator('order-{0000}').generate();
+const dates = new DateSequenceGenerator({
+    start: '2026-01-01T00:00:00.000Z',
+    unit: 'hour',
+}).generate();
+```
+
 ## Practical Patterns
 
 ### Sequential IDs
 
 ```typescript
-const idGenerator = new CycleGenerator([1, 2, 3, 4, 5]);
-
 const orderFactory = new Factory<Order>((faker) => ({
-    id: idGenerator.next(),
+    id: faker.sequence.increment({ start: 1 }),
     total: faker.number.float({ min: 10, max: 1000 }),
 }));
 ```
 
-### Weighted Distribution
-
-```typescript
-// 50% basic, 30% premium, 20% enterprise
-const typeGenerator = new SampleGenerator([
-    'basic',
-    'basic',
-    'basic',
-    'basic',
-    'basic',
-    'premium',
-    'premium',
-    'premium',
-    'enterprise',
-    'enterprise',
-]);
-```
-
 ### State Transitions
 
 ```typescript
-const stateGenerator = new CycleGenerator([
+const statusGenerator = new CycleGenerator([
     'draft',
     'pending_review',
     'approved',
     'published',
-]);
+]).generate();
 
 const articleFactory = new Factory<Article>((faker) => ({
     title: faker.lorem.sentence(),
-    status: stateGenerator.next(),
+    status: statusGenerator,
 }));
 ```
 
 ### Time Slots
 
 ```typescript
-const timeSlots = ['09:00', '10:00', '11:00', '14:00', '15:00'];
-const timeGenerator = new CycleGenerator(timeSlots);
-
 const appointmentFactory = new Factory<Appointment>((faker) => ({
     patientName: faker.person.fullName(),
-    time: timeGenerator.next(),
+    startsAt: faker.sequence.date({
+        start: '2026-01-01T09:00:00.000Z',
+        step: 30,
+        unit: 'minute',
+    }),
     duration: 30,
 }));
 ```
-
-## Advanced Usage
-
-### Combining Generators
-
-```typescript
-const priorityGen = new CycleGenerator(['low', 'medium', 'high']);
-const categoryGen = new SampleGenerator(['bug', 'feature', 'enhancement']);
-
-const ticketFactory = new Factory<Ticket>((faker) => ({
-    id: faker.string.uuid(),
-    priority: priorityGen.next(),
-    category: categoryGen.next(),
-}));
-```
-
-### A/B Testing Data
-
-```typescript
-const variantGen = new CycleGenerator(['A', 'B']);
-
-const experimentFactory = new Factory<Experiment>((faker) => ({
-    userId: faker.string.uuid(),
-    variant: variantGen.next(), // Equal A/B distribution
-    conversionRate: faker.number.float({ min: 0, max: 1 }),
-}));
-```
-
-### Load Testing
-
-```typescript
-const endpointGen = new CycleGenerator([
-    '/api/users',
-    '/api/products',
-    '/api/orders',
-]);
-
-const requestFactory = new Factory<Request>((faker) => ({
-    endpoint: endpointGen.next(),
-    method: faker.helpers.arrayElement(['GET', 'POST', 'PUT']),
-    responseTime: faker.number.int({ min: 50, max: 2000 }),
-}));
-```
-
-## Factory Integration
-
-Use generators with factory methods:
-
-```typescript
-const userFactory = new Factory<User>(factoryFn);
-
-// iterate() - Use with CycleGenerator
-const iteratedFactory = userFactory.iterate(statusGenerator);
-
-// sample() - Use with SampleGenerator
-const sampledFactory = userFactory.sample(
-    [{ role: 'admin' }, { role: 'user' }],
-    (template, faker) => ({
-        ...userFactory.build(),
-        role: template.role,
-    }),
-);
-```

docs/docs/getting-started/basic-usage.md

@@ -140,4 +140,5 @@ const eventFactory = new Factory<Event>((faker) => {
 
 - [Factory Composition](../core/composition) - Combine factories
 - [Utility Generators](../core/generators) - Control data patterns
-- [Zod Integration](../schema/zod-integration) - Schema-based generation
+- [Zod Integration](../schema/zod-integration) - Zod-based generation
+- [JSON Schema Integration](../schema/json-schema-integration) - JSON Schema-based generation

docs/docs/getting-started/installation.md

@@ -25,3 +25,11 @@ If you want to use the Zod integration, you will also need to install `zod`:
 ```bash
 pnpm add zod
 ```
+
+## Optional JSON Schema Integration
+
+If you want to use the JSON Schema integration, install the AJV peer dependencies:
+
+```bash
+pnpm add ajv ajv-formats
+```

docs/docs/index.md

@@ -13,7 +13,7 @@ Interface Forge is a TypeScript library for creating strongly typed mock data fa
 - **Type-Safe Factories**: Create factories that are fully type-safe, ensuring that your test data always matches your interfaces.
 - **Faker.js Integration**: Leverages the full power of Faker.js for generating realistic data.
 - **Advanced Composition**: Easily compose factories to create complex data structures.
-- **Zod Schema Integration**: Generate mock data directly from your Zod schemas.
+- **Schema Integration**: Generate mock data directly from Zod or JSON Schema.
 - **Extensible**: Customize and extend the library to fit your specific needs.
 
 ## Support This Project