@zero-server/orm 0.9.0 → 0.9.2

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

@@ -0,0 +1,128 @@
+'use strict';
+
+/**
+ * @module seed/data/person
+ * @description Data pools for generated person attributes:
+ *              job titles, prefixes/suffixes, gender, bio phrases, zodiac signs.
+ */
+
+/** Title prefixes — separate lists per target sex for contextual use. */
+const NAME_PREFIXES = {
+    male:    ['Mr.', 'Dr.', 'Prof.'],
+    female:  ['Ms.', 'Mrs.', 'Dr.', 'Prof.', 'Miss'],
+    neutral: ['Dr.', 'Prof.', 'Rev.', 'Hon.'],
+};
+
+/** Credential / generational suffixes. */
+const NAME_SUFFIXES = [
+    'Jr.', 'Sr.', 'I', 'II', 'III', 'IV', 'V',
+    'PhD', 'MD', 'MBA', 'DDS', 'Esq.', 'PE',
+];
+
+/** Job-level descriptors (prepended to job titles). */
+const JOB_DESCRIPTORS = [
+    'Senior', 'Junior', 'Lead', 'Principal', 'Staff', 'Associate',
+    'Global', 'Regional', 'District', 'National', 'Chief', 'Head of',
+    'VP of', 'Director of', 'Manager of', 'Specialist in',
+];
+
+/** Functional areas / departments. */
+const JOB_AREAS = [
+    'Engineering', 'Software', 'Frontend', 'Backend', 'Full-Stack',
+    'Data', 'Infrastructure', 'Cloud', 'Security', 'DevOps', 'QA',
+    'Product', 'Design', 'UX', 'Brand', 'Marketing', 'Growth',
+    'Sales', 'Account', 'Customer Success', 'Support', 'Finance',
+    'Operations', 'Legal', 'HR', 'Research', 'Analytics', 'Business',
+    'Mobile', 'AI', 'Machine Learning', 'Platform', 'Solutions',
+];
+
+/** Job title nouns. */
+const JOB_TYPES = [
+    'Engineer', 'Developer', 'Designer', 'Architect', 'Analyst',
+    'Strategist', 'Consultant', 'Coordinator', 'Administrator',
+    'Manager', 'Director', 'Officer', 'Executive', 'Specialist',
+    'Researcher', 'Scientist', 'Associate', 'Advisor', 'Lead',
+    'Partner', 'Representative', 'Recruiter', 'Writer', 'Editor',
+    'Technician', 'Operator', 'Planner', 'Producer', 'Advocate',
+];
+
+/** Pre-built full job titles for use when a complete title is needed. */
+const JOB_TITLES = [
+    'Software Engineer', 'Senior Software Engineer', 'Lead Developer',
+    'Full-Stack Developer', 'Frontend Developer', 'Backend Engineer',
+    'DevOps Engineer', 'Site Reliability Engineer', 'Platform Engineer',
+    'Data Engineer', 'Data Scientist', 'Machine Learning Engineer',
+    'Product Manager', 'Senior Product Manager', 'Technical Product Manager',
+    'UX Designer', 'UI Designer', 'Product Designer', 'Brand Designer',
+    'Marketing Manager', 'Growth Hacker', 'Content Strategist', 'SEO Specialist',
+    'Sales Engineer', 'Account Executive', 'Customer Success Manager',
+    'Business Analyst', 'Financial Analyst', 'Chief Financial Officer',
+    'Chief Technology Officer', 'Chief Executive Officer', 'VP of Engineering',
+    'Director of Operations', 'Head of Growth', 'Engineering Manager',
+    'QA Engineer', 'Security Engineer', 'Cloud Architect', 'Solutions Architect',
+    'HR Business Partner', 'Talent Acquisition Specialist', 'Legal Counsel',
+    'Data Analyst', 'BI Developer', 'Mobile Developer', 'iOS Engineer',
+    'Android Developer', 'Technical Writer', 'Developer Advocate',
+];
+
+/** Zodiac sign names. */
+const ZODIAC_SIGNS = [
+    'Aries', 'Taurus', 'Gemini', 'Cancer', 'Leo', 'Virgo',
+    'Libra', 'Scorpio', 'Sagittarius', 'Capricorn', 'Aquarius', 'Pisces',
+];
+
+/** Inclusive gender labels. */
+const GENDERS = [
+    'Male', 'Female', 'Non-binary', 'Gender fluid', 'Agender',
+    'Bigender', 'Genderqueer', 'Two-spirit', 'Trans man', 'Trans woman',
+    'Pangender', 'Neutrois', 'Androgynous', 'Gender non-conforming',
+];
+
+/** Short biography phrase fragments, combinable into a fun bio. */
+const BIO_ADJECTIVES = [
+    'avid', 'aspiring', 'passionate', 'reformed', 'recovering', 'proud',
+    'self-taught', 'seasoned', 'aspiring', 'enthusiastic', 'relentless',
+    'certified', 'award-winning', 'self-proclaimed', 'part-time', 'full-time',
+];
+
+const BIO_NOUNS = [
+    'coder', 'developer', 'designer', 'hacker', 'maker', 'builder',
+    'tinkerer', 'skeptic', 'advocate', 'coffee drinker', 'pizza lover',
+    'cat person', 'dog person', 'night owl', 'morning person', 'traveler',
+    'bookworm', 'gamer', 'runner', 'cyclist', 'climber', 'swimmer',
+    'foodie', 'chef', 'photographer', 'musician', 'artist', 'dreamer',
+    'blogger', 'podcaster', 'content creator', 'open-source contributor',
+];
+
+const BIO_PHRASES = [
+    'lover of all things tech', 'always learning something new',
+    'living one commit at a time', 'making things that matter',
+    'caffeinated and ready to ship', 'here to build great products',
+    'not all who wander are lost', 'just vibing and deploying hotfixes',
+    'ask me about my side projects', 'one bug at a time',
+    'pushing to prod on Fridays', 'debug everything, regret nothing',
+    'refactoring the world, one function at a time',
+    'building the future from the terminal',
+    'professional overthinker', 'chaos engineer in training',
+    '10x developer (citation needed)', 'it works on my machine',
+    'turning coffee into code since forever',
+    'probably thinking about distributed systems right now',
+];
+
+/** Blood type options. */
+const BLOOD_TYPES = ['A+', 'A-', 'B+', 'B-', 'AB+', 'AB-', 'O+', 'O-'];
+
+module.exports = {
+    NAME_PREFIXES,
+    NAME_SUFFIXES,
+    JOB_DESCRIPTORS,
+    JOB_AREAS,
+    JOB_TYPES,
+    JOB_TITLES,
+    ZODIAC_SIGNS,
+    GENDERS,
+    BIO_ADJECTIVES,
+    BIO_NOUNS,
+    BIO_PHRASES,
+    BLOOD_TYPES,
+};

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

