@zero-server/orm 0.9.0 → 0.9.2

package/lib/orm/search.js

@@ -0,0 +1,380 @@
+/**
+ * @module orm/search
+ * @description Full-text search integration for the ORM.
+ *              Provides a unified API across PostgreSQL (tsvector/tsquery),
+ *              MySQL (FULLTEXT), SQLite (FTS5), and in-memory (regex-based).
+ *
+ * @section Full-Text Search
+ *
+ * @example
+ *   const { FullTextSearch } = require('@zero-server/sdk');
+ *
+ *   // Create a search index
+ *   const search = new FullTextSearch(Article, {
+ *       fields: ['title', 'body'],
+ *       weights: { title: 'A', body: 'B' },
+ *   });
+ *
+ *   // Create the index in the database
+ *   await search.createIndex(db);
+ *
+ *   // Search
+ *   const results = await search.search('javascript framework');
+ *   const ranked = await search.search('node.js', { rank: true, limit: 10 });
+ */
+
+const log = require('../debug')('zero:orm:search');
+
+// -- FullTextSearch class ---------------------------------
+
+/**
+ * Full-text search engine for ORM models.
+ * Provides a unified search API that adapts to the underlying database engine.
+ *
+ * @param {typeof Model} ModelClass - Model class to search.
+ * @param {object}       options    - Search configuration.
+ * @param {string[]}     options.fields  - Column names to include in the search index.
+ * @param {Object<string, string>} [options.weights] - Weight map for fields. PostgreSQL: 'A'–'D'. Others: numeric multiplier.
+ * @param {string}       [options.language='english'] - Language for stemming/tokenisation.
+ * @param {string}       [options.indexName]          - Custom index name.
+ */
+class FullTextSearch
+{
+    /**
+     * @constructor
+     * @param {typeof Model} ModelClass - Model class to search.
+     * @param {object}       options    - Configuration options.
+     * @param {string[]}     options.fields       - Column names to include in the search index.
+     * @param {Object<string, string>} [options.weights] - Weight map for fields (e.g. `{ title: 'A', body: 'B' }`).
+     * @param {string}       [options.language='english'] - Language for stemming.
+     * @param {string}       [options.indexName]   - Custom index name.
+     */
+    constructor(ModelClass, options = {})
+    {
+        if (!ModelClass) throw new Error('FullTextSearch requires a Model class');
+        if (!options.fields || !options.fields.length) throw new Error('FullTextSearch requires at least one field');
+
+        /** @type {typeof Model} */
+        this._model = ModelClass;
+
+        /** @type {string[]} Fields to index. */
+        this._fields = options.fields;
+
+        /** @type {Object<string, string>} Field weight configuration. */
+        this._weights = options.weights || {};
+
+        /** @type {string} Language for stemming. */
+        this._language = options.language || 'english';
+
+        /** @type {string} Index name. */
+        this._indexName = options.indexName || `fts_${ModelClass.table}_${this._fields.join('_')}`;
+
+        /** @type {object|null} Database adapter. */
+        this._adapter = null;
+
+        /** @type {string|null} Detected adapter type. */
+        this._adapterType = null;
+    }
+
+    /**
+     * Create the full-text search index.
+     * Adapts to the underlying database:
+     * - PostgreSQL: creates a GIN index on tsvector columns
+     * - MySQL: creates a FULLTEXT index
+     * - SQLite: creates an FTS5 virtual table
+     * - Memory/JSON: no-op (search operates with in-memory regex)
+     *
+     * @param {object} db - Database instance.
+     * @returns {Promise<FullTextSearch>} `this` for chaining.
+     *
+     * @example
+     *   await search.createIndex(db);
+     */
+    async createIndex(db)
+    {
+        this._adapter = db.adapter;
+        this._adapterType = this._detectAdapterType();
+
+        if (typeof this._adapter.createFullTextIndex === 'function')
+        {
+            await this._adapter.createFullTextIndex(this._model.table, this._fields, {
+                name: this._indexName,
+                weights: this._weights,
+                language: this._language,
+            });
+        }
+
+        log.debug('fts index %s created on %s', this._indexName, this._model.table);
+        return this;
+    }
+
+    /**
+     * Drop the full-text search index.
+     *
+     * @param {object} db - Database instance.
+     * @returns {Promise<void>}
+     */
+    async dropIndex(db)
+    {
+        const adapter = db ? db.adapter : this._adapter;
+        if (!adapter) throw new Error('No database adapter available');
+
+        if (typeof adapter.dropFullTextIndex === 'function')
+        {
+            await adapter.dropFullTextIndex(this._model.table, this._indexName);
+        }
+
+        log.debug('fts index %s dropped', this._indexName);
+    }
+
+    /**
+     * Perform a full-text search.
+     *
+     * @param {string} query           - Search query string.
+     * @param {object} [options]       - Search options.
+     * @param {boolean} [options.rank=false]  - Include relevance ranking in results.
+     * @param {number}  [options.limit]       - Maximum number of results.
+     * @param {number}  [options.offset]      - Offset for pagination.
+     * @param {object}  [options.where]       - Additional WHERE conditions.
+     * @param {string}  [options.orderBy]     - Custom order ('rank' for relevance, or a column name).
+     * @returns {Promise<Array<object>>} Search results, optionally with `_rank` scores.
+     *
+     * @example
+     *   // Simple search
+     *   const results = await search.search('javascript');
+     *
+     *   // Ranked search with filters
+     *   const results = await search.search('node.js framework', {
+     *       rank: true,
+     *       limit: 10,
+     *       where: { published: true },
+     *   });
+     *   // results[0]._rank => 0.95 (relevance score)
+     */
+    async search(query, options = {})
+    {
+        if (!query || typeof query !== 'string') return [];
+
+        const adapter = this._adapter || this._model._adapter;
+        if (!adapter) throw new Error('Model is not registered with a database');
+
+        // Use adapter native FTS if available
+        if (typeof adapter.fullTextSearch === 'function')
+        {
+            return adapter.fullTextSearch(this._model.table, this._fields, query, {
+                ...options,
+                language: this._language,
+                weights: this._weights,
+                model: this._model,
+            });
+        }
+
+        // Fallback: in-memory search
+        return this._memorySearch(query, options);
+    }
+
+    /**
+     * Search and return model instances instead of plain objects.
+     *
+     * @param {string} query       - Search query string.
+     * @param {object} [options]   - Search options (same as search()).
+     * @returns {Promise<Array<Model>>} Model instances matching the search query.
+     *
+     * @example
+     *   const articles = await search.searchModels('javascript');
+     *   articles[0].title // => 'Learning JavaScript'
+     */
+    async searchModels(query, options = {})
+    {
+        const rows = await this.search(query, options);
+        return rows.map(row =>
+        {
+            const inst = this._model._fromRow(row);
+            if (row._rank !== undefined) inst._rank = row._rank;
+            return inst;
+        });
+    }
+
+    /**
+     * Count matching search results.
+     *
+     * @param {string} query - Search query string.
+     * @param {object} [options] - Additional WHERE conditions in `options.where`.
+     * @returns {Promise<number>} Number of matching records.
+     */
+    async count(query, options = {})
+    {
+        const results = await this.search(query, { ...options, rank: false });
+        return results.length;
+    }
+
+    /**
+     * Build search suggestions (autocomplete) from indexed fields.
+     *
+     * @param {string} prefix      - Partial search term.
+     * @param {object} [options]   - Configuration options.
+     * @param {number} [options.limit=10]    - Max suggestions.
+     * @param {string} [options.field]       - Specific field to suggest from.
+     * @returns {Promise<string[]>} Matching suggestions.
+     *
+     * @example
+     *   const suggestions = await search.suggest('jav', { limit: 5 });
+     *   // => ['JavaScript', 'Java', 'Javelin']
+     */
+    async suggest(prefix, options = {})
+    {
+        const { limit = 10, field } = options;
+        if (!prefix || typeof prefix !== 'string') return [];
+
+        const searchFields = field ? [field] : this._fields;
+        const adapter = this._adapter || this._model._adapter;
+        if (!adapter) throw new Error('Model is not registered with a database');
+
+        // Use adapter-native suggest if available
+        if (typeof adapter.fullTextSuggest === 'function')
+        {
+            return adapter.fullTextSuggest(this._model.table, searchFields, prefix, { limit });
+        }
+
+        // Fallback: in-memory suggestion
+        const q = this._model.query();
+        const results = await q.exec();
+        const seen = new Set();
+        const suggestions = [];
+        const lowerPrefix = prefix.toLowerCase();
+
+        for (const row of results)
+        {
+            for (const f of searchFields)
+            {
+                const val = row[f];
+                if (!val) continue;
+                const words = String(val).split(/\s+/);
+                for (const word of words)
+                {
+                    const lower = word.toLowerCase();
+                    if (lower.startsWith(lowerPrefix) && !seen.has(lower))
+                    {
+                        seen.add(lower);
+                        suggestions.push(word);
+                        if (suggestions.length >= limit) return suggestions;
+                    }
+                }
+            }
+        }
+
+        return suggestions;
+    }
+
+    /**
+     * In-memory full-text search using regex matching and scoring.
+     * Used as fallback for memory/json adapters.
+     * @param {string} query - Search query.
+     * @param {object} options - Search options.
+     * @returns {Promise<Array>} Matching rows with optional _rank.
+     * @private
+     */
+    async _memorySearch(query, options = {})
+    {
+        const { rank = false, limit, offset = 0, where = {} } = options;
+
+        // Tokenise query into words
+        const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
+        if (!tokens.length) return [];
+
+        // Build regex for each token (escape special chars)
+        const patterns = tokens.map(t =>
+        {
+            const escaped = t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            return new RegExp(escaped, 'i');
+        });
+
+        // Get all records, with optional WHERE conditions
+        let q = this._model.query();
+        if (Object.keys(where).length) q = q.where(where);
+        const allRows = await q.exec();
+
+        // Score each row
+        const scored = [];
+        for (const row of allRows)
+        {
+            let score = 0;
+            let matched = false;
+
+            for (const field of this._fields)
+            {
+                const val = row[field];
+                if (!val) continue;
+                const text = String(val).toLowerCase();
+                const weight = this._getWeight(field);
+
+                for (const pattern of patterns)
+                {
+                    const matches = text.match(new RegExp(pattern.source, 'gi'));
+                    if (matches)
+                    {
+                        matched = true;
+                        score += matches.length * weight;
+                    }
+                }
+            }
+
+            if (matched)
+            {
+                const data = row.toJSON ? row.toJSON() : { ...row };
+                if (rank) data._rank = score;
+                scored.push({ data, score });
+            }
+        }
+
+        // Sort by score (descending)
+        scored.sort((a, b) => b.score - a.score);
+
+        // Apply pagination
+        let results = scored.map(s => s.data);
+        if (offset) results = results.slice(offset);
+        if (limit) results = results.slice(0, limit);
+
+        return results;
+    }
+
+    /**
+     * Get numeric weight for a field.
+     * @param {string} field - Field name.
+     * @returns {number} Numeric weight multiplier.
+     * @private
+     */
+    _getWeight(field)
+    {
+        const w = this._weights[field];
+        if (!w) return 1;
+        // PostgreSQL-style weights: A=4, B=3, C=2, D=1
+        if (typeof w === 'string')
+        {
+            const map = { A: 4, B: 3, C: 2, D: 1 };
+            return map[w.toUpperCase()] || 1;
+        }
+        return Number(w) || 1;
+    }
+
+    /**
+     * Detect the adapter type from its constructor or methods.
+     * @returns {string} Adapter type identifier.
+     * @private
+     */
+    _detectAdapterType()
+    {
+        const adapter = this._adapter;
+        if (!adapter) return 'memory';
+        const name = adapter.constructor.name.toLowerCase();
+        if (name.includes('postgres')) return 'postgres';
+        if (name.includes('mysql')) return 'mysql';
+        if (name.includes('sqlite')) return 'sqlite';
+        if (name.includes('mongo')) return 'mongo';
+        if (name.includes('redis')) return 'redis';
+        if (name.includes('json')) return 'json';
+        return 'memory';
+    }
+}
+
+module.exports = { FullTextSearch };

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

