tillage

Tillage

Relational test data. Seed whole databases, not columns.

Install

npm i tillage

Quickstart

import { seed, defineFactory, hasMany } from 'tillage';

const user = defineFactory('user', ({ faker }) => ({ name: faker.person.fullName(), email: faker.internet.email() }));
const order = defineFactory('order', ({ faker }) => ({ total: faker.number.int({ min: 10, max: 500 }), userId: 0 }));

const data = seed(42, () => { user.buildList(3, { orders: hasMany(order, 2) }); });
console.log(data.toSQL({ dialect: 'postgres' }));

Run it with npx tsx examples/quickstart.ts once the package is installed locally.

What it does

Tillage generates referentially-consistent relational datasets. It is not a faker replacement: it wraps @faker-js/faker for leaf values (names, emails, numbers, and so on) and adds the piece faker does not have, relationships between records.

Define a factory per entity with defineFactory, then connect them:

• belongsTo(target), a required foreign key to a parent
• belongsToMaybe(target), an optional foreign key, useful for self-referential rows
• hasMany(target, count), a parent building N children
• oneToOne(target), a single linked child
• unique(fn), a value that will not repeat across a factory's rows
• inherit(key) with scope(values, fn), a field pulled from an enclosing scope, for denormalised ancestor keys (such as a multi-tenant orgId repeated on every table)

Wrap the whole build in seed(masterSeed, fn) and Tillage tracks every record it creates, in order, so the result is a coherent dataset instead of a pile of disconnected rows.

Inherited keys for multi-tenant schemas

Real schemas often denormalise an ancestor key onto every table. Declare it once with scope and let descendants pull it with inherit, instead of passing it as an override to every build:

const customer = defineFactory('customers', ({ faker }) => ({
  orgId: inherit('orgId'),
  name: faker.person.fullName(),
}), { id: 'cuid' });

seed(42, () => {
  const org = organization.build();
  scope({ orgId: org.id }, () => {
    const c = customer.build();
    scope({ customerId: c.id }, () => pool.buildList(2)); // pool inherits orgId + customerId
  });
});

Declare each relationship on one side only. Use hasMany on the parent with a plain foreign key field on the child (such as userId: 0, which the parent fills in), or use belongsTo on the child, but not both for the same relationship. Declaring both makes belongsTo build a standalone parent that the hasMany override then replaces, so you get extra parent rows.

Determinism and ordering

Output is deterministic for a given seed: the same masterSeed always produces the same data, field values included. Entities are exported in insertion order, parents before children, so toJSON() and toSQL() produce output that applies cleanly, no manual reordering of inserts required.