ddlseed 0.0.0-stage → 0.1.0

package/dist/generator.js

@@ -0,0 +1,381 @@
+import { Faker, en } from '@faker-js/faker';
+import { topologicalOrder } from './graph.js';
+import { DdlSeedError } from './types.js';
+const REF_DATE_DEFAULT = new Date('2026-01-01T00:00:00Z');
+const MAX_ATTEMPTS = 40;
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+export function validateSchema(schema) {
+    const byKey = new Map(schema.tables.map(t => [t.key, t]));
+    const resolved = new Map();
+    for (const table of schema.tables) {
+        const colKeys = new Set(table.columns.map(c => c.key));
+        if (table.primaryKey.length === 0) {
+            throw new DdlSeedError(`Table "${table.name}" has no primary key. ddlseed requires a primary key to keep rows consistent.`);
+        }
+        for (const pk of table.primaryKey) {
+            if (!colKeys.has(pk))
+                throw new DdlSeedError(`Table "${table.name}": primary key column "${pk}" not found.`);
+        }
+        const fks = [];
+        for (const fk of table.foreignKeys) {
+            for (const c of fk.columns) {
+                if (!colKeys.has(c))
+                    throw new DdlSeedError(`Table "${table.name}": foreign key column "${c}" not found.`);
+            }
+            const parent = byKey.get(fk.refTable.toLowerCase());
+            if (!parent) {
+                throw new DdlSeedError(`Table "${table.name}" references unknown table "${fk.refTable}".`);
+            }
+            let refCols = fk.refColumns;
+            if (refCols.length === 0) {
+                if (parent.primaryKey.length !== 1) {
+                    throw new DdlSeedError(`Table "${table.name}" references "${parent.name}" without columns, but the parent has a composite primary key. Specify the referenced columns explicitly.`);
+                }
+                refCols = parent.primaryKey;
+            }
+            const parentCols = new Set(parent.columns.map(c => c.key));
+            for (const rc of refCols) {
+                if (!parentCols.has(rc))
+                    throw new DdlSeedError(`Table "${table.name}" references unknown column "${parent.name}.${rc}".`);
+            }
+            fks.push({ columns: fk.columns, refTable: parent, refColumns: refCols });
+        }
+        resolved.set(table, fks);
+    }
+    return resolved;
+}
+// ---------------------------------------------------------------------------
+// Value generation
+// ---------------------------------------------------------------------------
+const EXACT_NAME_HINTS = {
+    state: f => f.location.state(),
+    status: f => f.helpers.arrayElement(['active', 'inactive', 'pending', 'archived']),
+    language: f => f.helpers.arrayElement(['en', 'es', 'fr', 'de', 'pt', 'it', 'ja']),
+    locale: f => f.helpers.arrayElement(['en_US', 'es_ES', 'fr_FR', 'de_DE']),
+    gender: f => f.person.sex(),
+    currency: f => f.finance.currency().code,
+    country_code: f => f.location.countryCode(),
+};
+function generateValue(col, f, ctx) {
+    const key = col.key;
+    // enum columns: pick from declared values
+    if (col.kind === 'enum' && col.enumValues.length) {
+        return f.helpers.arrayElement(col.enumValues);
+    }
+    // ---- name heuristics (exact, then contains) ----
+    const exact = EXACT_NAME_HINTS[key];
+    if (exact)
+        return exact(f);
+    if (/_id$/.test(key) && col.kind === 'int')
+        return f.number.int({ min: 1, max: Math.max(ctx.rows, 1) });
+    if (key.includes('email'))
+        return withLength(f.internet.email().toLowerCase(), col.length);
+    if (key.includes('first_name') || key === 'firstname')
+        return withLength(f.person.firstName(), col.length);
+    if (key.includes('last_name') || key === 'lastname' || key.includes('surname'))
+        return withLength(f.person.lastName(), col.length);
+    if (key === 'name' || key.includes('full_name'))
+        return withLength(f.person.fullName(), col.length);
+    if (key.includes('username') || key.includes('user_name') || key.includes('nickname') || key === 'handle')
+        return withLength(f.internet.username(), col.length);
+    if (key.includes('city') || key.includes('town'))
+        return withLength(f.location.city(), col.length);
+    if (key.includes('country'))
+        return withLength(f.location.country(), col.length);
+    if (key.includes('address') || key.includes('street'))
+        return withLength(f.location.streetAddress(), col.length);
+    if (key.includes('zip') || key.includes('postal'))
+        return withLength(f.location.zipCode(), col.length);
+    if (key.includes('phone') || key.includes('mobile') || key === 'tel')
+        return withLength(f.phone.number(), col.length);
+    if (key.includes('url') || key.includes('website') || key === 'link' || key.includes('homepage'))
+        return withLength(f.internet.url(), col.length);
+    if (key.includes('password'))
+        return withLength(f.internet.password({ length: 12 }), col.length);
+    if (key.includes('company') || key.includes('organization') || key.includes('organisation') || key.includes('brand') || key.includes('manufacturer'))
+        return withLength(f.company.name(), col.length);
+    if (key.includes('description') || key.includes('bio') || key.includes('content') || key.includes('body') || key.includes('comment') || key.includes('summary') || key.includes('excerpt'))
+        return withLength(f.lorem.paragraph(), col.length);
+    if (key.includes('title') || key.includes('subject') || key.includes('headline'))
+        return withLength(f.lorem.words({ min: 2, max: 4 }), col.length);
+    if (key === 'slug' || key.includes('slug'))
+        return f.helpers.slugify(f.lorem.words({ min: 2, max: 3 })).slice(0, col.length ?? 80);
+    if (key.includes('price') || key.includes('amount') || key.includes('total') || key.includes('balance') || key.includes('salary') || key.includes('cost') || key.includes('fee'))
+        return f.number.float({ min: 1, max: 1000, fractionDigits: 2 });
+    if (key === 'age')
+        return f.number.int({ min: 18, max: 90 });
+    if (key.includes('qty') || key.includes('quantity') || key.includes('stock') || key.includes('count'))
+        return f.number.int({ min: 1, max: 100 });
+    if (key.includes('rating'))
+        return f.number.float({ min: 0, max: 5, fractionDigits: 1 });
+    if (key.includes('uuid') || key.includes('guid'))
+        return f.string.uuid();
+    if (key.includes('token') || key.includes('hash') || key.includes('secret') || key.includes('api_key') || key === 'key')
+        return f.string.alphanumeric({ length: 32 });
+    if (key.includes('color') || key.includes('colour'))
+        return f.color.human();
+    if (key.includes('version'))
+        return `${f.number.int({ min: 1, max: 3 })}.${f.number.int({ min: 0, max: 9 })}.${f.number.int({ min: 0, max: 9 })}`;
+    if (key.includes('percent'))
+        return f.number.float({ min: 0, max: 100, fractionDigits: 1 });
+    if (key.includes('ip'))
+        return f.internet.ip();
+    if (key.includes('lat'))
+        return parseFloat(f.location.latitude({ min: -60, max: 60 }).toFixed(6));
+    if (key.includes('lon') || key.includes('lng'))
+        return parseFloat(f.location.longitude({ min: -120, max: 120 }).toFixed(6));
+    if (key.includes('code'))
+        return f.string.alphanumeric({ length: 8, casing: 'upper' });
+    if (/^is_|^has_|_enabled$|_verified$|^active$|^verified$/.test(key))
+        return f.datatype.boolean();
+    // ---- by type ----
+    switch (col.kind) {
+        case 'int':
+            return f.number.int({ min: 0, max: col.length ? Math.min(col.length, 1_000_000) : 1000 });
+        case 'float':
+            return f.number.float({ min: 0, max: 1000, fractionDigits: col.scale ?? 2 });
+        case 'bool':
+            return f.datatype.boolean();
+        case 'date':
+            return f.date.recent({ days: 730, refDate: ctx.refDate });
+        case 'datetime':
+            return f.date.recent({ days: 730, refDate: ctx.refDate });
+        case 'time': {
+            const d = f.date.recent({ days: 730, refDate: ctx.refDate });
+            return d.toISOString().slice(11, 19);
+        }
+        case 'uuid':
+            return f.string.uuid();
+        case 'json':
+            return { key: f.lorem.word(), value: f.number.int({ min: 0, max: 99 }) };
+        case 'blob':
+            return f.string.alphanumeric({ length: 16 });
+        case 'text':
+        case 'unknown':
+        default: {
+            const base = f.lorem.paragraph();
+            return withLength(base, col.length);
+        }
+    }
+}
+function withLength(v, length) {
+    if (length && length > 0 && v.length > length)
+        return v.slice(0, length);
+    return v;
+}
+export function generateData(schema, options = {}) {
+    const rowsPerTable = options.rows ?? 50;
+    const seed = options.seed ?? 42;
+    const refDateRaw = options.refDate ?? REF_DATE_DEFAULT;
+    const refDate = refDateRaw instanceof Date ? refDateRaw : new Date(refDateRaw);
+    const resolvedFks = validateSchema(schema);
+    const order = topologicalOrder(schema);
+    const f = new Faker({ locale: [en] });
+    f.seed(seed);
+    const ctx = { f, rows: rowsPerTable, refDate };
+    /** committed rows per table, keyed by table.key -> array of internal rows */
+    const committed = new Map();
+    for (const t of schema.tables)
+        committed.set(t.key, []);
+    const result = new Map();
+    for (const table of order) {
+        const fks = resolvedFks.get(table);
+        const pkSet = new Set();
+        const uniqueSets = new Map();
+        const uniqueGroups = [];
+        if (table.primaryKey.length > 1)
+            uniqueGroups.push(table.primaryKey);
+        for (const cols of table.uniqueConstraints)
+            uniqueGroups.push(cols);
+        for (const col of table.columns) {
+            if (col.unique && !uniqueGroups.some(g => g.length === 1 && g[0] === col.key)) {
+                uniqueGroups.push([col.key]);
+            }
+        }
+        for (const g of uniqueGroups)
+            uniqueSets.set(g.join('\u0000'), new Set());
+        const tableRows = [];
+        for (let i = 0; i < rowsPerTable; i++) {
+            const row = generateRow(table, fks, i, ctx, tableRows, pkSet, uniqueSets, uniqueGroups);
+            tableRows.push(row);
+            // commit: update uniqueness bookkeeping
+            if (table.primaryKey.length === 1) {
+                pkSet.add(keyOf(row, table.primaryKey[0]));
+            }
+            for (const g of uniqueGroups) {
+                const sig = tupleKey(row, g);
+                if (sig !== null)
+                    uniqueSets.get(g.join('\u0000')).add(sig);
+            }
+        }
+        committed.set(table.key, tableRows);
+        // convert internal (key-keyed) rows to output rows (name-keyed)
+        const outRows = tableRows.map(r => {
+            const o = {};
+            for (const col of table.columns)
+                o[col.name] = r[col.key];
+            return o;
+        });
+        result.set(table.key, outRows);
+    }
+    return result;
+}
+function keyOf(row, colKey) {
+    const v = row[colKey];
+    return v === null || v === undefined ? 'null' : String(v instanceof Date ? v.toISOString() : v);
+}
+function tupleKey(row, cols) {
+    const parts = [];
+    for (const c of cols) {
+        const v = row[c];
+        if (v === null || v === undefined)
+            return null; // nulls don't collide in SQL UNIQUE
+        parts.push(keyOf(row, c));
+    }
+    return parts.join('\u0000');
+}
+function generateRow(table, fks, index, ctx, committedRows, pkSet, uniqueSets, uniqueGroups) {
+    let row = draftRow(table, fks, index, ctx, committedRows, false);
+    for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+        if (satisfies(row, table, pkSet, uniqueSets, uniqueGroups))
+            return row;
+        row = draftRow(table, fks, index, ctx, committedRows, attempt > 0);
+    }
+    // deterministic fallback: force uniqueness with the row index
+    forceUnique(row, table, index, uniqueSets, uniqueGroups, table.primaryKey.length > 1 ? table.primaryKey : null);
+    return row;
+}
+function satisfies(row, table, pkSet, uniqueSets, uniqueGroups) {
+    if (table.primaryKey.length === 1) {
+        if (pkSet.has(keyOf(row, table.primaryKey[0])))
+            return false;
+    }
+    for (const g of uniqueGroups) {
+        const sig = tupleKey(row, g);
+        if (sig === null)
+            continue;
+        if (uniqueSets.get(g.join('\u0000')).has(sig))
+            return false;
+    }
+    return true;
+}
+function draftRow(table, fks, index, ctx, committedRows, isRetry) {
+    const row = {};
+    // ---- pass 1: primary key ----
+    if (table.primaryKey.length === 1) {
+        const pk = table.columns.find(c => c.key === table.primaryKey[0]);
+        if (pk.kind === 'int') {
+            row[pk.key] = index + 1; // deterministic, always unique
+        }
+        else if (!isRetry || row[pk.key] === undefined) {
+            row[pk.key] = generateValue(pk, ctx.f, ctx);
+        }
+    }
+    else {
+        for (const pkKey of table.primaryKey) {
+            const col = table.columns.find(c => c.key === pkKey);
+            if (col.kind === 'int') {
+                row[col.key] = index + 1;
+            }
+            else if (!isRetry || row[col.key] === undefined) {
+                row[col.key] = generateValue(col, ctx.f, ctx);
+            }
+        }
+    }
+    // ---- pass 2: foreign keys ----
+    for (const fk of fks) {
+        const pool = getRefPool(fk, committedRows);
+        const allNullable = fk.columns.every(c => table.columns.find(col => col.key === c).notNull === false);
+        if (pool.length === 0) {
+            if (fk.refTable.key === table.key) {
+                // self-reference with no committed rows: point the row to itself (valid once inserted)
+                const own = ownPkValuesFor(table, fk, index, row);
+                if (own === null && allNullable) {
+                    for (const c of fk.columns)
+                        row[c] = null;
+                }
+                else if (own !== null) {
+                    fk.columns.forEach((c, idx) => { row[c] = own[idx]; });
+                }
+                else {
+                    fk.columns.forEach((c, idx) => { row[c] = idx === 0 ? 1 : 1; });
+                }
+            }
+            else {
+                // referenced table produced no rows (rows=0 edge) -> null if allowed
+                if (allNullable)
+                    for (const c of fk.columns)
+                        row[c] = null;
+                else
+                    for (const c of fk.columns)
+                        row[c] = 1;
+            }
+            continue;
+        }
+        if (allNullable && ctx.f.number.int({ min: 1, max: 10 }) === 1) {
+            for (const c of fk.columns)
+                row[c] = null;
+            continue;
+        }
+        const tuple = ctx.f.helpers.arrayElement(pool);
+        fk.columns.forEach((c, idx) => { row[c] = tuple[idx]; });
+    }
+    // ---- pass 3: the rest ----
+    for (const col of table.columns) {
+        if (row[col.key] !== undefined)
+            continue;
+        const isPk = table.primaryKey.includes(col.key);
+        const nullable = !col.notNull && !isPk;
+        if (nullable && ctx.f.number.int({ min: 1, max: 10 }) === 1) {
+            row[col.key] = null;
+            continue;
+        }
+        row[col.key] = generateValue(col, ctx.f, ctx);
+    }
+    return row;
+}
+function ownPkValuesFor(table, fk, index, row) {
+    // self-FK usually references own PK
+    const vals = [];
+    for (const rc of fk.refColumns) {
+        const v = row[rc];
+        if (v === undefined)
+            return null;
+        vals.push(v);
+    }
+    return vals;
+}
+function getRefPool(fk, committedRows) {
+    return committedRows.map(r => fk.refColumns.map(rc => r[rc]));
+}
+function forceUnique(row, table, index, uniqueSets, uniqueGroups, compositePk) {
+    const groups = [...uniqueGroups];
+    if (compositePk)
+        groups.push(compositePk);
+    for (const g of groups) {
+        const sig = tupleKey(row, g);
+        if (sig === null)
+            continue;
+        const set = uniqueSets.get(g.join('\u0000'));
+        if (set && !set.has(sig))
+            continue;
+        for (const colKey of g) {
+            const col = table.columns.find(c => c.key === colKey);
+            const v = row[colKey];
+            if (typeof v === 'number')
+                row[colKey] = v + index + 1;
+            else if (typeof v === 'string')
+                row[colKey] = `${v}-${index}`;
+            else if (v instanceof Date)
+                row[colKey] = new Date(v.getTime() + index * 1000);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Convenience: ordered table names for writers
+// ---------------------------------------------------------------------------
+export function generationOrder(schema) {
+    return topologicalOrder(schema);
+}

package/dist/graph.d.ts

@@ -0,0 +1,7 @@
+import { Schema, TableDef } from './types.js';
+/**
+ * Orders tables so that every table comes after the tables its foreign keys
+ * reference (self-references are ignored). Independent tables keep their
+ * declaration order. Throws on FK cycles.
+ */
+export declare function topologicalOrder(schema: Schema): TableDef[];

package/dist/graph.js

@@ -0,0 +1,47 @@
+import { DdlSeedError } from './types.js';
+/**
+ * Orders tables so that every table comes after the tables its foreign keys
+ * reference (self-references are ignored). Independent tables keep their
+ * declaration order. Throws on FK cycles.
+ */
+export function topologicalOrder(schema) {
+    const byKey = new Map();
+    for (const t of schema.tables)
+        byKey.set(t.key, t);
+    const deps = new Map();
+    for (const t of schema.tables) {
+        const set = new Set();
+        for (const fk of t.foreignKeys) {
+            const ref = fk.refTable.toLowerCase();
+            if (ref !== t.key)
+                set.add(ref);
+        }
+        deps.set(t.key, set);
+    }
+    const order = [];
+    const emitted = new Set();
+    const remaining = [...schema.tables]; // declaration order preserved
+    while (remaining.length > 0) {
+        // find first table whose deps are all emitted
+        const idx = remaining.findIndex(t => {
+            const d = deps.get(t.key);
+            for (const dep of d) {
+                if (!byKey.has(dep)) {
+                    throw new DdlSeedError(`Table "${t.name}" references unknown table "${dep}" in a foreign key.`);
+                }
+                if (!emitted.has(dep))
+                    return false;
+            }
+            return true;
+        });
+        if (idx === -1) {
+            const stuck = remaining.map(t => t.name).join(', ');
+            throw new DdlSeedError(`Circular foreign-key dependency between tables: ${stuck}. ` +
+                'ddlseed cannot order these tables for insertion.');
+        }
+        const [t] = remaining.splice(idx, 1);
+        emitted.add(t.key);
+        order.push(t);
+    }
+    return order;
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { parseSchema, detectDialect } from './parser.js';
+export { topologicalOrder } from './graph.js';
+export { generateData, validateSchema } from './generator.js';
+export { toSql, toJson, toCsv, toCsvAll } from './writers.js';
+export { DdlSeedError } from './types.js';
+export type { ColumnDef, Dialect, ForeignKey, Row, Schema, TableDef } from './types.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { parseSchema, detectDialect } from './parser.js';
+export { topologicalOrder } from './graph.js';
+export { generateData, validateSchema } from './generator.js';
+export { toSql, toJson, toCsv, toCsvAll } from './writers.js';
+export { DdlSeedError } from './types.js';

package/dist/parser.d.ts

@@ -0,0 +1,3 @@
+import { Dialect, Schema } from './types.js';
+export declare function detectDialect(sql: string): Dialect;
+export declare function parseSchema(sql: string, dialect?: Dialect): Schema;