fakeforge 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 [Your Name]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# fakeforge
+
+Zero-dependency, **seedable** fake data generator for tests, demos, and prototypes. Generate names, emails, phone numbers, addresses, and full person records — with the option to make output fully reproducible.
+
+## Why another fake-data library?
+
+- **Zero dependencies** — nothing to audit, tiny install.
+- **Seedable** — pass a seed and you get the *same* data every run, so your test snapshots don't break.
+- **Simple API** — one class, intuitive methods.
+
+## Install
+
+```bash
+npm install fakeforge
+```
+
+## Quick start
+
+```js
+const FakeForge = require('fakeforge');
+
+const fake = new FakeForge();
+
+fake.fullName();   // "Sofia Martinez"
+fake.email();      // "p.nguyen@gmail.com"
+fake.phone();      // "(415) 892-3310"
+fake.address();    // { street, city, state, stateAbbr, zip }
+fake.person();     // full record (see below)
+```
+
+Or grab the ready-made default instance:
+
+```js
+const { fake } = require('fakeforge');
+fake.fullName();
+```
+
+## Reproducible data with seeds
+
+Pass a number or string seed. The same seed always produces the same sequence — ideal for deterministic tests.
+
+```js
+const a = new FakeForge('my-seed');
+const b = new FakeForge('my-seed');
+
+a.fullName() === b.fullName(); // true
+```
+
+## API
+
+| Method | Returns |
+| --- | --- |
+| `firstName()` | First name |
+| `lastName()` | Last name |
+| `fullName()` | "First Last" |
+| `email(first?, last?)` | Email, derived from a name if given |
+| `phone(format?)` | Phone; `format` uses `#` as a digit placeholder |
+| `streetAddress()` | "123 Maple St" |
+| `city()` / `state(abbr?)` / `zip()` | Address parts |
+| `address()` | `{ street, city, state, stateAbbr, zip }` |
+| `number(min?, max?)` | Integer in range |
+| `bool(probability?)` | Boolean |
+| `pick(array)` | Random item from your array |
+| `uuid()` | v4-style UUID |
+| `date(start?, end?)` | Date in range |
+| `words(n?)` | n words of lorem ipsum |
+| `person()` | Full person record |
+| `array(method, n, ...args)` | Array of n results from a method |
+
+### Custom phone formats
+
+```js
+fake.phone('+1-###-###-####'); // "+1-415-892-3310"
+fake.phone('###.###.####');    // "415.892.3310"
+```
+
+### Generating many records
+
+```js
+const users = new FakeForge('users').array('person', 100);
+// 100 deterministic person objects
+```
+
+## Example person record
+
+```json
+{
+  "id": "a4e3c9e8-96c5-49ae-aa78-50692d103f9f",
+  "firstName": "Diego",
+  "lastName": "Davis",
+  "fullName": "Diego Davis",
+  "email": "ddavis@yahoo.com",
+  "phone": "(352) 762-6744",
+  "address": {
+    "street": "3432 Cedar Way",
+    "city": "Salem",
+    "state": "Georgia",
+    "stateAbbr": "GA",
+    "zip": "55495"
+  },
+  "birthDate": "1999-09-24"
+}
+```
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,210 @@
+'use strict';
+
+/* ============================================================
+ * fakeforge — zero-dependency, seedable fake data generator
+ * Single-file build. No subfolders, nothing to misplace.
+ * ============================================================ */
+
+/* ---- Seedable PRNG (mulberry32) ---- */
+
+function mulberry32(seed) {
+  let a = seed >>> 0;
+  return function () {
+    a |= 0;
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+function hashSeed(str) {
+  let h = 1779033703 ^ str.length;
+  for (let i = 0; i < str.length; i++) {
+    h = Math.imul(h ^ str.charCodeAt(i), 3432918353);
+    h = (h << 13) | (h >>> 19);
+  }
+  return h >>> 0;
+}
+
+class Random {
+  constructor(seed) {
+    if (seed === undefined || seed === null) {
+      this._next = Math.random;
+    } else if (typeof seed === 'string') {
+      this._next = mulberry32(hashSeed(seed));
+    } else {
+      this._next = mulberry32(Number(seed) >>> 0);
+    }
+  }
+  float() { return this._next(); }
+  int(min, max) { return Math.floor(this._next() * (max - min + 1)) + min; }
+  pick(arr) { return arr[Math.floor(this._next() * arr.length)]; }
+  sample(arr, n) {
+    const copy = arr.slice();
+    const out = [];
+    n = Math.min(n, copy.length);
+    for (let i = 0; i < n; i++) {
+      const idx = Math.floor(this._next() * copy.length);
+      out.push(copy.splice(idx, 1)[0]);
+    }
+    return out;
+  }
+  bool(probability = 0.5) { return this._next() < probability; }
+}
+
+/* ---- Data pools ---- */
+
+const firstNames = [
+  'James', 'Mary', 'Robert', 'Patricia', 'John', 'Jennifer', 'Michael', 'Linda',
+  'David', 'Elizabeth', 'William', 'Barbara', 'Richard', 'Susan', 'Joseph', 'Jessica',
+  'Thomas', 'Sarah', 'Charles', 'Karen', 'Christopher', 'Nancy', 'Daniel', 'Lisa',
+  'Matthew', 'Margaret', 'Anthony', 'Betty', 'Mark', 'Sandra', 'Aisha', 'Wei',
+  'Mateo', 'Sofia', 'Omar', 'Priya', 'Liam', 'Olivia', 'Noah', 'Emma',
+  'Yuki', 'Chen', 'Amara', 'Diego', 'Fatima', 'Ravi', 'Ingrid', 'Tomas'
+];
+
+const lastNames = [
+  'Smith', 'Johnson', 'Williams', 'Brown', 'Jones', 'Garcia', 'Miller', 'Davis',
+  'Rodriguez', 'Martinez', 'Hernandez', 'Lopez', 'Gonzalez', 'Wilson', 'Anderson',
+  'Thomas', 'Taylor', 'Moore', 'Jackson', 'Martin', 'Lee', 'Perez', 'Thompson',
+  'White', 'Harris', 'Sanchez', 'Clark', 'Ramirez', 'Lewis', 'Robinson', 'Walker',
+  'Nguyen', 'Kim', 'Patel', 'Khan', 'Singh', 'Chen', 'Wang', 'Ali',
+  'Okafor', 'Silva', 'Costa', 'Rossi', 'Muller', 'Schmidt', 'Novak', 'Ivanov'
+];
+
+const emailDomains = [
+  'gmail.com', 'yahoo.com', 'outlook.com', 'hotmail.com', 'icloud.com',
+  'proton.me', 'example.com', 'mail.com'
+];
+
+const streetNames = [
+  'Maple', 'Oak', 'Pine', 'Cedar', 'Elm', 'Washington', 'Lake', 'Hill',
+  'Park', 'Sunset', 'River', 'Spring', 'Highland', 'Forest', 'Meadow', 'Ridge',
+  'Lincoln', 'Jefferson', 'Madison', 'Franklin', 'Church', 'Market', 'Union', 'Center'
+];
+
+const streetTypes = ['St', 'Ave', 'Blvd', 'Rd', 'Ln', 'Dr', 'Ct', 'Way', 'Pl'];
+
+const cities = [
+  'Springfield', 'Riverside', 'Franklin', 'Greenville', 'Bristol', 'Clinton',
+  'Fairview', 'Salem', 'Madison', 'Georgetown', 'Arlington', 'Ashland',
+  'Burlington', 'Manchester', 'Oxford', 'Dover', 'Hudson', 'Kingston'
+];
+
+const states = [
+  { name: 'California', abbr: 'CA' }, { name: 'Texas', abbr: 'TX' },
+  { name: 'Florida', abbr: 'FL' }, { name: 'New York', abbr: 'NY' },
+  { name: 'Illinois', abbr: 'IL' }, { name: 'Ohio', abbr: 'OH' },
+  { name: 'Georgia', abbr: 'GA' }, { name: 'Washington', abbr: 'WA' },
+  { name: 'Arizona', abbr: 'AZ' }, { name: 'Colorado', abbr: 'CO' }
+];
+
+const lorem = [
+  'lorem', 'ipsum', 'dolor', 'sit', 'amet', 'consectetur', 'adipiscing', 'elit',
+  'sed', 'do', 'eiusmod', 'tempor', 'incididunt', 'ut', 'labore', 'et', 'dolore',
+  'magna', 'aliqua', 'enim', 'minim', 'veniam', 'quis', 'nostrud', 'exercitation'
+];
+
+/* ---- Main class ---- */
+
+class FakeForge {
+  /** @param {number|string} [seed] Same seed => same data. */
+  constructor(seed) {
+    this.rng = new Random(seed);
+  }
+
+  firstName() { return this.rng.pick(firstNames); }
+  lastName() { return this.rng.pick(lastNames); }
+  fullName() { return `${this.firstName()} ${this.lastName()}`; }
+
+  email(firstName, lastName) {
+    const first = (firstName || this.firstName()).toLowerCase();
+    const last = (lastName || this.lastName()).toLowerCase();
+    const domain = this.rng.pick(emailDomains);
+    const styles = [
+      `${first}.${last}`,
+      `${first}${last}`,
+      `${first}_${last}`,
+      `${first}${this.rng.int(1, 999)}`,
+      `${first[0]}${last}`
+    ];
+    const local = this.rng.pick(styles).replace(/[^a-z0-9._]/g, '');
+    return `${local}@${domain}`;
+  }
+
+  phone(format = '(###) ###-####') {
+    let out = '';
+    for (const ch of format) out += ch === '#' ? this.rng.int(0, 9) : ch;
+    return out;
+  }
+
+  streetAddress() {
+    return `${this.rng.int(1, 9999)} ${this.rng.pick(streetNames)} ${this.rng.pick(streetTypes)}`;
+  }
+  city() { return this.rng.pick(cities); }
+  state(abbr = false) { const s = this.rng.pick(states); return abbr ? s.abbr : s.name; }
+  zip() { return String(this.rng.int(10000, 99999)); }
+
+  address() {
+    const s = this.rng.pick(states);
+    return {
+      street: this.streetAddress(),
+      city: this.city(),
+      state: s.name,
+      stateAbbr: s.abbr,
+      zip: String(this.rng.int(10000, 99999))
+    };
+  }
+
+  number(min = 0, max = 100) { return this.rng.int(min, max); }
+  bool(probability = 0.5) { return this.rng.bool(probability); }
+  pick(arr) { return this.rng.pick(arr); }
+
+  uuid() {
+    const hex = '0123456789abcdef';
+    let out = '';
+    for (let i = 0; i < 36; i++) {
+      if (i === 8 || i === 13 || i === 18 || i === 23) out += '-';
+      else if (i === 14) out += '4';
+      else if (i === 19) out += hex[(this.rng.int(0, 15) & 0x3) | 0x8];
+      else out += hex[this.rng.int(0, 15)];
+    }
+    return out;
+  }
+
+  date(start, end) {
+    const s = (start ? new Date(start) : new Date(Date.now() - 3.15e11)).getTime();
+    const e = (end ? new Date(end) : new Date()).getTime();
+    return new Date(s + this.rng.float() * (e - s));
+  }
+
+  words(n = 3) { return this.rng.sample(lorem, Math.min(n, lorem.length)).join(' '); }
+
+  person() {
+    const first = this.firstName();
+    const last = this.lastName();
+    return {
+      id: this.uuid(),
+      firstName: first,
+      lastName: last,
+      fullName: `${first} ${last}`,
+      email: this.email(first, last),
+      phone: this.phone(),
+      address: this.address(),
+      birthDate: this.date('1950-01-01', '2005-12-31').toISOString().slice(0, 10)
+    };
+  }
+
+  array(method, n, ...args) {
+    const out = [];
+    for (let i = 0; i < n; i++) out.push(this[method](...args));
+    return out;
+  }
+}
+
+const defaultInstance = new FakeForge();
+
+module.exports = FakeForge;
+module.exports.FakeForge = FakeForge;
+module.exports.fake = defaultInstance;

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "fakeforge",
+  "version": "1.0.0",
+  "description": "Zero-dependency, seedable fake data generator — names, emails, phones, addresses and full person records for testing and prototyping.",
+  "main": "index.js",
+  "type": "commonjs",
+  "scripts": {
+    "test": "node test.js"
+  },
+  "files": [
+    "index.js"
+  ],
+  "keywords": [
+    "fake",
+    "faker",
+    "mock",
+    "dummy-data",
+    "test-data",
+    "seed",
+    "seedable",
+    "random",
+    "generator",
+    "names",
+    "email",
+    "address"
+  ],
+  "author": "mohen_96",
+  "license": "MIT",
+  "engines": {
+    "node": ">=14"
+  }
+}