@seedts/types

Core TypeScript types and interfaces for SeedTS

This package contains all the core TypeScript type definitions and interfaces used throughout the SeedTS ecosystem. It has zero runtime dependencies and serves as the foundation for type safety across all SeedTS packages.

Installation

pnpm add @seedts/types

Note: This package is automatically included when you install the main seedts package. You typically only need to install it directly if you're building custom adapters or extensions.

Overview

The @seedts/types package provides TypeScript types for:

• Seed Definitions - Types for defining seeds and their configuration
• Adapters - Interface for database adapters
• Execution Context - Context available during seed execution
• Errors - Custom error types for better error handling
• Configuration - Configuration options for executors and seeds

Key Types

SeedAdapter

The core interface that all database adapters must implement:

import type { SeedAdapter } from '@seedts/types';

type SeedAdapter<T = any> = {
  name: string;
  insert(tableName: string, data: T[]): Promise<T[]>;
  update(tableName: string, data: T[]): Promise<T[]>;
  delete(tableName: string, ids: any[]): Promise<void>;
  beginTransaction(): Promise<void>;
  commit(): Promise<void>;
  rollback(): Promise<void>;
  query(tableName: string, conditions?: any): Promise<T[]>;
  close?(): Promise<void>;
};

SeedDefinition

Type for seed configuration:

import type { SeedDefinition } from '@seedts/types';

type SeedDefinition<T = any> = {
  name: string;
  adapter: SeedAdapter<T>;
  data?: T[];
  factory?: (context: ExecutionContext) => Promise<T[]> | T[];
  dependsOn?: string | string[];
  onConflict?: 'skip' | 'update' | 'error';
  hooks?: SeedHooks<T>;
};

ExecutionContext

Context available during seed execution:

import type { ExecutionContext } from '@seedts/types';

type ExecutionContext = {
  index: number;
  count: number;
  seedName: string;
  getSeed(name: string): Promise<any[]>;
  getInsertedData(seedName: string): any[];
  metadata: Record<string, any>;
};

SeedHooks

Lifecycle hooks for seeds:

import type { SeedHooks } from '@seedts/types';

type SeedHooks<T = any> = {
  beforeInsert?: (data: T[]) => Promise<T[]> | T[];
  afterInsert?: (data: T[], inserted: T[]) => Promise<void> | void;
  onSuccess?: (data: T[], metadata: ExecutionMetadata) => Promise<void> | void;
  onError?: (error: Error) => Promise<void> | void;
};

Error Types

Custom error types for better error handling:

import type {
  SeedError,
  SeedValidationError,
  SeedExecutionError,
  SeedDependencyError,
} from '@seedts/types';

Usage

Creating Type-Safe Seeds

import type { SeedDefinition, SeedAdapter } from '@seedts/types';

type User = {
  id?: number;
  email: string;
  name: string;
  role: string;
};

const userSeed: SeedDefinition<User> = {
  name: 'users',
  adapter: myAdapter,
  factory: async (ctx) => {
    return Array.from({ length: 100 }, (_, i) => ({
      email: `user${i}@example.com`,
      name: `User ${i}`,
      role: 'user',
    }));
  },
};

Implementing Custom Adapters

import type { SeedAdapter } from '@seedts/types';

export class MyCustomAdapter implements SeedAdapter {
  name = 'my-custom-adapter';

  async insert<T>(tableName: string, data: T[]): Promise<T[]> {
    // Implementation
    return data;
  }

  async update<T>(tableName: string, data: T[]): Promise<T[]> {
    // Implementation
    return data;
  }

  async delete(tableName: string, ids: any[]): Promise<void> {
    // Implementation
  }

  async beginTransaction(): Promise<void> {
    // Implementation
  }

  async commit(): Promise<void> {
    // Implementation
  }

  async rollback(): Promise<void> {
    // Implementation
  }

  async query<T>(tableName: string, conditions?: any): Promise<T[]> {
    // Implementation
    return [];
  }
}

Using Execution Context

import type { ExecutionContext } from '@seedts/types';

const factory = async (ctx: ExecutionContext) => {
  // Access execution context
  console.log(`Generating record ${ctx.index + 1} of ${ctx.count}`);

  // Get data from other seeds
  const users = await ctx.getSeed('users');

  // Return generated data
  return {
    userId: users[ctx.index % users.length].id,
    content: `Post ${ctx.index}`,
  };
};

Type Exports

Main Types

export type {
  // Adapter types
  SeedAdapter,
  AdapterConfig,

  // Seed definition types
  SeedDefinition,
  SeedConfig,
  SeedHooks,

  // Execution types
  ExecutionContext,
  ExecutionMetadata,
  ExecutionResult,
  ExecutorConfig,

  // Data types
  ConflictStrategy,
  SeedData,

  // Error types
  SeedError,
  SeedValidationError,
  SeedExecutionError,
  SeedDependencyError,
  SeedAdapterError,
};

API Documentation

For detailed API documentation, visit:

• Full Documentation
• Adapter Guide
• Type Safety Guide

Related Packages

• @seedts/core - Core execution engine
• @seedts/adapters - Base adapter classes
• seedts - Main convenience package

Contributing

Contributions are welcome! Please see our Contributing Guide.

License

MIT © SeedTS Contributors