@zero-server/sdk 0.9.0 → 0.9.2

package/lib/orm/seed/data/words.js

@@ -1,134 +1,134 @@
-'use strict';
-
-/**
- * @module seed/data/words
- * @description Word pools for text-generation helpers (lorem ipsum, hacker,
- *              adjectives, nouns, verbs).
- */
-
-/** Extended lorem ipsum vocabulary for paragraph / sentence generation. */
-const LOREM_WORDS = [
-    'lorem', 'ipsum', 'dolor', 'sit', 'amet', 'consectetur', 'adipiscing', 'elit',
-    'sed', 'eiusmod', 'tempor', 'incididunt', 'labore', 'dolore', 'magna', 'aliqua',
-    'enim', 'minim', 'veniam', 'quis', 'nostrud', 'exercitation', 'ullamco', 'laboris',
-    'nisi', 'aliquip', 'commodo', 'consequat', 'duis', 'aute', 'irure', 'reprehenderit',
-    'voluptate', 'velit', 'esse', 'cillum', 'fugiat', 'nulla', 'pariatur', 'excepteur',
-    'sint', 'occaecat', 'cupidatat', 'proident', 'culpa', 'officia', 'deserunt', 'mollit',
-    'anim', 'laborum', 'perspiciatis', 'unde', 'omnis', 'iste', 'natus', 'error',
-    'accusantium', 'doloremque', 'laudantium', 'totam', 'aperiam', 'eaque', 'ipsa',
-    'quae', 'inventore', 'veritatis', 'quasi', 'architecto', 'beatae', 'vitae',
-    'dicta', 'explicabo', 'aspernatur', 'aut', 'odit', 'fugit', 'voluptas', 'esse',
-    'blanditiis', 'praesentium', 'voluptatum', 'deleniti', 'atque', 'corrupti',
-    'quos', 'molestias', 'excepturi', 'occaecati', 'impedit', 'minus', 'soluta',
-    'nobis', 'eligendi', 'optio', 'cumque', 'nihil', 'impedit', 'assumenda',
-    'repellendus', 'temporibus', 'quibusdam', 'officiis', 'debitis', 'rerum',
-    'saepe', 'eveniet', 'repudiandae', 'recusandae', 'itaque', 'earum', 'facilis',
-    'expedita', 'distinctio', 'libero', 'tempore', 'cum', 'soluta', 'nobis',
-    'eligendi', 'voluptatem', 'accusantium', 'reiciendis', 'voluptatibus', 'maiores',
-];
-
-/** Hacker-speak adjectives (for technical-sounding content). */
-const HACKER_ADJECTIVES = [
-    'auxiliary', 'back-end', 'binary', 'bluetooth', 'bypass', 'cross-platform',
-    'digital', 'distributed', 'encrypted', 'enterprise', 'global', 'haptic',
-    'human-readable', 'incremental', 'integrated', 'intuitive', 'iterative',
-    'mobile', 'modular', 'multi-byte', 'neural', 'neural-net', 'online',
-    'open-source', 'optical', 'primary', 'progressive', 'proxy', 'real-time',
-    'redundant', 'responsive', 'scalable', 'solid-state', 'syntactic',
-    'third-party', 'turn-key', 'ubiquitous', 'upstream', 'virtual', 'wireless',
-];
-
-/** Hacker-speak nouns. */
-const HACKER_NOUNS = [
-    'array', 'bandwidth', 'circuit', 'codecs', 'bus', 'capacitor', 'driver',
-    'feed', 'firewall', 'hard-drive', 'interface', 'matrix', 'microchip',
-    'monitor', 'network', 'panel', 'parser', 'payload', 'pixel', 'port',
-    'protocol', 'router', 'sensor', 'server', 'socket', 'system', 'terminal',
-    'transmitter', 'program', 'card', 'application', 'cache', 'alarm',
-    'bandwidth', 'protocol', 'pixel', 'database', 'byte', 'token', 'hash',
-];
-
-/** Hacker-speak verbs. */
-const HACKER_VERBS = [
-    'back up', 'bypass', 'calculate', 'compress', 'connect', 'copy', 'decrypt',
-    'disintegrate', 'encrypt', 'encode', 'generate', 'hack', 'index', 'input',
-    'install', 'interface', 'navigate', 'override', 'parse', 'program',
-    'quantify', 'reboot', 'reinitialize', 'synthesize', 'transmit', 'transpile',
-    'quantize', 'serialize', 'virtualize', 'authenticate', 'tokenize', 'deploy',
-];
-
-/** Common English adjectives. */
-const ADJECTIVES = [
-    'adaptable', 'adventurous', 'affectionate', 'ambitious', 'ancient', 'arid',
-    'aromatic', 'artificial', 'bold', 'boundless', 'captivating', 'careful',
-    'charming', 'cheerful', 'cloudy', 'comfortable', 'complex', 'confident',
-    'content', 'crisp', 'curious', 'dazzling', 'decisive', 'delightful',
-    'dense', 'determined', 'divine', 'durable', 'elegant', 'ethical',
-    'exciting', 'exotic', 'exquisite', 'extraordinary', 'fabulous', 'faithful',
-    'famous', 'fancy', 'fantastic', 'fearless', 'flexible', 'fluent',
-    'genuine', 'glorious', 'graceful', 'grateful', 'handsome', 'harmonious',
-    'helpful', 'honest', 'humble', 'immense', 'impeccable', 'innovative',
-    'inspiring', 'intelligent', 'jovial', 'joyful', 'keen', 'lively',
-    'logical', 'loyal', 'luxurious', 'magical', 'majestic', 'masterful',
-    'mindful', 'natural', 'nimble', 'noble', 'orderly', 'passionate',
-    'patient', 'peaceful', 'perfect', 'playful', 'polished', 'powerful',
-    'precise', 'productive', 'qualitative', 'radiant', 'refreshing', 'reliable',
-    'resilient', 'resourceful', 'restful', 'rhythmic', 'robust', 'secure',
-    'serene', 'sincere', 'sophisticated', 'steadfast', 'strategic', 'stunning',
-    'sustainable', 'swift', 'thoughtful', 'thriving', 'timeless', 'tranquil',
-    'trustworthy', 'unique', 'vibrant', 'vigilant', 'virtuous', 'wonderful',
-];
-
-/** Common English nouns. */
-const NOUNS = [
-    'ability', 'absence', 'access', 'account', 'action', 'activity', 'addition',
-    'address', 'advance', 'adventure', 'advice', 'affair', 'agenda', 'agreement',
-    'algorithm', 'alliance', 'analysis', 'announcement', 'answer', 'approach',
-    'architecture', 'area', 'argument', 'arrangement', 'asset', 'assumption',
-    'balance', 'benefit', 'boundary', 'capability', 'challenge', 'change',
-    'channel', 'chart', 'choice', 'claim', 'clarity', 'class', 'collection',
-    'commitment', 'community', 'component', 'concept', 'concern', 'conclusion',
-    'configuration', 'conflict', 'connection', 'constraint', 'context', 'contract',
-    'contribution', 'control', 'conversion', 'culture', 'decision', 'delivery',
-    'design', 'detail', 'development', 'difference', 'direction', 'discovery',
-    'discussion', 'distribution', 'document', 'domain', 'duration', 'element',
-    'energy', 'environment', 'evaluation', 'example', 'experience', 'explanation',
-    'extension', 'factor', 'feature', 'feedback', 'flow', 'focus', 'format',
-    'foundation', 'framework', 'function', 'future', 'growth', 'guide',
-    'improvement', 'innovation', 'input', 'insight', 'integration', 'interface',
-    'issue', 'iteration', 'journey', 'knowledge', 'language', 'layer', 'level',
-    'limit', 'method', 'metric', 'model', 'module', 'network', 'object',
-    'option', 'outcome', 'output', 'package', 'pattern', 'performance', 'pipeline',
-    'platform', 'policy', 'potential', 'priority', 'problem', 'process', 'product',
-    'progress', 'project', 'protocol', 'quality', 'query', 'range', 'record',
-    'resource', 'result', 'review', 'risk', 'role', 'rule', 'scope',
-    'service', 'session', 'setting', 'signal', 'solution', 'source', 'stage',
-    'standard', 'status', 'strategy', 'structure', 'success', 'summary', 'support',
-    'task', 'team', 'technology', 'template', 'threshold', 'timeline', 'token',
-    'tool', 'transition', 'type', 'update', 'user', 'value', 'version', 'vision',
-];
-
-/** Common English verbs (infinitive form). */
-const VERBS = [
-    'achieve', 'adjust', 'adopt', 'advance', 'analyze', 'apply', 'approve',
-    'arrange', 'assess', 'assist', 'build', 'calculate', 'capture', 'change',
-    'choose', 'clarify', 'collaborate', 'communicate', 'complete', 'configure',
-    'connect', 'consider', 'create', 'decide', 'define', 'deliver', 'design',
-    'develop', 'discover', 'distribute', 'document', 'enable', 'establish',
-    'evaluate', 'execute', 'explore', 'focus', 'generate', 'guide', 'identify',
-    'implement', 'improve', 'increase', 'integrate', 'iterate', 'launch',
-    'maintain', 'manage', 'measure', 'migrate', 'monitor', 'optimize', 'plan',
-    'prioritize', 'produce', 'provide', 'publish', 'refactor', 'release',
-    'resolve', 'review', 'scale', 'simplify', 'streamline', 'support', 'test',
-    'transform', 'update', 'validate', 'verify',
-];
-
-module.exports = {
-    LOREM_WORDS,
-    HACKER_ADJECTIVES,
-    HACKER_NOUNS,
-    HACKER_VERBS,
-    ADJECTIVES,
-    NOUNS,
-    VERBS,
-};
+'use strict';
+
+/**
+ * @module seed/data/words
+ * @description Word pools for text-generation helpers (lorem ipsum, hacker,
+ *              adjectives, nouns, verbs).
+ */
+
+/** Extended lorem ipsum vocabulary for paragraph / sentence generation. */
+const LOREM_WORDS = [
+    'lorem', 'ipsum', 'dolor', 'sit', 'amet', 'consectetur', 'adipiscing', 'elit',
+    'sed', 'eiusmod', 'tempor', 'incididunt', 'labore', 'dolore', 'magna', 'aliqua',
+    'enim', 'minim', 'veniam', 'quis', 'nostrud', 'exercitation', 'ullamco', 'laboris',
+    'nisi', 'aliquip', 'commodo', 'consequat', 'duis', 'aute', 'irure', 'reprehenderit',
+    'voluptate', 'velit', 'esse', 'cillum', 'fugiat', 'nulla', 'pariatur', 'excepteur',
+    'sint', 'occaecat', 'cupidatat', 'proident', 'culpa', 'officia', 'deserunt', 'mollit',
+    'anim', 'laborum', 'perspiciatis', 'unde', 'omnis', 'iste', 'natus', 'error',
+    'accusantium', 'doloremque', 'laudantium', 'totam', 'aperiam', 'eaque', 'ipsa',
+    'quae', 'inventore', 'veritatis', 'quasi', 'architecto', 'beatae', 'vitae',
+    'dicta', 'explicabo', 'aspernatur', 'aut', 'odit', 'fugit', 'voluptas', 'esse',
+    'blanditiis', 'praesentium', 'voluptatum', 'deleniti', 'atque', 'corrupti',
+    'quos', 'molestias', 'excepturi', 'occaecati', 'impedit', 'minus', 'soluta',
+    'nobis', 'eligendi', 'optio', 'cumque', 'nihil', 'impedit', 'assumenda',
+    'repellendus', 'temporibus', 'quibusdam', 'officiis', 'debitis', 'rerum',
+    'saepe', 'eveniet', 'repudiandae', 'recusandae', 'itaque', 'earum', 'facilis',
+    'expedita', 'distinctio', 'libero', 'tempore', 'cum', 'soluta', 'nobis',
+    'eligendi', 'voluptatem', 'accusantium', 'reiciendis', 'voluptatibus', 'maiores',
+];
+
+/** Hacker-speak adjectives (for technical-sounding content). */
+const HACKER_ADJECTIVES = [
+    'auxiliary', 'back-end', 'binary', 'bluetooth', 'bypass', 'cross-platform',
+    'digital', 'distributed', 'encrypted', 'enterprise', 'global', 'haptic',
+    'human-readable', 'incremental', 'integrated', 'intuitive', 'iterative',
+    'mobile', 'modular', 'multi-byte', 'neural', 'neural-net', 'online',
+    'open-source', 'optical', 'primary', 'progressive', 'proxy', 'real-time',
+    'redundant', 'responsive', 'scalable', 'solid-state', 'syntactic',
+    'third-party', 'turn-key', 'ubiquitous', 'upstream', 'virtual', 'wireless',
+];
+
+/** Hacker-speak nouns. */
+const HACKER_NOUNS = [
+    'array', 'bandwidth', 'circuit', 'codecs', 'bus', 'capacitor', 'driver',
+    'feed', 'firewall', 'hard-drive', 'interface', 'matrix', 'microchip',
+    'monitor', 'network', 'panel', 'parser', 'payload', 'pixel', 'port',
+    'protocol', 'router', 'sensor', 'server', 'socket', 'system', 'terminal',
+    'transmitter', 'program', 'card', 'application', 'cache', 'alarm',
+    'bandwidth', 'protocol', 'pixel', 'database', 'byte', 'token', 'hash',
+];
+
+/** Hacker-speak verbs. */
+const HACKER_VERBS = [
+    'back up', 'bypass', 'calculate', 'compress', 'connect', 'copy', 'decrypt',
+    'disintegrate', 'encrypt', 'encode', 'generate', 'hack', 'index', 'input',
+    'install', 'interface', 'navigate', 'override', 'parse', 'program',
+    'quantify', 'reboot', 'reinitialize', 'synthesize', 'transmit', 'transpile',
+    'quantize', 'serialize', 'virtualize', 'authenticate', 'tokenize', 'deploy',
+];
+
+/** Common English adjectives. */
+const ADJECTIVES = [
+    'adaptable', 'adventurous', 'affectionate', 'ambitious', 'ancient', 'arid',
+    'aromatic', 'artificial', 'bold', 'boundless', 'captivating', 'careful',
+    'charming', 'cheerful', 'cloudy', 'comfortable', 'complex', 'confident',
+    'content', 'crisp', 'curious', 'dazzling', 'decisive', 'delightful',
+    'dense', 'determined', 'divine', 'durable', 'elegant', 'ethical',
+    'exciting', 'exotic', 'exquisite', 'extraordinary', 'fabulous', 'faithful',
+    'famous', 'fancy', 'fantastic', 'fearless', 'flexible', 'fluent',
+    'genuine', 'glorious', 'graceful', 'grateful', 'handsome', 'harmonious',
+    'helpful', 'honest', 'humble', 'immense', 'impeccable', 'innovative',
+    'inspiring', 'intelligent', 'jovial', 'joyful', 'keen', 'lively',
+    'logical', 'loyal', 'luxurious', 'magical', 'majestic', 'masterful',
+    'mindful', 'natural', 'nimble', 'noble', 'orderly', 'passionate',
+    'patient', 'peaceful', 'perfect', 'playful', 'polished', 'powerful',
+    'precise', 'productive', 'qualitative', 'radiant', 'refreshing', 'reliable',
+    'resilient', 'resourceful', 'restful', 'rhythmic', 'robust', 'secure',
+    'serene', 'sincere', 'sophisticated', 'steadfast', 'strategic', 'stunning',
+    'sustainable', 'swift', 'thoughtful', 'thriving', 'timeless', 'tranquil',
+    'trustworthy', 'unique', 'vibrant', 'vigilant', 'virtuous', 'wonderful',
+];
+
+/** Common English nouns. */
+const NOUNS = [
+    'ability', 'absence', 'access', 'account', 'action', 'activity', 'addition',
+    'address', 'advance', 'adventure', 'advice', 'affair', 'agenda', 'agreement',
+    'algorithm', 'alliance', 'analysis', 'announcement', 'answer', 'approach',
+    'architecture', 'area', 'argument', 'arrangement', 'asset', 'assumption',
+    'balance', 'benefit', 'boundary', 'capability', 'challenge', 'change',
+    'channel', 'chart', 'choice', 'claim', 'clarity', 'class', 'collection',
+    'commitment', 'community', 'component', 'concept', 'concern', 'conclusion',
+    'configuration', 'conflict', 'connection', 'constraint', 'context', 'contract',
+    'contribution', 'control', 'conversion', 'culture', 'decision', 'delivery',
+    'design', 'detail', 'development', 'difference', 'direction', 'discovery',
+    'discussion', 'distribution', 'document', 'domain', 'duration', 'element',
+    'energy', 'environment', 'evaluation', 'example', 'experience', 'explanation',
+    'extension', 'factor', 'feature', 'feedback', 'flow', 'focus', 'format',
+    'foundation', 'framework', 'function', 'future', 'growth', 'guide',
+    'improvement', 'innovation', 'input', 'insight', 'integration', 'interface',
+    'issue', 'iteration', 'journey', 'knowledge', 'language', 'layer', 'level',
+    'limit', 'method', 'metric', 'model', 'module', 'network', 'object',
+    'option', 'outcome', 'output', 'package', 'pattern', 'performance', 'pipeline',
+    'platform', 'policy', 'potential', 'priority', 'problem', 'process', 'product',
+    'progress', 'project', 'protocol', 'quality', 'query', 'range', 'record',
+    'resource', 'result', 'review', 'risk', 'role', 'rule', 'scope',
+    'service', 'session', 'setting', 'signal', 'solution', 'source', 'stage',
+    'standard', 'status', 'strategy', 'structure', 'success', 'summary', 'support',
+    'task', 'team', 'technology', 'template', 'threshold', 'timeline', 'token',
+    'tool', 'transition', 'type', 'update', 'user', 'value', 'version', 'vision',
+];
+
+/** Common English verbs (infinitive form). */
+const VERBS = [
+    'achieve', 'adjust', 'adopt', 'advance', 'analyze', 'apply', 'approve',
+    'arrange', 'assess', 'assist', 'build', 'calculate', 'capture', 'change',
+    'choose', 'clarify', 'collaborate', 'communicate', 'complete', 'configure',
+    'connect', 'consider', 'create', 'decide', 'define', 'deliver', 'design',
+    'develop', 'discover', 'distribute', 'document', 'enable', 'establish',
+    'evaluate', 'execute', 'explore', 'focus', 'generate', 'guide', 'identify',
+    'implement', 'improve', 'increase', 'integrate', 'iterate', 'launch',
+    'maintain', 'manage', 'measure', 'migrate', 'monitor', 'optimize', 'plan',
+    'prioritize', 'produce', 'provide', 'publish', 'refactor', 'release',
+    'resolve', 'review', 'scale', 'simplify', 'streamline', 'support', 'test',
+    'transform', 'update', 'validate', 'verify',
+];
+
+module.exports = {
+    LOREM_WORDS,
+    HACKER_ADJECTIVES,
+    HACKER_NOUNS,
+    HACKER_VERBS,
+    ADJECTIVES,
+    NOUNS,
+    VERBS,
+};

