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

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.

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.