seedts

v0.1.1

Published

3 months ago

Type-safe database seeding for TypeScript with React-like JSX syntax

0High
0Medium
0Low

dariobr91

seedts seeding database typescript jsx orm testing fixtures

SeedTS

Type-safe database seeding for TypeScript with React-like JSX syntax

SeedTS is a modern, type-safe database seeding library for TypeScript. It provides a clean, declarative API for defining and executing database seeds with full TypeScript support.

Features

🎯 Type-Safe - Full TypeScript support with type inference
⚛️ JSX Syntax - Familiar React-like JSX for declarative seed definitions
🔌 Database Agnostic - Works with any database through adapters
🚀 Performance - Batch processing, parallel execution, and streaming
🎨 Flexible - Conditional seeding, transformers, hooks, and dependencies
🧪 Testing Tools - Snapshot testing, deterministic seeding, test helpers

Installation

# Using pnpm
pnpm add seedts

# Using npm
npm install seedts

# Using yarn
yarn add seedts

Quick Start

1. Install a database adapter

pnpm add @seedts/adapter-postgresql
# or @seedts/adapter-mysql, @seedts/adapter-sqlite, etc.

2. Configure TypeScript

Add JSX support to your tsconfig.json:

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "seedts"
  }
}

3. Create your first seed

// seeds/users.seed.tsx
import { Seed, Action, Entity, Attribute } from 'seedts/jsx-runtime';
import { PostgreSQLAdapter } from '@seedts/adapter-postgresql';
import { Pool } from 'pg';

const pool = new Pool({ /* your config */ });
const adapter = new PostgreSQLAdapter(pool);

export const UsersSeed = (
  <Seed name="users" adapter={adapter}>
    <Action count={100}>
      <Entity>
        <Attribute
          name="email"
          factory={(ctx) => `user${ctx.index}@example.com`}
        />
        <Attribute
          name="name"
          factory={(ctx) => `User ${ctx.index}`}
        />
        <Attribute
          name="role"
          factory={() => 'user'}
        />
      </Entity>
    </Action>
  </Seed>
);

4. Run your seeds

import { Executor } from 'seedts';
import { UsersSeed } from './seeds/users.seed';

const executor = new Executor([UsersSeed]);

const results = await executor.execute({
  parallel: false,
  transaction: true,
});

console.log('Seeding complete!', results);

Using Faker (Optional)

For more realistic data, install the Faker integration:

pnpm add @seedts/faker

Use it in your seeds:

import { faker } from '@seedts/faker';

<Entity>
  <Attribute name="email" factory={faker.email()} />
  <Attribute name="firstName" factory={faker.firstName()} />
  <Attribute name="lastName" factory={faker.lastName()} />
  <Attribute name="age" factory={faker.int({ min: 18, max: 80 })} />
</Entity>

Using the CLI (Optional)

Install the CLI for a better developer experience:

pnpm add -D @seedts/cli

Add scripts to your package.json:

{
  "scripts": {
    "seed": "seedts run",
    "seed:list": "seedts list",
    "seed:generate": "seedts generate"
  }
}

Run your seeds:

pnpm seed

Available Packages

This is a convenience package that includes the core SeedTS functionality. For advanced use cases, you can install individual packages:

@seedts/types - Core TypeScript types and interfaces
@seedts/core - Core execution engine
@seedts/adapters - Base adapter classes
@seedts/cli - Command-line interface
@seedts/jsx-runtime - JSX runtime (included automatically)
@seedts/faker - Faker.js integration
@seedts/testing - Testing utilities
@seedts/performance - Performance tools
@seedts/import - Import/export utilities
@seedts/introspect - Database introspection

Database Adapters

@seedts/adapter-postgresql - PostgreSQL adapter
@seedts/adapter-mysql - MySQL adapter
@seedts/adapter-sqlite - SQLite adapter
@seedts/adapter-prisma - Prisma ORM adapter

Documentation

For full documentation, visit https://seedts.dev

Examples

With Dependencies

<Seed name="users" adapter={adapter}>
  <Action count={50}>
    <UserEntity />
  </Action>
</Seed>

<Seed name="posts" dependsOn="users" adapter={adapter}>
  <Action count={100}>
    <PostEntity />
  </Action>
</Seed>

With Conditional Seeding

<Action
  run={process.env.NODE_ENV === 'development'}
  count={50}
>
  <UserEntity />
</Action>

With Transformers

<Attribute
  name="password"
  factory={() => 'password123'}
  transform={hashPassword}
/>

With Hooks

<Seed
  name="users"
  adapter={adapter}
  beforeInsert={(data) => {
    console.log(`Inserting ${data.length} users`);
    return data;
  }}
  onSuccess={(data, metadata) => {
    console.log(`Done! Duration: ${metadata.duration}ms`);
  }}
>
  <Action count={100}>
    <UserEntity />
  </Action>
</Seed>