@watershed-labs/data

Test data factories, fake data helpers, and fixture loader for the Watershed ecosystem.

Part of the Watershed testing ecosystem.

Overview

@watershed-labs/data provides the lightweight data layer shared across Watershed templates. It wraps @faker-js/faker with Watershed-specific seed and locale configuration, adds a factory builder pattern for structured test objects, and provides a fixture loader for static JSON and YAML files.

This is the thin shared layer that create-hatchery builds on top of. Other templates can use it directly without pulling in the full hatchery scaffolding.

Installation

npm install @watershed-labs/data

Usage

import { factory, fixture, sequence, seed } from '@watershed-labs/data';

// Set a reproducible seed for CI runs
seed(Number(process.env.DATA_SEED) || 42);

// Define a factory
factory('user', {
    email:    () => faker.internet.email(),
    name:     () => faker.person.fullName(),
    role:     'buyer',
    verified: true,
});

// Build an instance with optional overrides
const user       = factory.build('user');
const adminUser  = factory.build('user', { role: 'admin' });
const guestUser  = factory.build('user', { verified: false });

// Build a list
const users = factory.buildList('user', 5);

// Load a static fixture
const products = fixture('products/checkout-flow');
// → reads from test/fixtures/products/checkout-flow.json or .yaml

// Generate a unique sequence ID
const orderId = sequence('order');  // → 1, 2, 3 ...

API

| Export | Description | |---|---| | factory(name, definition) | Defines a named factory. Call factory.build(name, overrides?) to generate an instance. | | factory.build(name, overrides?) | Builds a single instance of the named factory. | | factory.buildList(name, count, overrides?) | Builds an array of instances. | | fixture(path) | Loads a JSON or YAML fixture from test/fixtures/. Throws clearly if the file does not exist. | | sequence(name, start?) | Returns the next integer in a named sequence. Useful for unique IDs across a test run. | | seed(value) | Sets the global faker seed for reproducible data generation. Call once at the start of each worker. |

Parallel Safety

Safe with worker-scoped sequences. Pass workerId to DataFactory and all sequence generators are automatically offset by workerId * 20000, preventing ID collisions across workers.

// In WatershedWorld.init()
this.data = new DataFactory({ workerId: this.workerId });

Faker seeds should be set per-worker using seed(baseSeed + workerId) for reproducible but non-colliding data across parallel workers.

Licence

MIT — part of the Watershed ecosystem.