@@ -0,0 +1,136 @@
+'use strict';
+
+/**
+ * @module seed/data/commerce
+ * @description Data pools for commerce, product, and company fake data.
+ */
+
+/** Adjectives applied to product names. */
+const PRODUCT_ADJECTIVES = [
+    'Ergonomic', 'Electronic', 'Smart', 'Professional', 'Ultra', 'Premium',
+    'Heavy-Duty', 'Lightweight', 'Compact', 'Portable', 'Advanced', 'Wireless',
+    'Digital', 'Classic', 'Modern', 'Handcrafted', 'Luxurious', 'Eco-Friendly',
+    'Industrial', 'Vintage', 'Rustic', 'Sleek', 'Durable', 'Flexible',
+    'Multi-Purpose', 'Automated', 'Intelligent', 'Refined', 'Next-Gen', 'Essential',
+];
+
+/** Materials for product names. */
+const PRODUCT_MATERIALS = [
+    'Steel', 'Wooden', 'Leather', 'Plastic', 'Marble', 'Metal', 'Concrete',
+    'Bronze', 'Bamboo', 'Aluminum', 'Carbon Fiber', 'Ceramic', 'Glass',
+    'Crystal', 'Silk', 'Cotton', 'Copper', 'Iron', 'Granite', 'Rubber',
+    'Titanium', 'Brass', 'Linen', 'Mesh', 'Polyester', 'Nylon', 'Wool',
+];
+
+/** Product category nouns. */
+const PRODUCT_NOUNS = [
+    'Chair', 'Table', 'Shirt', 'Ball', 'Gloves', 'Pants', 'Shoes', 'Hat',
+    'Keyboard', 'Mouse', 'Monitor', 'Laptop', 'Phone', 'Tablet', 'Speaker',
+    'Watch', 'Bag', 'Wallet', 'Coat', 'Glasses', 'Lamp', 'Desk', 'Shelf',
+    'Pillow', 'Blanket', 'Towel', 'Mug', 'Bottle', 'Bowl', 'Knife', 'Pan',
+    'Bike', 'Helmet', 'Rack', 'Stand', 'Holder', 'Case', 'Cover', 'Mount',
+    'Charger', 'Cable', 'Drive', 'Camera', 'Headphones', 'Microphone', 'Printer',
+    'Mat', 'Brush', 'Comb', 'Mirror', 'Clock', 'Frame', 'Candle', 'Vase',
+];
+
+/** Top-level product category names. */
+const CATEGORIES = [
+    'Electronics', 'Clothing & Apparel', 'Food & Beverages', 'Home & Garden',
+    'Sports & Outdoors', 'Books & Media', 'Toys & Games', 'Health & Beauty',
+    'Automotive', 'Office Supplies', 'Jewelry & Accessories', 'Pet Supplies',
+    'Baby & Kids', 'Tools & Hardware', 'Travel & Luggage', 'Music & Instruments',
+    'Art & Crafts', 'Software & Apps', 'Industrial Equipment', 'Collectibles',
+    'Furniture', 'Kitchen & Dining', 'Lighting', 'Garden Tools', 'Fitness',
+];
+
+/** Business department names. */
+const DEPARTMENTS = [
+    'Engineering', 'Marketing', 'Sales', 'Finance', 'Human Resources',
+    'Operations', 'Legal', 'Product', 'Design', 'Customer Success',
+    'Research & Development', 'IT', 'Security', 'Data Science', 'Supply Chain',
+    'Quality Assurance', 'Business Development', 'Communications', 'Analytics',
+    'Compliance', 'Strategy', 'Procurement', 'Manufacturing', 'Logistics',
+];
+
+/** First part of a generated company name. */
+const COMPANY_ADJECTIVES = [
+    'Innovative', 'Global', 'Dynamic', 'Advanced', 'Premier', 'Elite',
+    'National', 'Digital', 'Strategic', 'Integrated', 'Unified', 'Nexus',
+    'Alpha', 'Apex', 'Vertex', 'Summit', 'Pinnacle', 'Horizon', 'Stellar',
+    'Quantum', 'Fusion', 'Synergy', 'Core', 'Prime', 'Precision', 'Vantage',
+    'Catalyst', 'Axiom', 'Aether', 'Titanium', 'Ironclad', 'Luminary',
+];
+
+/** Second part of a generated company name. */
+const COMPANY_NOUNS = [
+    'Technologies', 'Solutions', 'Systems', 'Industries', 'Group',
+    'Partners', 'Ventures', 'Labs', 'Works', 'Consulting', 'Services',
+    'Analytics', 'Media', 'Networks', 'Designs', 'Innovations', 'Enterprises',
+    'Digital', 'Cloud', 'Data', 'Security', 'Health', 'Finance', 'Capital',
+    'Dynamics', 'Intelligence', 'Platforms', 'Insights', 'Studio', 'Agency',
+];
+
+/** Company legal-entity suffixes. */
+const COMPANY_SUFFIXES = [
+    'Inc.', 'LLC', 'Corp.', 'Ltd.', 'Co.', 'Group', 'Holdings', 'International',
+];
+
+/** Industry sector names. */
+const INDUSTRIES = [
+    'Information Technology', 'Financial Services', 'Healthcare', 'Retail',
+    'Manufacturing', 'Transportation & Logistics', 'Media & Entertainment',
+    'Telecommunications', 'Education', 'Real Estate', 'Hospitality & Tourism',
+    'Aerospace & Defense', 'Energy & Utilities', 'Agriculture', 'Construction',
+    'Pharmaceuticals', 'Automotive', 'Insurance', 'Non-Profit', 'Government',
+    'Consulting', 'E-commerce', 'Cybersecurity', 'Artificial Intelligence',
+    'Blockchain & Crypto', 'Biotechnology', 'Clean Energy', 'Legal Services',
+];
+
+/** Buzzword adjectives for catch phrases. */
+const CATCH_PHRASE_ADJECTIVES = [
+    'Adaptive', 'Advanced', 'Automated', 'Balanced', 'Business-focused',
+    'Centralized', 'Compatible', 'Configurable', 'Cross-platform', 'Customer-focused',
+    'Decentralized', 'Digitized', 'Distributed', 'Enhanced', 'Enterprise-wide',
+    'Ergonomic', 'Expanded', 'Face to face', 'Focused', 'Front-line',
+    'Fully-configurable', 'Function-based', 'Future-proofed', 'Horizontal',
+    'Implemented', 'Innovative', 'Integrated', 'Intuitive', 'Managed', 'Monitored',
+    'Multi-channelled', 'Multi-lateral', 'Multi-tiered', 'Networked', 'Object-based',
+    'Open-architected', 'Open-source', 'Optimized', 'Organic', 'Organized',
+    'Pre-emptive', 'Proactive', 'Profit-focused', 'Programmable', 'Progressive',
+    'Quality-focused', 'Re-engineered', 'Reactive', 'Reduced', 'Right-sized',
+    'Robust', 'Seamless', 'Secured', 'Self-enabling', 'Streamlined', 'Synchronized',
+    'Synergistic', 'Team-oriented', 'Universal', 'User-centric', 'User-friendly',
+    'Versatile', 'Virtual', 'Visionary', 'Vision-oriented',
+];
+
+/** Buzzword nouns for catch phrases. */
+const CATCH_PHRASE_NOUNS = [
+    'ability', 'access', 'adapter', 'algorithm', 'alliance', 'analyzer', 'archive',
+    'array', 'attitude', 'benchmark', 'capability', 'capacity', 'challenge',
+    'circuit', 'collaboration', 'complexity', 'concept', 'contingency',
+    'core', 'database', 'data-warehouse', 'definition', 'emulation', 'encoding',
+    'encryption', 'extranet', 'firmware', 'flexibility', 'focus group',
+    'forecast', 'frame', 'framework', 'function', 'functionalities', 'hub',
+    'implementation', 'info-mediaries', 'infrastructure', 'initiative', 'installation',
+    'instruction set', 'interface', 'internet solution', 'intranet', 'knowledge user',
+    'knowledge base', 'local area network', 'leverage', 'matrix', 'methodology',
+    'middleware', 'migration', 'model', 'moderator', 'moratorium', 'neural-net',
+    'open architecture', 'open system', 'orchestration', 'paradigm', 'policy',
+    'portal', 'pricing structure', 'process improvement', 'product', 'productivity',
+    'project', 'projection', 'protocol', 'throughput', 'time-frame', 'toolset',
+    'transition', 'utilisation', 'website', 'workforce',
+];
+
+module.exports = {
+    PRODUCT_ADJECTIVES,
+    PRODUCT_MATERIALS,
+    PRODUCT_NOUNS,
+    CATEGORIES,
+    DEPARTMENTS,
+    COMPANY_ADJECTIVES,
+    COMPANY_NOUNS,
+    COMPANY_SUFFIXES,
+    INDUSTRIES,
+    CATCH_PHRASE_ADJECTIVES,
+    CATCH_PHRASE_NOUNS,
+};

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

