Seed by Snaplet

Snaplet uses specific strategies to mimic database behavior for identifiers:

UUID Generation

For fields requiring a UUID or unique identifier, Snaplet uses a seed-based approach to ensure values are both unique and reproducible. It typically uses the copycat library to generate these values based on the current seed.

// Default UUID generation for fields requiring unique identifiers
id: ({ seed }) => copycat.uuid(seed);

Auto-Increment Fields

To manage auto-incrementing sequences without causing conflicts, Snaplet follows these steps:

1. Fetch Current Sequence Value: It retrieves the current maximum value from the database sequence.
2. Internal Sequence Management: It maintains an in-memory counter starting from that maximum value to ensure new values follow the existing sequence.
3. Committing New Rows: After seeding, Snaplet ensures the database sequence is updated to reflect the newly inserted values.

In @snaplet/seed, a "connection" refers to referencing existing data rather than creating new data. This allows you to build complex relational graphs in your seed scripts. There are four primary ways to define connections, ranging from implicit to explicit:

1. Path connect (Implicit): Connections made when a parent entity declares children. The children automatically reference the parent.
2. Plan connect: Defines a connection pool for a specific seeding function (a "plan"), allowing you to break down logic into dedicated, scoped functions.
3. Global connect: Sets default connection behavior for all plans in the seed script. This is useful for shared configuration or augmenting all rows with specific existing data.
4. Field connect: The most granular method, allowing you to connect specific columns and rows to specific existing entities.

While all connections can technically be achieved via field connect, the other methods serve as convenient shortcuts for common patterns.

Plan inputs for a model can be a static object or a callback function receiving a PlanContext.

PlanContext

• index: The current index of the record being generated.
• seed: A deterministic seed string.
• store: The current Seed Client store.

Field Contexts

When defining fields within a plan, you can use callbacks to access:

• FieldContext: Access previously generated scalar fields in the same record via ctx.data.
• ParentContext: Use ctx.connect(modelData) to satisfy a relationship by connecting to an existing record in the store without creating a new one.

// Scalar field as a callback using previously generated data
await seed.posts([
  {
    title: "Hello, world!",
    content: (ctx) => `The title of this post is "${ctx.data.title}"`,
  },
]);

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

Starting from version 0.85.0, you can use callback functions to define dynamic data for models and fields. This allows you to access the current iteration index, the unique seed for that iteration, and the data generated for previous fields.

Children fields

Callbacks receive index and seed:

await seed.posts([
  ({ index, seed }) => ({
    title: `Post #${index}`,
    content: `This post's seed is ${seed}`
  }),
]);

Parent fields

Callbacks receive seed and a connect function to explicitly link data:

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

Accessing previously generated data

Use the data parameter in a callback to access values from other fields in the same record:

await seed.users([{
  createdAt: ({ seed }) => copycat.dateString(seed),
  updateAt: ({ data }) => {
    const createdAt = new Date(data.createdAt)
    const updatedAtMs = Number(createdAt) + 60_000
    return new Date(updatedAtMs).toISOString()
  }
}])

// Example of using the 'data' parameter to create dependent fields
await seed.users([{
  createdAt: ({ seed }) => copycat.dateString(seed),
  updateAt: ({ data }) => {
    const createdAt = new Date(data.createdAt)
    const updatedAtMs = Number(createdAt) + 60_000
    return new Date(updatedAtMs).toISOString()
  }
}])

The Seed Client is auto-generated from your database schema, providing a type-safe and auto-completed experience in TypeScript. It allows you to define specific data requirements while automatically handling complex relationships.

Common patterns include:

• Generating a specific count of records: Use a function to specify the number of items.
• Providing specific field values: Pass an object to override default values (e.g., setting a specific email).
• Generating nested relationships with varying counts: Use a function within an object to define a range (min/max) for related records.

// Generate 5 posts
await seed.posts((x) => x(5))

// Create a user with a specific email
await seed.users([
  { email: 'snappy@snaplet.dev' },
])

// Create an organization with a varying number of members (between 1 and 10)
await seed.organizations([
  {
    name: 'Snaplet',
    members: (x) => x({ min: 1, max: 10 }),
  },
])