package/lib/orm/seed/factory.js

@@ -1,178 +1,178 @@
-'use strict';
-
-/**
- * @module seed/factory
- * @description Factory pattern for generating and persisting model records.
- *
- * @example
- *   const factory = new Factory(User);
- *   factory.define({
- *       name:  () => Fake.fullName(),
- *       email: () => Fake.email({ unique: true }),
- *       role:  'user',
- *   });
- *
- *   // Build without persisting
- *   const data = factory.count(5).make();
- *
- *   // Create and persist
- *   const users = await factory.count(10).create();
- *
- *   // State overrides
- *   factory.state('admin', { role: 'admin' });
- *   const admins = await factory.count(3).withState('admin').create();
- */
-class Factory
-{
-    /**
-     * @constructor
-     * @param {typeof import('../model')} ModelClass - The Model class this factory produces.
-     */
-    constructor(ModelClass)
-    {
-        this._model       = ModelClass;
-        this._definition  = {};
-        this._count       = 1;
-        this._states      = {};
-        this._activeState = null;
-        this._afterCreate = [];
-    }
-
-    /**
-     * Define default field generators for the factory.
-     * Values can be static literals or functions `(index) => value`.
-     *
-     * @param {Record<string, any|((index: number) => any)>} definition - Field definitions map.
-     * @returns {Factory} This factory for chaining.
-     */
-    define(definition)
-    {
-        this._definition = definition;
-        return this;
-    }
-
-    /**
-     * Set how many records to build / create.
-     *
-     * @param {number} n - Positive integer.
-     * @returns {Factory} This factory for chaining.
-     */
-    count(n)
-    {
-        const val = Math.floor(n);
-        if (!Number.isFinite(val) || val < 1)
-            throw new Error('Factory: count must be a positive integer');
-        this._count = val;
-        return this;
-    }
-
-    /**
-     * Register a named state (variation) that can override field values.
-     *
-     * @param {string} name - State name.
-     * @param {Record<string, any|((index: number) => any)>} overrides - Field overrides for this state.
-     * @returns {Factory} This factory for chaining.
-     *
-     * @example
-     *   factory.state('admin', { role: 'admin', verified: true });
-     *   await factory.count(3).withState('admin').create();
-     */
-    state(name, overrides)
-    {
-        this._states[name] = overrides;
-        return this;
-    }
-
-    /**
-     * Apply a previously registered state to the next create / make call.
-     *
-     * @param {string} name - Name of a previously registered state.
-     * @returns {Factory} This factory for chaining.
-     */
-    withState(name)
-    {
-        if (!this._states[name])
-            throw new Error(`Factory state "${name}" is not defined`);
-        this._activeState = name;
-        return this;
-    }
-
-    /**
-     * Register a callback invoked after each record is created.
-     * Useful for setting up relationships.
-     *
-     * @param {(record: any, index: number) => void|Promise<void>} fn - Callback invoked after each record is created.
-     * @returns {Factory} This factory for chaining.
-     *
-     * @example
-     *   factory.afterCreating(async (user) => {
-     *       await Profile.create({ userId: user.id, bio: Fake.bio() });
-     *   });
-     */
-    afterCreating(fn)
-    {
-        this._afterCreate.push(fn);
-        return this;
-    }
-
-    /**
-     * Build plain data objects without persisting to the database.
-     *
-     * @param {object} [overrides] - Per-call field overrides.
-     * @returns {object|object[]} Single object when count=1, array otherwise.
-     */
-    make(overrides = {})
-    {
-        const records = [];
-        for (let i = 0; i < this._count; i++)
-            records.push(this._buildOne(overrides, i));
-        return this._count === 1 ? records[0] : records;
-    }
-
-    /**
-     * Create records and persist them to the database.
-     *
-     * @param {object} [overrides] - Per-call field overrides.
-     * @returns {Promise<object|object[]>} Single record when count=1, array otherwise.
-     */
-    async create(overrides = {})
-    {
-        const records = [];
-        for (let i = 0; i < this._count; i++)
-        {
-            const data   = this._buildOne(overrides, i);
-            const record = await this._model.create(data);
-
-            for (const fn of this._afterCreate)
-                await fn(record, i);
-
-            records.push(record);
-        }
-        return this._count === 1 ? records[0] : records;
-    }
-
-    /**
-     * Build a single record data object applying definition → state → overrides.
-     * @private
-     */
-    _buildOne(overrides, index)
-    {
-        const data = {};
-
-        for (const [key, val] of Object.entries(this._definition))
-            data[key] = typeof val === 'function' ? val(index) : val;
-
-        if (this._activeState && this._states[this._activeState])
-        {
-            for (const [key, val] of Object.entries(this._states[this._activeState]))
-                data[key] = typeof val === 'function' ? val(index) : val;
-        }
-
-        for (const [key, val] of Object.entries(overrides))
-            data[key] = typeof val === 'function' ? val(index) : val;
-
-        return data;
-    }
-}
-
-module.exports = { Factory };
+'use strict';
+
+/**
+ * @module seed/factory
+ * @description Factory pattern for generating and persisting model records.
+ *
+ * @example
+ *   const factory = new Factory(User);
+ *   factory.define({
+ *       name:  () => Fake.fullName(),
+ *       email: () => Fake.email({ unique: true }),
+ *       role:  'user',
+ *   });
+ *
+ *   // Build without persisting
+ *   const data = factory.count(5).make();
+ *
+ *   // Create and persist
+ *   const users = await factory.count(10).create();
+ *
+ *   // State overrides
+ *   factory.state('admin', { role: 'admin' });
+ *   const admins = await factory.count(3).withState('admin').create();
+ */
+class Factory
+{
+    /**
+     * @constructor
+     * @param {typeof import('../model')} ModelClass - The Model class this factory produces.
+     */
+    constructor(ModelClass)
+    {
+        this._model       = ModelClass;
+        this._definition  = {};
+        this._count       = 1;
+        this._states      = {};
+        this._activeState = null;
+        this._afterCreate = [];
+    }
+
+    /**
+     * Define default field generators for the factory.
+     * Values can be static literals or functions `(index) => value`.
+     *
+     * @param {Record<string, any|((index: number) => any)>} definition - Field definitions map.
+     * @returns {Factory} This factory for chaining.
+     */
+    define(definition)
+    {
+        this._definition = definition;
+        return this;
+    }
+
+    /**
+     * Set how many records to build / create.
+     *
+     * @param {number} n - Positive integer.
+     * @returns {Factory} This factory for chaining.
+     */
+    count(n)
+    {
+        const val = Math.floor(n);
+        if (!Number.isFinite(val) || val < 1)
+            throw new Error('Factory: count must be a positive integer');
+        this._count = val;
+        return this;
+    }
+
+    /**
+     * Register a named state (variation) that can override field values.
+     *
+     * @param {string} name - State name.
+     * @param {Record<string, any|((index: number) => any)>} overrides - Field overrides for this state.
+     * @returns {Factory} This factory for chaining.
+     *
+     * @example
+     *   factory.state('admin', { role: 'admin', verified: true });
+     *   await factory.count(3).withState('admin').create();
+     */
+    state(name, overrides)
+    {
+        this._states[name] = overrides;
+        return this;
+    }
+
+    /**
+     * Apply a previously registered state to the next create / make call.
+     *
+     * @param {string} name - Name of a previously registered state.
+     * @returns {Factory} This factory for chaining.
+     */
+    withState(name)
+    {
+        if (!this._states[name])
+            throw new Error(`Factory state "${name}" is not defined`);
+        this._activeState = name;
+        return this;
+    }
+
+    /**
+     * Register a callback invoked after each record is created.
+     * Useful for setting up relationships.
+     *
+     * @param {(record: any, index: number) => void|Promise<void>} fn - Callback invoked after each record is created.
+     * @returns {Factory} This factory for chaining.
+     *
+     * @example
+     *   factory.afterCreating(async (user) => {
+     *       await Profile.create({ userId: user.id, bio: Fake.bio() });
+     *   });
+     */
+    afterCreating(fn)
+    {
+        this._afterCreate.push(fn);
+        return this;
+    }
+
+    /**
+     * Build plain data objects without persisting to the database.
+     *
+     * @param {object} [overrides] - Per-call field overrides.
+     * @returns {object|object[]} Single object when count=1, array otherwise.
+     */
+    make(overrides = {})
+    {
+        const records = [];
+        for (let i = 0; i < this._count; i++)
+            records.push(this._buildOne(overrides, i));
+        return this._count === 1 ? records[0] : records;
+    }
+
+    /**
+     * Create records and persist them to the database.
+     *
+     * @param {object} [overrides] - Per-call field overrides.
+     * @returns {Promise<object|object[]>} Single record when count=1, array otherwise.
+     */
+    async create(overrides = {})
+    {
+        const records = [];
+        for (let i = 0; i < this._count; i++)
+        {
+            const data   = this._buildOne(overrides, i);
+            const record = await this._model.create(data);
+
+            for (const fn of this._afterCreate)
+                await fn(record, i);
+
+            records.push(record);
+        }
+        return this._count === 1 ? records[0] : records;
+    }
+
+    /**
+     * Build a single record data object applying definition → state → overrides.
+     * @private
+     */
+    _buildOne(overrides, index)
+    {
+        const data = {};
+
+        for (const [key, val] of Object.entries(this._definition))
+            data[key] = typeof val === 'function' ? val(index) : val;
+
+        if (this._activeState && this._states[this._activeState])
+        {
+            for (const [key, val] of Object.entries(this._states[this._activeState]))
+                data[key] = typeof val === 'function' ? val(index) : val;
+        }
+
+        for (const [key, val] of Object.entries(overrides))
+            data[key] = typeof val === 'function' ? val(index) : val;
+
+        return data;
+    }
+}
+
+module.exports = { Factory };