Feature: Dedicated Sequence Generators

[Goldziher]

Feature: Enhanced Sequence Generators

Add dedicated sequence generators for common patterns like incrementing IDs, date sequences, or custom sequences, building upon the existing iterate() method.

Current State

The library already has an iterate() method that cycles through values. This feature would enhance sequence generation capabilities with more specialized patterns.

Proposed Features

• Increment sequences

  • Numeric sequences (1, 2, 3...)
  • Alphanumeric sequences (A001, A002, B001...)
  • Custom increment patterns

• Template sequences

  • String templates with counters (user-1@example.com, user-2@example.com)
  • Multiple variable substitution
  • Format specifiers (padding, prefix, suffix)

• Date sequences

  • Incrementing by days, hours, minutes, etc.
  • Business day sequences
  • Custom date patterns

• Custom sequence functions

  • User-defined sequence generators
  • Stateful sequences with memory
  • Conditional sequences

• Sequence management

  • Ability to reset sequences
  • Named sequence registries
  • Thread-safe sequences for parallel generation

Implementation Requirements

• Build upon existing iterate() functionality
• Global sequence registry with namespacing
• Thread-safe implementation for concurrent use
• Multiple reset strategies (per-test, per-suite, manual)
• Efficient memory usage for long sequences
• Integration with fixture generation

Example API

// Numeric sequences
const factory = new Factory<User>((faker) => ({
  id: faker.sequence.increment(), // 1, 2, 3...
  employeeId: faker.sequence.increment({ start: 1000, step: 10 }), // 1000, 1010, 1020...
  code: faker.sequence.alphanumeric('USR-{0000}') // USR-0001, USR-0002...
}));

// Template sequences
const emailFactory = new Factory<Contact>((faker) => ({
  email: faker.sequence.template('user-{n}@example.com'), // user-1@example.com...
  alternateEmail: faker.sequence.template('contact.{yyyy}.{mm}.{n}@test.com') // contact.2024.01.1@test.com
}));

// Date sequences
const eventFactory = new Factory<Event>((faker) => ({
  date: faker.sequence.date({ start: '2024-01-01', increment: 'day' }),
  businessDay: faker.sequence.businessDay({ start: '2024-01-01' }),
  timestamp: faker.sequence.timestamp({ increment: 'hour' })
}));

// Custom sequences
const fibonacci = faker.sequence.custom((index) => {
  if (index <= 1) return index;
  return fibonacci(index - 1) + fibonacci(index - 2);
});

// Reset sequences
Factory.resetSequences(); // Reset all
Factory.resetSequence('increment'); // Reset specific
factory.resetSequences(); // Reset factory-specific

// Named sequences
const userIdSequence = faker.sequence.named('userId', { type: 'increment', start: 1000 });
const sameSequence = faker.sequence.named('userId'); // Reuses existing

Reset Strategies

// Per-test reset
beforeEach(() => {
  Factory.resetSequences();
});

// Manual reset with checkpoint
const checkpoint = Factory.sequenceCheckpoint();
// ... generate data ...
Factory.restoreCheckpoint(checkpoint);

// Scoped sequences
Factory.withSequenceScope(() => {
  // Sequences are isolated to this scope
  const users = UserFactory.batch(10);
}); // Sequences reset after scope

Testing Requirements

• Unit tests for each sequence type
• Thread safety tests with concurrent generation
• Reset strategy verification
• Memory usage tests for large sequences
• Integration tests with batch generation
• Fixture compatibility tests