@@ -0,0 +1,211 @@
+'use strict';
+
+/**
+ * @module seed/data/phone
+ * @description Phone format templates and country-code metadata.
+ *
+ *  Format characters:
+ *    #  any digit (0–9)
+ *    N  non-zero digit (1–9)
+ *    X  subscriber digit (2–9)
+ */
+
+/**
+ * Array of { countryCode, dialCode, formats }
+ *
+ * formats.human       – human-input style  (e.g. 555-770-7727 x1234)
+ * formats.national    – national format    (e.g. (555) 123-4567)
+ * formats.international – E.123 style      (e.g. +1 555 123 4567)
+ */
+const PHONE_DATA = [
+    {
+        countryCode: 'US',
+        dialCode: '+1',
+        formats: {
+            human:         ['###-###-####', '(###) ###-####', '###.###.####', '###-###-#### x###'],
+            national:      ['(###) ###-####'],
+            international: ['+1 (###) ###-####', '+1-###-###-####'],
+        },
+    },
+    {
+        countryCode: 'CA',
+        dialCode: '+1',
+        formats: {
+            human:         ['###-###-####', '(###) ###-####', '###.###.####'],
+            national:      ['(###) ###-####'],
+            international: ['+1 (###) ###-####'],
+        },
+    },
+    {
+        countryCode: 'GB',
+        dialCode: '+44',
+        formats: {
+            human:         ['07### ######', '01### ######', '02# #### ####'],
+            national:      ['07### ######', '(01###) ######'],
+            international: ['+44 7### ######', '+44 1### ######'],
+        },
+    },
+    {
+        countryCode: 'DE',
+        dialCode: '+49',
+        formats: {
+            human:         ['0### #######', '0## ########', '01## #######'],
+            national:      ['(0###) #######'],
+            international: ['+49 ### #######', '+49 ## ########'],
+        },
+    },
+    {
+        countryCode: 'FR',
+        dialCode: '+33',
+        formats: {
+            human:         ['0# ## ## ## ##', '06 ## ## ## ##', '07 ## ## ## ##'],
+            national:      ['0# ## ## ## ##'],
+            international: ['+33 # ## ## ## ##'],
+        },
+    },
+    {
+        countryCode: 'IT',
+        dialCode: '+39',
+        formats: {
+            human:         ['### #######', '3## #######'],
+            national:      ['(###) #######'],
+            international: ['+39 ### #######'],
+        },
+    },
+    {
+        countryCode: 'ES',
+        dialCode: '+34',
+        formats: {
+            human:         ['### ### ###', '6## ### ###'],
+            national:      ['(###) ### ###'],
+            international: ['+34 ### ### ###'],
+        },
+    },
+    {
+        countryCode: 'PT',
+        dialCode: '+351',
+        formats: {
+            human:         ['2## ### ###', '9## ### ###'],
+            national:      ['(2##) ### ###'],
+            international: ['+351 ### ### ###'],
+        },
+    },
+    {
+        countryCode: 'BR',
+        dialCode: '+55',
+        formats: {
+            human:         ['(##) ####-####', '(##) 9####-####'],
+            national:      ['(##) ####-####'],
+            international: ['+55 ## #### ####'],
+        },
+    },
+    {
+        countryCode: 'MX',
+        dialCode: '+52',
+        formats: {
+            human:         ['(###) ###-####', '## #### ####'],
+            national:      ['(###) ###-####'],
+            international: ['+52 ### ### ####'],
+        },
+    },
+    {
+        countryCode: 'RU',
+        dialCode: '+7',
+        formats: {
+            human:         ['8 (###) ###-##-##', '8-###-###-##-##'],
+            national:      ['(###) ###-##-##'],
+            international: ['+7 (###) ###-##-##'],
+        },
+    },
+    {
+        countryCode: 'IN',
+        dialCode: '+91',
+        formats: {
+            human:         ['#####-#####', '(0##) ###-####'],
+            national:      ['##### #####'],
+            international: ['+91 ##### #####'],
+        },
+    },
+    {
+        countryCode: 'CN',
+        dialCode: '+86',
+        formats: {
+            human:         ['### #### ####', '1## #### ####'],
+            national:      ['(0##) #### ####'],
+            international: ['+86 ### #### ####'],
+        },
+    },
+    {
+        countryCode: 'JP',
+        dialCode: '+81',
+        formats: {
+            human:         ['0##-####-####', '080-####-####', '090-####-####'],
+            national:      ['(0##) ####-####'],
+            international: ['+81 ##-####-####'],
+        },
+    },
+    {
+        countryCode: 'KR',
+        dialCode: '+82',
+        formats: {
+            human:         ['0##-####-####', '010-####-####'],
+            national:      ['(0##) ####-####'],
+            international: ['+82 ##-####-####'],
+        },
+    },
+    {
+        countryCode: 'AU',
+        dialCode: '+61',
+        formats: {
+            human:         ['04## ### ###', '0# #### ####'],
+            national:      ['04## ### ###', '(0#) #### ####'],
+            international: ['+61 4## ### ###', '+61 # #### ####'],
+        },
+    },
+    {
+        countryCode: 'NL',
+        dialCode: '+31',
+        formats: {
+            human:         ['0## ### ####', '06 ## ## ## ##'],
+            national:      ['(0##) ### ####'],
+            international: ['+31 ## ### ####'],
+        },
+    },
+    {
+        countryCode: 'SE',
+        dialCode: '+46',
+        formats: {
+            human:         ['0## ### ## ##', '07# ### ## ##'],
+            national:      ['(0##) ### ## ##'],
+            international: ['+46 ## ### ## ##'],
+        },
+    },
+    {
+        countryCode: 'ZA',
+        dialCode: '+27',
+        formats: {
+            human:         ['0## ### ####', '081 ### ####'],
+            national:      ['(0##) ### ####'],
+            international: ['+27 ## ### ####'],
+        },
+    },
+    {
+        countryCode: 'NG',
+        dialCode: '+234',
+        formats: {
+            human:         ['080 #### ####', '081 #### ####', '0## ### ####'],
+            national:      ['0## ### ####'],
+            international: ['+234 ## #### ####'],
+        },
+    },
+];
+
+/** Indexed by country code for O(1) lookups. */
+const PHONE_BY_COUNTRY = Object.fromEntries(
+    PHONE_DATA.map(p => [p.countryCode, p])
+);
+
+/** All supported country codes. */
+const COUNTRY_CODES = PHONE_DATA.map(p => p.countryCode);
+
+module.exports = { PHONE_DATA, PHONE_BY_COUNTRY, COUNTRY_CODES };

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

@@ -0,0 +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,
+};

package/lib/orm/seed/factory.js

@@ -0,0 +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 };