schema-seed-core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,443 @@
+import { MongoSeedConfig } from './mongo/types.js';
+export { MongoCollectionConfig, MongoFieldConfig, MongoFieldConfigObject, MongoFieldType } from './mongo/types.js';
+
+/**
+ * Normalized SQL types that map various database-specific types to a common set.
+ */
+declare enum NormalizedSqlType {
+    STRING = "string",
+    TEXT = "text",
+    INT = "int",
+    BIGINT = "bigint",
+    FLOAT = "float",
+    DECIMAL = "decimal",
+    BOOLEAN = "boolean",
+    DATE = "date",
+    DATETIME = "datetime",
+    JSON = "json",
+    UUID = "uuid",
+    ENUM = "enum",
+    BINARY = "binary",
+    OBJECTID = "objectid"
+}
+/**
+ * Metadata for a single column in a table.
+ */
+interface ColumnSchema {
+    name: string;
+    type: NormalizedSqlType;
+    /** The raw database-specific type string */
+    rawType: string;
+    nullable: boolean;
+    defaultValue?: any;
+    /** For ENUM types, the list of allowed values */
+    enumValues?: string[];
+    /** Precision for decimal/float types */
+    precision?: number;
+    /** Scale for decimal types */
+    scale?: number;
+    /** Maximum length for string/binary types */
+    maxLength?: number;
+    /** Whether this column is auto-incrementing / identity */
+    isAutoIncrement: boolean;
+    /** Documentation or comments from the database */
+    comment?: string;
+}
+/**
+ * Primary key definition.
+ */
+interface PrimaryKeySchema {
+    name?: string;
+    columns: string[];
+}
+/**
+ * Foreign key relationship definition.
+ */
+interface ForeignKeySchema {
+    name?: string;
+    /** Columns in the current table */
+    columns: string[];
+    /** Referenced table name */
+    referencedTable: string;
+    /** Referenced columns in the target table */
+    referencedColumns: string[];
+    onUpdate?: 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION';
+    onDelete?: 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION';
+}
+/**
+ * Unique constraint definition.
+ */
+interface UniqueConstraintSchema {
+    name?: string;
+    columns: string[];
+}
+/**
+ * Metadata for a single table.
+ */
+interface TableSchema {
+    name: string;
+    schema?: string;
+    columns: Record<string, ColumnSchema>;
+    primaryKey?: PrimaryKeySchema;
+    foreignKeys: ForeignKeySchema[];
+    uniqueConstraints: UniqueConstraintSchema[];
+    /** Estimated or actual row count */
+    rowCount?: number;
+    comment?: string;
+}
+/**
+ * A complete representation of the database schema as a graph of tables.
+ */
+interface SchemaGraph {
+    tables: Record<string, TableSchema>;
+}
+/**
+ * Metadata for a single MongoDB collection.
+ */
+interface MongoCollectionSchema {
+    name: string;
+    fields: Record<string, ColumnSchema>;
+    /** Mapping of field names to referenced collections and fields, e.g. { "userId": "users._id" } */
+    references?: Record<string, string>;
+}
+/**
+ * A complete representation of the MongoDB schema.
+ */
+interface MongoSchema {
+    collections: Record<string, MongoCollectionSchema>;
+}
+/**
+ * A batch of data to be inserted into a table.
+ */
+interface SeedBatch {
+    tableName: string;
+    rows: Record<string, any>[];
+}
+/**
+ * The execution plan for seeding the database.
+ */
+interface SeedPlan {
+    /** The order in which tables should be seeded to satisfy foreign key constraints */
+    insertOrder: string[];
+    /** Grouped batches for execution */
+    batches: SeedBatch[];
+    /** Mapping of virtual IDs to actual database IDs for resolving references */
+    referencesMap: Map<string, any>;
+}
+type OverrideFunction = (ctx: {
+    i: number;
+    random: any;
+    refs: any;
+}) => any;
+interface WeightedEnumOverride {
+    enum: any[];
+    weights?: number[];
+}
+interface DateBetweenOverride {
+    dateBetween: [string | Date, string | Date];
+}
+type ColumnOverride = OverrideFunction | WeightedEnumOverride | DateBetweenOverride | any;
+type TableOverrides = Record<string, ColumnOverride>;
+interface Hooks {
+    beforeInsert?: (table: string, rows: any[]) => any[] | Promise<any[]>;
+    afterInsert?: (table: string, result: {
+        insertedCount: number;
+        durationMs: number;
+    }) => void | Promise<void>;
+}
+interface Plugin {
+    name: string;
+    overrides?: Record<string, TableOverrides>;
+    generators?: Record<string, (ctx: any) => any>;
+    hooks?: Hooks;
+}
+/**
+ * Options for the seeding process.
+ */
+interface SeedOptions {
+    /** Number of rows to generate per table (can be a global number or per-table map) */
+    rows?: number | Record<string, number>;
+    /** Seed for the random number generator to ensure reproducibility */
+    seed?: number | string;
+    /** If true, only show what would happen without executing any writes */
+    dryRun?: boolean;
+    /** Number of rows to insert in a single batch */
+    batchSize?: number;
+    /** Safety flag to allow running against production environments */
+    allowProduction?: boolean;
+    /** If true, also seed parent tables required by foreign keys even if not explicitly requested */
+    withParents?: boolean;
+    /** If true, truncate tables before seeding */
+    truncate?: boolean;
+    /** Specific tables to include in the seeding process */
+    includeTables?: string[];
+    /** Specific tables to exclude from the seeding process */
+    excludeTables?: string[];
+    /** Custom overrides for specific tables and columns */
+    overrides?: Record<string, TableOverrides>;
+    /** Lifecycle hooks */
+    hooks?: Hooks;
+    /** List of plugins to load */
+    plugins?: (string | Plugin)[];
+}
+interface RunnerContext {
+    generators: Record<string, (ctx: any) => any>;
+    inferGenerator: (columnName: string, sqlType: any) => {
+        generatorId: string;
+        options?: any;
+    };
+    overrides?: Record<string, any>;
+}
+/**
+ * Detailed report of the seeding operation's effects.
+ */
+interface EffectReport {
+    success: boolean;
+    /** Total time taken in milliseconds */
+    durationMs: number;
+    /** Stats per table */
+    tables: Record<string, {
+        insertedCount: number;
+        error?: string;
+        durationMs: number;
+    }>;
+    /** Any global errors that occurred during the process */
+    errors: Error[];
+}
+
+/**
+ * A deterministic pseudo-random number generator (PRNG) using the Mulberry32 algorithm.
+ */
+declare class Random {
+    private state;
+    constructor(seed: number | string);
+    private hashString;
+    next(): number;
+    nextInt(min: number, max: number): number;
+    pick<T>(array: T[], weights?: number[]): T;
+    boolean(probability?: number): boolean;
+}
+
+/**
+ * Base interface for all database adapters.
+ */
+interface DbAdapter {
+    /** Establish connection to the database */
+    connect(): Promise<void>;
+    /** Close the database connection */
+    disconnect(): Promise<void>;
+    /** Start a new transaction */
+    begin(): Promise<void>;
+    /** Commit the current transaction */
+    commit(): Promise<void>;
+    /** Rollback the current transaction */
+    rollback(): Promise<void>;
+}
+/**
+ * Adapter interface for SQL-based databases (Postgres, MySQL, SQLite, etc.)
+ */
+interface SqlAdapter extends DbAdapter {
+    /**
+     * Introspect the database to build a SchemaGraph.
+     */
+    introspectSchema(): Promise<SchemaGraph>;
+    /**
+     * Insert a batch of rows into a table.
+     * @param batch The batch of data to insert
+     */
+    insertBatch(batch: SeedBatch): Promise<void>;
+    /**
+     * Truncate the specified tables.
+     * @param tableNames List of tables to truncate
+     */
+    truncateTables(tableNames: string[]): Promise<void>;
+    /**
+     * Capabilities and flags for the specific SQL dialect.
+     */
+    readonly capabilities: {
+        /** Supports native ENUM types */
+        enums: boolean;
+        /** Supports deferrable constraints (e.g., Postgres) */
+        deferrableConstraints: boolean;
+        /** Supports RETURNING clause for inserted IDs */
+        returning: boolean;
+        /** Requires explicit IDENTITY_INSERT ON for manual ID insertion (e.g., MSSQL) */
+        identityInsert: boolean;
+    };
+}
+/**
+ * Adapter interface for MongoDB.
+ */
+interface MongoAdapter extends DbAdapter {
+    /**
+     * Introspect collections and their schemas if possible.
+     */
+    introspectCollections?(): Promise<any>;
+    /**
+     * Insert many documents into a collection.
+     * @param collection Name of the collection
+     * @param documents Array of documents to insert
+     */
+    insertMany(collection: string, documents: any[]): Promise<void>;
+    /**
+     * Get the JSON Schema validator for a collection if it exists.
+     * @param collection Name of the collection
+     */
+    getValidatorSchema?(collection: string): Promise<any>;
+    /**
+     * Truncate (delete all documents from) the specified collections.
+     * @param collections List of collection names
+     */
+    truncateCollections?(collections: string[]): Promise<void>;
+}
+
+/**
+ * Registry to track and enforce uniqueness for generated values.
+ */
+declare class UniquenessRegistry {
+    private registry;
+    /**
+     * Generates a unique key for a table and column.
+     */
+    private getRegistryKey;
+    /**
+     * Attempts to generate a unique value using a generator function.
+     * If the generated value is already in the registry, it retries up to `maxRetries` times.
+     * If it still fails, it uses a deterministic fallback.
+     *
+     * @param table Table name
+     * @param column Column name
+     * @param generator Function that generates a value
+     * @param maxRetries Maximum number of retries before fallback
+     * @returns A unique value
+     */
+    ensureUnique<T>(table: string, column: string, generator: () => T | Promise<T>, maxRetries?: number): Promise<T>;
+    /**
+     * Clears the registry for a specific table/column or all.
+     */
+    clear(table?: string, column?: string): void;
+}
+
+/**
+ * Helper to redact sensitive information from reports and logs.
+ */
+declare class Redactor {
+    private static readonly SENSITIVE_PATTERNS;
+    /**
+     * Checks if a column name is considered sensitive.
+     */
+    static isSensitive(columnName: string): boolean;
+    /**
+     * Redacts sensitive values in a row object.
+     * @param row The row data to redact
+     * @returns A new object with sensitive values replaced by a placeholder
+     */
+    static redactRow(row: Record<string, any>): Record<string, any>;
+    /**
+     * Redacts sensitive values in a list of rows.
+     */
+    static redactRows(rows: Record<string, any>[]): Record<string, any>[];
+}
+
+interface DependencyNode {
+    tableName: string;
+    dependencies: Set<string>;
+    dependents: Set<string>;
+}
+declare class DependencyGraph {
+    nodes: Map<string, DependencyNode>;
+    constructor(schema: SchemaGraph);
+    getNodes(): DependencyNode[];
+    getNode(tableName: string): DependencyNode | undefined;
+}
+
+interface TopoSortResult {
+    order: string[];
+    cycles: string[][];
+}
+/**
+ * Performs a topological sort on the dependency graph.
+ * Uses Kahn's algorithm or DFS-based approach. Here we use DFS for easier cycle path extraction.
+ */
+declare function topologicalSort(graph: DependencyGraph): TopoSortResult;
+
+interface CycleResolution {
+    resolved: boolean;
+    strategy?: 'NULLABLE_FK' | 'DEFERRABLE';
+    breakingTable?: string;
+    breakingColumn?: string;
+}
+/**
+ * Attempts to resolve cycles in the dependency graph.
+ */
+declare function resolveCycles(cycles: string[][], schema: SchemaGraph, supportsDeferrable: boolean): CycleResolution[];
+
+declare function createSeedPlan(schema: SchemaGraph, options: SeedOptions, supportsDeferrable?: boolean): SeedPlan;
+/**
+ * Heuristic to identify if a table is likely a join table.
+ */
+declare function isJoinTable(table: TableSchema): boolean;
+
+/**
+ * Registry to store and retrieve primary key values for foreign key resolution.
+ */
+declare class ReferenceRegistry {
+    private refs;
+    /**
+     * Records an inserted primary key for a table.
+     */
+    addReference(table: string, pk: any): void;
+    /**
+     * Picks a random primary key from the specified table.
+     */
+    getRandomReference(table: string, random: Random): any;
+    /**
+     * Returns all recorded references for a table.
+     */
+    getReferences(table: string): any[];
+    clear(): void;
+}
+
+interface GenerationContext {
+    random: Random;
+    uniqueness: UniquenessRegistry;
+    refs: ReferenceRegistry;
+    /** Current row index in the batch */
+    i: number;
+    /** Map of column name or table.column to a specific generator function */
+    overrides?: Record<string, any>;
+    /** Map of generator IDs to their implementation */
+    generators: Record<string, (ctx: any) => any>;
+    /** Function to infer generator ID from column metadata */
+    inferGenerator: (columnName: string, sqlType: NormalizedSqlType) => {
+        generatorId: string;
+        options?: any;
+    };
+}
+/**
+ * Generates multiple rows for a table.
+ */
+declare function generateRows(table: TableSchema, count: number, context: Omit<GenerationContext, 'i'>): Promise<Record<string, any>[]>;
+/**
+ * Generates a single row for a table.
+ */
+declare function generateRow(table: TableSchema, context: GenerationContext): Promise<Record<string, any>>;
+
+declare function runSeedSql(adapter: SqlAdapter, schema: any, // SchemaGraph
+plan: SeedPlan, options: SeedOptions, context: RunnerContext): Promise<EffectReport>;
+
+declare function runSeedMongo(adapter: MongoAdapter, config: MongoSeedConfig, options: {
+    dryRun?: boolean;
+    allowProduction?: boolean;
+} | undefined, context: RunnerContext): Promise<EffectReport>;
+
+declare function loadPlugins(options: SeedOptions, context: RunnerContext): Promise<void>;
+
+declare function reportToConsole(report: EffectReport): void;
+
+declare function reportToJson(report: EffectReport): string;
+
+declare const version = "0.0.1";
+declare function defineSeed(options: SeedOptions): SeedOptions;
+
+export { type ColumnOverride, type ColumnSchema, type CycleResolution, type DateBetweenOverride, type DbAdapter, DependencyGraph, type DependencyNode, type EffectReport, type ForeignKeySchema, type GenerationContext, type Hooks, type MongoAdapter, type MongoCollectionSchema, type MongoSchema, MongoSeedConfig, NormalizedSqlType, type OverrideFunction, type Plugin, type PrimaryKeySchema, Random, Redactor, ReferenceRegistry, type RunnerContext, type SchemaGraph, type SeedBatch, type SeedOptions, type SeedPlan, type SqlAdapter, type TableOverrides, type TableSchema, type TopoSortResult, type UniqueConstraintSchema, UniquenessRegistry, type WeightedEnumOverride, createSeedPlan, defineSeed, generateRow, generateRows, isJoinTable, loadPlugins, reportToConsole, reportToJson, resolveCycles, runSeedMongo, runSeedSql, topologicalSort, version };