Seed Client API

The Seed Client API reference documentation is based on the following PostgreSQL database schema and seed.config.ts configuration file:

seed.config.ts


import { SeedPostgres } from "@snaplet/seed/adapter-postgres";
import { defineConfig } from "@snaplet/seed/config";
import postgres from "postgres";
export default defineConfig({
  adapter: () => {
    const client = postgres(process.env.DATABASE_URL);
    return new SeedPostgres(client);
  },
  alias: {
    inflection: true,
  },
});

`createSeedClient`

Type: (options?: SeedClientOptions) => Promise<SeedClient>

Create a new Seed Client instance.

Example


import { createSeedClient } from "@snaplet/seed";
const seed = await createSeedClient();

`adapter`

Type: DatabaseClient

Overrides the adapter defined in the seed.config.ts configuration file.

Example


import { SeedPostgres } from "@snaplet/seed/adapter-postgres";
import postgres from "postgres";
const client = postgres(process.env.DATABASE_URL);
const seed = await createSeedClient({
  adapter: new SeedPostgres(client),
});

`connect`

Type: boolean

If true, the Seed Client will apply the connect option to every plan.

Example


const seed = await createSeedClient({
  connect: true,
});
await seed.users((x) => x(2));
// these posts will be connected to the users
await seed.posts((x) => x(10));
// these posts will generate their own users, a plan's connect option overrides the client's connect option
await seed.posts((x) => x(10), { connect: false });

`dryRun`

Type: boolean

If true, the Seed Client will not execute any database operations, it will log the generated SQL queries to stdout instead.

Example


const seed = await createSeedClient({
  dryRun: true,
});

`models`

Type: UserModels

Provide custom data generation functions for the Seed Client instance.

Example


import { copycat } from "@snaplet/copycat";
const seed = await createSeedClient({
  models: {
    users: {
      data: {
        email: (ctx) => copycat.email(ctx.seed, { domain: "blog.dev" }),
      },
    },
  },
});

Models functions

Example type: (plan: Array<UserPlanInputs> | xCallback<UserPlanInputs>, options?: PlanOptions) => Promise<Store>

Seed one or more records in the database starting from the given model.

`plan`

Describes the data to seed.

You can provide the plan's inputs as a static array of inputs or more dynamically using the x function helper.

static array

Example type: Array<UserPlanInputs>

Seed a static array of a given model.

Example

Seed 3 users:


await seed.users([
  { username: "Alice" },
  { username: "Bob" },
  {},
]);

`x` function helper

Example type: (n: number | MinMaxOption, plan?: UserPlanInputs) => Array<UserPlanInputs>

Seed a given model n times.

Examples

Seed 10 users:


await seed.users((x) => x(10));

Seed between 1 and 5 users:


await seed.users((x) => x({ min: 1, max: 5 }));

Seed 3 posts with the same title:


await seed.posts((x) => x(3, {
  title: "Hello, world!",
}));

Seed 3 posts with a specific title depending on the index:


await seed.posts((x) => x(3, (ctx) => ({
  title: `Post ${ctx.index}`
})));

model plan's inputs

Example type: PostPlanInputs

Provides a description of the data to seed.

The PostPlanInputs type is an union of two types:

PostInputs: an object that describes the data to seed.
(ctx: PlanContext) => PostInputs: a callback receiving the plan's context and which returns an object that describes the data to seed.


type PlanContext = {
  index: number;
  seed: string;
  store: Store;
};
type PostPlanInputs = PostInputs | ((ctx: PlanContext) => PostInputs);

Examples

Model's plan inputs as an object:


await seed.posts([
  { title: "Hello, world!" },
]);

Model's plan inputs as a callback:


await seed.posts([
  (ctx) => ({ title: `Hello, world #${ctx.index}!` }),
]);

The PostInputs type is a record of the model's fields. The fields can be scalar fields or relationships (parents or children fields).


