Test data that fits together, every run.

• Whole graphs, not loose objects

  Ask for “an org with 2 users, one project with 5 tasks and a cancelled subscription”. Foreign keys, ids and “assignee belongs to the same org” come from the definitions.

• Unique constraints

  Single, composite and foreign-key uniqueness, with deterministic regeneration of collisions and an error when an override causes one.

• Definitions checked up front

  Missing targets and unbounded cycles are reported all at once when you define fixtures, not halfway through a test run.

• Per-record random streams

  Each record's stream comes from the seed plus its place in the graph, so editing one entity doesn't reshuffle unrelated data.

• Atomic creates

  If anything in a create() throws, the world is left exactly as it was. Dangling foreign keys throw instead of slipping through.

• Zero dependencies, strict types

  No database, no runtime packages. Record types, foreign keys, with trees, overrides and scenarios are all inferred. ESM and CommonJS, Node ≥ 18.

Output depends on the seed, your definitions and the order of your calls. Read how determinism works →

1. 1

   Define the schema

   Entities, unique keys and relations, with fields from seq, rng and now.

   ts

   import { belongsTo, defineFixtures, entity, hasMany } from "fixtureflow";
   
   export const fixtures = defineFixtures({
     organization: entity({
       fields: ({ seq, rng }) => ({ name: `Org ${seq}`, slug: `org-${rng.string(6)}` }),
       unique: ["slug"],
       hasMany: {
         users: hasMany("user", { via: "organization", count: 3 }),
         projects: hasMany("project", { via: "organization", count: 2 }),
         subscriptions: hasMany("subscription", { via: "organization", count: 1 }),
       },
     }),
     user: entity({
       fields: ({ seq }) => ({ email: `user${seq}@example.test` }),
       unique: ["email"],
       belongsTo: { organization: belongsTo("organization") },
     }),
     project: entity({
       fields: ({ seq }) => ({ title: `Project ${seq}` }),
       belongsTo: { organization: belongsTo("organization") },
       hasMany: { tasks: hasMany("task", { via: "project", count: [2, 4] }) },
     }),
     task: entity({
       fields: ({ rng }) => ({ status: rng.pick(["todo", "doing", "done"] as const) }),
       belongsTo: {
         project: belongsTo("project"),
         // an assignee picked from the users created in the same create() call
         assignee: belongsTo("user", { optional: true, rate: 0.8, reuse: "scope" }),
       },
     }),
     subscription: entity({
       fields: () => ({ plan: "team" as "team" | "free", status: "active" as "active" | "cancelled" }),
       belongsTo: { organization: belongsTo("organization") },
       unique: ["organizationId"],
     }),
   });

2. 2

   Use it in a test

   Works in Vitest, Jest and node:test. Override only what the test cares about.

   ts

   import { beforeEach, expect, it } from "vitest";
   import { fixtures } from "./fixtures";
   
   let world: ReturnType<typeof fixtures.world>;
   beforeEach(() => {
     world = fixtures.world({ seed: "vitest" }); // isolated, reproducible
   });
   
   it("a cancelled team has no renewal", () => {
     const org = world.create("organization", {
       with: { subscriptions: { overrides: { status: "cancelled" } } },
     });
     const [subscription] = world.children("organization", org, "subscriptions");
     expect(subscription?.status).toBe("cancelled");
   });

3. 3

   Persist, if you want

   The core never touches a database. Rows come out parents first, batched by entity.

   ts

   import { fixtures } from "./fixtures";
   
   declare const db: { insert(table: string, rows: object[]): Promise<void> };
   
   const world = fixtures.world({ seed: 7 });
   world.create("organization");
   
   // Rows arrive in creation order, so parents are always written before their children.
   await world.persist(async (entity, rows) => {
     await db.insert(entity, rows);
   });

• belongsToMany-to-one. Required by default: a missing parent is generated. Optional with a rate.
• hasManyOne-to-many. count is a number or [min, max]; lazy children are generated on first load.
• uniqueSingle or composite keys. Collisions regenerate from a fresh deterministic stream.
• reusePick an existing parent from this create() call (scope) or the whole world instead of making one.
• scenariosNamed, typed presets. Plain functions over a world, so no business domain lives in the library.
• persistHands you rows in creation order, parents first, so you can insert them with any client.

See every relationship option →