@zero-server/orm 0.9.1 → 0.9.2

package/lib/orm/seed/index.js

@@ -0,0 +1,18 @@
+'use strict';
+
+/**
+ * @module seed/index
+ * @description Public API for the seed subsystem.
+ *
+ * Re-exports:
+ *   - `Fake`         — static fake-data generator
+ *   - `Factory`      — model factory for defining / creating test fixtures
+ *   - `Seeder`       — base class for database seeders
+ *   - `SeederRunner` — orchestrates running multiple seeders
+ */
+
+const { Fake }                   = require('./fake');
+const { Factory }                = require('./factory');
+const { Seeder, SeederRunner }   = require('./seeder');
+
+module.exports = { Fake, Factory, Seeder, SeederRunner };

package/lib/orm/seed/rng.js

@@ -0,0 +1,71 @@
+'use strict';
+
+/**
+ * @module seed/rng
+ * @description Seeded PRNG (mulberry32) for reproducible fake data generation.
+ *              When no seed is set, falls back to Math.random so default
+ *              behaviour is indistinguishable from the original implementation.
+ *
+ * @example
+ *   const { seed, rand } = require('./rng');
+ *   seed(42);           // deterministic from here on
+ *   rand();             // always the same sequence for seed 42
+ *   seed(null);         // back to crypto-quality Math.random
+ */
+
+/**
+ * mulberry32 — minimal, high-quality 32-bit PRNG.
+ * @param {number} s - Unsigned 32-bit integer seed.
+ * @returns {() => number} Float in [0, 1).
+ */
+function _mulberry32(s) {
+    s = s >>> 0;
+    return function () {
+        s += 0x6D2B79F5;
+        let t = s;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+
+/** FNV-1a string → unsigned 32-bit integer. */
+function _hashString(str) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < str.length; i++) {
+        h ^= str.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return h >>> 0;
+}
+
+let _rng  = Math.random.bind(Math);
+let _seed = null;
+
+/** Return a random float in [0, 1). */
+function rand() { return _rng(); }
+
+/**
+ * Set a deterministic seed.  Pass `null` / `undefined` to reset to Math.random.
+ *
+ * @param {number|string|null} [value] - Value to set.
+ * @returns {number|null} The numeric seed that was applied (or null if reset).
+ */
+function seed(value) {
+    if (value === undefined || value === null) {
+        _rng  = Math.random.bind(Math);
+        _seed = null;
+    } else {
+        const n = typeof value === 'number'
+            ? (value >>> 0)
+            : _hashString(String(value));
+        _seed = n;
+        _rng  = _mulberry32(n);
+    }
+    return _seed;
+}
+
+/** @returns {number|null} Active numeric seed, or null when using Math.random. */
+function getSeed() { return _seed; }
+
+module.exports = { rand, seed, getSeed };

package/lib/orm/seed/seeder.js

@@ -0,0 +1,125 @@
+'use strict';
+
+/**
+ * @module seed/seeder
+ * @description Base Seeder class and SeederRunner for orchestrating database
+ *              seeding operations.
+ *
+ * @example
+ *   class UserSeeder extends Seeder {
+ *       async run(db) {
+ *           const factory = new Factory(User);
+ *           factory.define({ name: () => Fake.fullName(), email: () => Fake.email() });
+ *           await factory.count(50).create();
+ *       }
+ *   }
+ *
+ *   const runner = new SeederRunner(db);
+ *   await runner.run(UserSeeder, PostSeeder);
+ */
+
+const log = require('../../debug')('zero:seed');
+
+// ================================================================
+//  Seeder base class
+// ================================================================
+
+/**
+ * Extend this class to create a seeder.  Override `run(db)` with your
+ * seeding logic.
+ */
+class Seeder
+{
+    /**
+     * Run the seeder.  Must be overridden in subclasses.
+     *
+     * @param {import('../index').Database} db - Database instance.
+     * @returns {Promise<void>}
+     */
+    async run(db)  // eslint-disable-line no-unused-vars
+    {
+        throw new Error(`Seeder ${this.constructor.name}: run() is not implemented`);
+    }
+}
+
+// ================================================================
+//  SeederRunner
+// ================================================================
+
+/**
+ * Orchestrates running one or more seeders against a database connection.
+ *
+ * @example
+ *   const runner = new SeederRunner(db);
+ *   await runner.run(UserSeeder, PostSeeder);
+ *   await runner.call(UserSeeder);           // single seeder
+ *   await runner.fresh(UserSeeder);          // clear then seed
+ */
+class SeederRunner
+{
+    /**
+     * @constructor
+     * @param {import('../index').Database} db - Database connection instance.
+     */
+    constructor(db)
+    {
+        this._db = db;
+    }
+
+    /**
+     * Run one or more seeder classes (or instances) in order.
+     *
+     * @param {...(Function|Function[])} seeders - Seeder classes or instances.
+     * @returns {Promise<string[]>} Names of the seeders that ran.
+     */
+    async run(...seeders)
+    {
+        const flat  = seeders.flat();
+        const names = [];
+
+        for (const SeederClass of flat)
+        {
+            const instance = typeof SeederClass === 'function'
+                ? new SeederClass()
+                : SeederClass;
+
+            const name = instance.constructor.name || 'AnonymousSeeder';
+            log('Seeding: %s', name);
+
+            await instance.run(this._db);
+            names.push(name);
+
+            log('Seeded:  %s', name);
+        }
+
+        return names;
+    }
+
+    /**
+     * Run a single seeder class or instance.
+     *
+     * @param {Function} SeederClass - Seeder class or instance to run.
+     * @returns {Promise<void>}
+     */
+    async call(SeederClass)
+    {
+        await this.run(SeederClass);
+    }
+
+    /**
+     * Clear all adapter data then run the provided seeders.
+     * Works with adapters that expose a `clear()` method (memory, json, redis).
+     *
+     * @param {...Function} seeders - Seeder classes to run after clearing.
+     * @returns {Promise<string[]>} Names of the seeders that ran.
+     */
+    async fresh(...seeders)
+    {
+        if (typeof this._db.adapter.clear === 'function')
+            await this._db.adapter.clear();
+
+        return this.run(...seeders);
+    }
+}
+
+module.exports = { Seeder, SeederRunner };

package/lib/orm/seed/unique.js

@@ -0,0 +1,68 @@
+'use strict';
+
+/**
+ * @module seed/unique
+ * @description Per-namespace deduplication tracker used by `Fake.unique()`.
+ *              Keeps a `Set` of already-returned values per key and retries
+ *              the generator until a fresh value is produced.
+ */
+
+const DEFAULT_MAX_ATTEMPTS = 1000;
+
+/**
+ * Tracks generated values per namespace so callers can guarantee uniqueness
+ * within a seeding session without maintaining external state.
+ */
+class UniqueTracker {
+    constructor() {
+        /** @type {Map<string, Set<any>>} */
+        this._store = new Map();
+    }
+
+    /**
+     * Call `fn()` repeatedly until it returns a value not yet seen under `key`.
+     *
+     * @param {string}   key            - Uniqueness namespace (e.g. `'email'`).
+     * @param {() => any} fn            - Value generator.
+     * @param {number}   [maxAttempts]  - Give up after this many retries.
+     * @returns {any} The unique generated value.
+     * @throws {Error} When the generator pool is exhausted.
+     */
+    generate(key, fn, maxAttempts = DEFAULT_MAX_ATTEMPTS) {
+        if (!this._store.has(key)) this._store.set(key, new Set());
+        const seen = this._store.get(key);
+
+        for (let i = 0; i < maxAttempts; i++) {
+            const val = fn();
+            if (!seen.has(val)) {
+                seen.add(val);
+                return val;
+            }
+        }
+
+        throw new Error(
+            `Fake.unique: exhausted ${maxAttempts} attempts for key "${key}". ` +
+            `The data pool may be too small. Call Fake.resetUnique("${key}") to start fresh.`
+        );
+    }
+
+    /**
+     * Clear uniqueness tracking.
+     * @param {string} [key] - Clear only this namespace, or all if omitted.
+     */
+    reset(key) {
+        if (key !== undefined) this._store.delete(key);
+        else this._store.clear();
+    }
+
+    /**
+     * How many unique values have been generated for a namespace.
+     * @param {string} key - Cache or storage key.
+     * @returns {number} Count of unique values tracked for the key.
+     */
+    seen(key) {
+        return this._store.has(key) ? this._store.get(key).size : 0;
+    }
+}
+
+module.exports = { UniqueTracker };

package/lib/orm/snapshot.js

@@ -0,0 +1,366 @@
+/**
+ * @module orm/snapshot
+ * @description Schema snapshot and diff engine for EF Core–style auto-generated
+ *              migrations.  Compares the current Model schemas against a stored
+ *              snapshot and produces a structured change-set that the CLI can
+ *              render into migration code.
+ *
+ * The snapshot file (_schema_snapshot.json) is a plain JSON representation of
+ * every tracked table's schema at the time the last migration was generated.
+ *
+ * @example
+ *   const { diffSnapshots, buildSnapshot } = require('./snapshot');
+ *
+ *   const current  = buildSnapshot(models);   // from Model classes
+ *   const previous = loadSnapshot(dir);       // from JSON file
+ *   const changes  = diffSnapshots(previous, current);
+ *
+ *   // changes = { tables: { created: [...], dropped: [...] },
+ *   //             columns: { added: [...], dropped: [...], altered: [...] } }
+ */
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+const SNAPSHOT_FILE = '_schema_snapshot.json';
+
+// -- Building a snapshot ----------------------------------------
+
+/**
+ * Build a normalised snapshot from an array of Model classes.
+ * Each Model must have `static table` and `static schema`.
+ *
+ * @param {Function[]} models - Array of Model subclasses.
+ * @returns {object} Snapshot keyed by table name.
+ */
+function buildSnapshot(models)
+{
+    const snap = {};
+
+    for (const M of models)
+    {
+        const table = M.table;
+        if (!table) continue;
+
+        const schema = typeof M._fullSchema === 'function'
+            ? M._fullSchema()
+            : { ...M.schema };
+
+        // Normalise each column to a serialisable form (strip functions)
+        const cols = {};
+        for (const [colName, def] of Object.entries(schema))
+        {
+            cols[colName] = _normaliseDef(def);
+        }
+
+        snap[table] = {
+            schema:     cols,
+            timestamps: !!M.timestamps,
+            softDelete: !!M.softDelete,
+        };
+    }
+
+    return snap;
+}
+
+/**
+ * Normalise a column definition to a JSON-serialisable object.
+ * Strips function defaults to `null`.
+ * @private
+ */
+function _normaliseDef(def)
+{
+    const out = {};
+    for (const [k, v] of Object.entries(def))
+    {
+        if (typeof v === 'function')      out[k] = null;           // fn defaults not serialisable
+        else if (v instanceof RegExp)     out[k] = v.source;       // match patterns
+        else                              out[k] = v;
+    }
+    return out;
+}
+
+// -- Loading / saving snapshots ---------------------------------
+
+/**
+ * Load a previously saved snapshot from disk.
+ * Returns an empty object if no file exists.
+ *
+ * @param {string} dir - Directory containing the snapshot file.
+ * @returns {object} Snapshot.
+ */
+function loadSnapshot(dir)
+{
+    const p = path.join(dir, SNAPSHOT_FILE);
+    if (!fs.existsSync(p)) return {};
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+}
+
+/**
+ * Write a snapshot to disk.
+ *
+ * @param {string} dir      - Directory to write to.
+ * @param {object} snapshot - The snapshot object.
+ */
+function saveSnapshot(dir, snapshot)
+{
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(
+        path.join(dir, SNAPSHOT_FILE),
+        JSON.stringify(snapshot, null, 4) + '\n',
+        'utf8'
+    );
+}
+
+// -- Diffing two snapshots --------------------------------------
+
+/**
+ * Diff two snapshots and return a structured change-set.
+ *
+ * @param {object} prev    - Previous snapshot (from file).
+ * @param {object} current - Current snapshot (from live models).
+ * @returns {object} `{ tables, columns }` change-set.
+ */
+function diffSnapshots(prev, current)
+{
+    const prevTables   = Object.keys(prev);
+    const currTables   = Object.keys(current);
+
+    const createdTables = currTables.filter(t => !prev[t]);
+    const droppedTables = prevTables.filter(t => !current[t]);
+    const commonTables  = currTables.filter(t => !!prev[t]);
+
+    const addedCols   = [];
+    const droppedCols = [];
+    const alteredCols = [];
+
+    for (const table of commonTables)
+    {
+        const prevCols = Object.keys(prev[table].schema);
+        const currCols = Object.keys(current[table].schema);
+
+        // New columns
+        for (const col of currCols)
+        {
+            if (!prev[table].schema[col])
+            {
+                addedCols.push({ table, column: col, def: current[table].schema[col] });
+            }
+        }
+
+        // Dropped columns
+        for (const col of prevCols)
+        {
+            if (!current[table].schema[col])
+            {
+                droppedCols.push({ table, column: col, def: prev[table].schema[col] });
+            }
+        }
+
+        // Altered columns (type or constraints changed)
+        for (const col of currCols)
+        {
+            if (prev[table].schema[col] && current[table].schema[col])
+            {
+                if (!_defsEqual(prev[table].schema[col], current[table].schema[col]))
+                {
+                    alteredCols.push({
+                        table,
+                        column: col,
+                        from:   prev[table].schema[col],
+                        to:     current[table].schema[col],
+                    });
+                }
+            }
+        }
+    }
+
+    return {
+        tables:  { created: createdTables, dropped: droppedTables },
+        columns: { added: addedCols, dropped: droppedCols, altered: alteredCols },
+    };
+}
+
+/**
+ * Deep-compare two column definitions (JSON-serialisable).
+ * @private
+ */
+function _defsEqual(a, b)
+{
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+
+/**
+ * Returns true when the change-set has no changes.
+ *
+ * @param {object} changes - Output of `diffSnapshots`.
+ * @returns {boolean}
+ */
+function hasNoChanges(changes)
+{
+    return changes.tables.created.length  === 0
+        && changes.tables.dropped.length  === 0
+        && changes.columns.added.length   === 0
+        && changes.columns.dropped.length === 0
+        && changes.columns.altered.length === 0;
+}
+
+// -- Code generation -------------------------------------------
+
+/**
+ * Generate the JavaScript source for a migration file from a change-set.
+ *
+ * @param {string} migrationName - Timestamped migration name.
+ * @param {object} changes       - Output of `diffSnapshots`.
+ * @param {object} currentSnap   - Current snapshot (for full table schemas on create).
+ * @returns {string} Migration file source code.
+ */
+function generateMigrationCode(migrationName, changes, currentSnap)
+{
+    const upLines   = [];
+    const downLines = [];
+
+    // -- Created tables --
+    for (const table of changes.tables.created)
+    {
+        const schema = currentSnap[table].schema;
+        upLines.push(`        await db.adapter.createTable('${table}', ${_schemaLiteral(schema)});`);
+        downLines.push(`        await db.adapter.dropTable('${table}');`);
+    }
+
+    // -- Dropped tables (reverse of create) --
+    for (const table of changes.tables.dropped)
+    {
+        upLines.push(`        await db.adapter.dropTable('${table}');`);
+        // down recreates — but we need the previous snapshot's schema for that
+        // This is handled via the `prev` reference embedded in the dropped table
+    }
+
+    // -- Added columns --
+    for (const { table, column, def } of changes.columns.added)
+    {
+        upLines.push(`        await db.adapter.addColumn('${table}', '${column}', ${_defLiteral(def)});`);
+        downLines.push(`        await db.adapter.dropColumn('${table}', '${column}');`);
+    }
+
+    // -- Dropped columns --
+    for (const { table, column, def } of changes.columns.dropped)
+    {
+        upLines.push(`        await db.adapter.dropColumn('${table}', '${column}');`);
+        downLines.push(`        await db.adapter.addColumn('${table}', '${column}', ${_defLiteral(def)});`);
+    }
+
+    // -- Altered columns (drop + re-add with new def) --
+    for (const { table, column, from, to } of changes.columns.altered)
+    {
+        upLines.push(`        await db.adapter.dropColumn('${table}', '${column}');`);
+        upLines.push(`        await db.adapter.addColumn('${table}', '${column}', ${_defLiteral(to)});`);
+        downLines.push(`        await db.adapter.dropColumn('${table}', '${column}');`);
+        downLines.push(`        await db.adapter.addColumn('${table}', '${column}', ${_defLiteral(from)});`);
+    }
+
+    // Build the final source
+    const upBody   = upLines.length   > 0 ? upLines.join('\n')   : '        // No changes';
+    const downBody = downLines.length > 0 ? downLines.join('\n') : '        // No changes';
+
+    return `'use strict';
+
+/**
+ * Auto-generated migration — ${migrationName}
+ * Generated by: npx zh make:migration
+ */
+module.exports = {
+    name: '${migrationName}',
+
+    async up(db) {
+${upBody}
+    },
+
+    async down(db) {
+${downBody}
+    },
+};
+`;
+}
+
+/**
+ * Serialise a full table schema into a code literal string.
+ * @private
+ */
+function _schemaLiteral(schema)
+{
+    const entries = [];
+    for (const [col, def] of Object.entries(schema))
+    {
+        entries.push(`            ${col}: ${_defLiteral(def)}`);
+    }
+    return `{\n${entries.join(',\n')},\n        }`;
+}
+
+/**
+ * Serialise one column definition into a code literal string.
+ * @private
+ */
+function _defLiteral(def)
+{
+    const parts = [];
+    for (const [k, v] of Object.entries(def))
+    {
+        if (v === null || v === undefined) continue;
+        if (typeof v === 'string') parts.push(`${k}: '${v}'`);
+        else if (typeof v === 'boolean' || typeof v === 'number') parts.push(`${k}: ${v}`);
+        else if (Array.isArray(v)) parts.push(`${k}: ${JSON.stringify(v)}`);
+        else if (typeof v === 'object') parts.push(`${k}: ${JSON.stringify(v)}`);
+    }
+    return `{ ${parts.join(', ')} }`;
+}
+
+// -- Model discovery -------------------------------------------
+
+/**
+ * Load all Model classes from a directory.
+ *
+ * @param {string} dir  - Absolute path to the models directory.
+ * @param {Function} ModelBase - The base Model class to check `instanceof`.
+ * @returns {Function[]} Array of Model subclasses.
+ */
+function discoverModels(dir, ModelBase)
+{
+    if (!fs.existsSync(dir)) return [];
+
+    const files = fs.readdirSync(dir).filter(f => f.endsWith('.js')).sort();
+    const models = [];
+
+    for (const file of files)
+    {
+        try
+        {
+            const exported = require(path.join(dir, file));
+            const M = typeof exported === 'function' ? exported
+                : (exported && exported.default && typeof exported.default === 'function')
+                    ? exported.default
+                    : null;
+
+            if (M && M.table && M.schema && (M.prototype instanceof ModelBase || M === ModelBase))
+            {
+                models.push(M);
+            }
+        }
+        catch (_) { /* skip files that fail to load */ }
+    }
+
+    return models;
+}
+
+module.exports = {
+    buildSnapshot,
+    loadSnapshot,
+    saveSnapshot,
+    diffSnapshots,
+    hasNoChanges,
+    generateMigrationCode,
+    discoverModels,
+    SNAPSHOT_FILE,
+};