type FieldContext = {
  // the scalar fields already generated for this model
  data: Partial<PostScalarFields>;
  seed: string;
  store: Store;
};
type ParentContext<T> = {
  // the parent field can be marked as connected
  // it won't be created in this case but its ids will be used by the current model to satisfy the relationship
  connect: (modelData: T) => Connect<T>;
  seed: string;
  store: Store;
};
type UserInputs = {
  // scalar fields
  id?: string | ((ctx: FieldContext) => string | Promise<string>);
  title?: string | ((ctx: FieldContext) => string | Promise<string>);
  content?: string | ((ctx: FieldContext) => string | Promise<string>);
  // relationship (parent field)
  author?: UserInputs | (ctx: ParentContext<UserInputs>) => UserInputs;
  // relationship (child fields)
  comments?: Array<CommentPlanInputs> | xCallback<CommentPlanInputs>;
};

Examples

Scalar field as a string:


await seed.posts([
  { title: (ctx) => "Hello, world!" },
]);

Scalar field as a callback:


await seed.posts([
  {
    title: "Hello, world!",
    content: (ctx) => `The title of this post is "${ctx.data.title}"`,
  },
]);

Scalar field as an async callback:


await seed.posts([
  {
    title: async (ctx) => {
      return await fetchTitle(ctx.seed);
    },
  },
]);

Parent field as an object:


await seed.posts([
  {
    author: { username: "Snappy" },
  }
]);

Parent field as a callback:


await seed.users([{}]);
await seed.posts([
  {
    author: (ctx) => ctx.connect(seed.$store.users[0]),
  }
]);

Child field as a static array:


await seed.posts([
  {
    comments: [
      { title: "Very interesting!" },
      { title: "It's Internet so I disagree!" },
    ],
  },
]);

Child field as a callback:


await seed.posts([
  {
    comments: (x) => x(2),
  },
]);

`options`

Provides additional options for the plan.

`connect`

Type: true | Partial<Store>

Connects the missing relationships to one of the corresponding models in the provided store.

If true, the relationships will be connected to the Seed Client instance's $store.

Examples

Connect 10 posts to 2 previously seeded users:


await seed.users((x) => x(2));
await seed.posts((x) => x(10), {
  connect: true,
});

Connect 10 posts to one particular user:


const store = await seed.users((x) => x(2));
await seed.posts((x) => x(10), {
  connect: { users: [store.users[0]] },
});

`models`

Type: UserModels

Provides custom data generation functions for the plan.

Example


import { copycat } from "@snaplet/copycat";
await seed.users((x) => x(2), {
  models: {
    users: {
      data: {
        email: (ctx) => copycat.email(ctx.seed, { domain: "snaplet.dev" }),
      },
    },
  },
});

`seed`

Type: string

Provides a custom seed for the plan.

Example


await seed.users((x) => x(2), {
  seed: 'snappy',
});

Client functions

`$resetDatabase`

Type: (selectConfig?: SelectConfig) => Promise<void>

Reset the database by deleting all rows in given tables.

You can provide a custom select configuration to filter the tables to truncate.

Examples

Truncate all the tables:


await seed.$resetDatabase();

Truncate all the tables except the public._prisma_migrations table:


await seed.$resetDatabase([
  "!public._prisma_migrations",
]);

Client properties

`$store`

Type: Store

The store is an object containing all the seeded data so far for each model.

Example


await seed.users((x) => x(2));
// [{ id: '...', username: 'Alice' }, { id: '...', username: 'Bob' }]
console.log(seed.$store.users);

Seed CLI Release Notes

Seed Client API

createSeedClient

adapter

connect

dryRun

models

Models functions

plan

static array

x function helper

model plan's inputs

options

connect

models

seed

Client functions

$resetDatabase

Client properties

$store

`createSeedClient`

`adapter`

`connect`

`dryRun`

`models`

`plan`

`x` function helper

`options`

`connect`

`models`

`seed`

`$resetDatabase`

`$store`