@@ -0,0 +1,111 @@
+'use strict';
+
+/**
+ * @module seed/data/internet
+ * @description Data pools for internet-related fake data generation.
+ */
+
+/** Public email providers (for Fake.email when provider is not specified). */
+const EMAIL_PROVIDERS = [
+    'gmail.com', 'yahoo.com', 'hotmail.com', 'outlook.com', 'icloud.com',
+    'protonmail.com', 'aol.com', 'live.com', 'msn.com', 'ymail.com',
+    'mail.com', 'zoho.com', 'fastmail.com', 'hey.com', 'tutanota.com',
+];
+
+/** Safe example domains that cannot belong to real people (RFC 2606). */
+const SAFE_DOMAINS = [
+    'example.com', 'example.org', 'example.net', 'test.com', 'test.org',
+    'demo.com', 'demo.org', 'sample.com', 'fake.io', 'acme.example',
+    'placeholder.dev', 'noreply.example', 'sandbox.example',
+];
+
+/** Common TLDs used for domain generation. */
+const TLDS = [
+    'com', 'net', 'org', 'io', 'dev', 'app', 'co', 'info', 'biz', 'us',
+    'uk', 'ca', 'au', 'de', 'fr', 'jp', 'in', 'br', 'mx', 'tech',
+    'site', 'online', 'store', 'shop', 'cloud', 'ai', 'xyz', 'me',
+];
+
+/** Adjectives for generated domain names. */
+const DOMAIN_ADJECTIVES = [
+    'quick', 'bright', 'dark', 'silent', 'loud', 'smart', 'wild', 'swift',
+    'bold', 'calm', 'crisp', 'deep', 'fast', 'fresh', 'grand', 'happy',
+    'keen', 'light', 'mighty', 'neat', 'open', 'proud', 'rapid', 'sharp',
+    'steady', 'strong', 'thin', 'tough', 'warm', 'wise', 'young', 'agile',
+    'blue', 'clever', 'cool', 'epic', 'free', 'great', 'huge', 'ideal',
+];
+
+/** Nouns for generated domain names. */
+const DOMAIN_NOUNS = [
+    'apple', 'arrow', 'atlas', 'base', 'beam', 'blade', 'bridge', 'byte',
+    'cache', 'chain', 'cloud', 'code', 'core', 'crest', 'cube', 'data',
+    'deck', 'edge', 'field', 'flame', 'fleet', 'flow', 'forge', 'frame',
+    'gate', 'grid', 'grove', 'harbor', 'heap', 'hub', 'index', 'kit',
+    'lab', 'leaf', 'link', 'loop', 'map', 'matrix', 'mesh', 'mint',
+    'node', 'orbit', 'path', 'peak', 'pixel', 'plugin', 'pod', 'port',
+    'prism', 'pulse', 'realm', 'ridge', 'root', 'route', 'scope', 'seed',
+    'shift', 'signal', 'site', 'snap', 'socket', 'source', 'spike', 'stack',
+    'storm', 'stream', 'summit', 'sync', 'thread', 'tide', 'token', 'tower',
+    'trace', 'vault', 'vector', 'vibe', 'vista', 'wave', 'wire', 'zone',
+];
+
+/**
+ * Username separator styles.
+ *   dot       → john.doe99
+ *   underscore → john_doe99
+ *   none      → johndoe99
+ */
+const USERNAME_SEPARATORS   = ['.', '_', ''];
+const USERNAME_STYLES       = ['dot', 'underscore', 'none', 'random'];
+
+/** Realistic browser user-agent strings for 5 major browsers. */
+const USER_AGENTS = [
+    // Chrome
+    'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 14_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+    'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36',
+    // Firefox
+    'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:121.0) Gecko/20100101 Firefox/121.0',
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 14.2; rv:121.0) Gecko/20100101 Firefox/121.0',
+    'Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:120.0) Gecko/20100101 Firefox/120.0',
+    // Safari
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 14_2_1) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.2 Safari/605.1.15',
+    'Mozilla/5.0 (iPhone; CPU iPhone OS 17_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.2 Mobile/15E148 Safari/604.1',
+    // Edge
+    'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36 Edg/120.0.0.0',
+    // Android Chrome
+    'Mozilla/5.0 (Linux; Android 14; Pixel 7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.6099.43 Mobile Safari/537.36',
+    // curl / bot style
+    'curl/7.88.1',
+    'python-requests/2.31.0',
+];
+
+/** MAC address segment values (OUIs from well-known vendors for realism). */
+const MAC_OUIS = [
+    '00:1A:2B', '00:50:56', '08:00:27', 'AC:BC:32', 'B8:27:EB',
+    'DC:A6:32', 'E4:5F:01', '3C:22:FB', '70:B3:D5', 'F4:5C:89',
+];
+
+/** Password character pool constants. */
+const CHARSET_LOWERCASE  = 'abcdefghijklmnopqrstuvwxyz';
+const CHARSET_UPPERCASE  = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+const CHARSET_DIGITS     = '0123456789';
+const CHARSET_SPECIAL    = '!@#$%^&*()-_=+[]{}|;:,.<>?';
+const CHARSET_AMBIGUOUS  = 'lI1O0';   // chars to optionally exclude
+
+module.exports = {
+    EMAIL_PROVIDERS,
+    SAFE_DOMAINS,
+    TLDS,
+    DOMAIN_ADJECTIVES,
+    DOMAIN_NOUNS,
+    USERNAME_SEPARATORS,
+    USERNAME_STYLES,
+    USER_AGENTS,
+    MAC_OUIS,
+    CHARSET_LOWERCASE,
+    CHARSET_UPPERCASE,
+    CHARSET_DIGITS,
+    CHARSET_SPECIAL,
+    CHARSET_AMBIGUOUS,
+};