tina4-nodejs 3.0.0-rc.2

package/packages/core/src/errorOverlay.ts

@@ -0,0 +1,278 @@
+/**
+ * Tina4 Debug — Rich error overlay for development mode.
+ *
+ * Renders a professional, syntax-highlighted HTML error page when an unhandled
+ * exception occurs in a route handler.
+ *
+ *   import { renderErrorOverlay, renderProductionError, isDebugMode } from "./errorOverlay.js";
+ *
+ *   try {
+ *     await handler(req, res);
+ *   } catch (err) {
+ *     const html = isDebugMode()
+ *       ? renderErrorOverlay(err as Error, req)
+ *       : renderProductionError();
+ *     res.html(html, 500);
+ *   }
+ *
+ * Only activate when TINA4_DEBUG is true.
+ * In production, call renderProductionError() instead.
+ */
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { isTruthy } from "./dotenv.js";
+
+// ── Colour palette (Catppuccin Mocha) ────────────────────────────────────
+const BG = "#1e1e2e";
+const SURFACE = "#313244";
+const OVERLAY = "#45475a";
+const TEXT = "#cdd6f4";
+const SUBTEXT = "#a6adc8";
+const RED = "#f38ba8";
+const YELLOW = "#f9e2af";
+const BLUE = "#89b4fa";
+const GREEN = "#a6e3a1";
+const LAVENDER = "#b4befe";
+const PEACH = "#fab387";
+const ERROR_LINE_BG = "rgba(243,139,168,0.15)";
+
+const CONTEXT_LINES = 7;
+
+interface StackFrame {
+  file: string;
+  line: number;
+  column: number;
+  func: string;
+}
+
+function esc(text: string): string {
+  return text
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+function parseStack(stack: string): StackFrame[] {
+  const frames: StackFrame[] = [];
+  const lines = stack.split("\n");
+  for (const line of lines) {
+    // Match: "    at functionName (file:line:col)"
+    let match = line.match(/^\s*at\s+(.+?)\s+\((.+?):(\d+):(\d+)\)/);
+    if (match) {
+      frames.push({ func: match[1], file: match[2], line: parseInt(match[3], 10), column: parseInt(match[4], 10) });
+      continue;
+    }
+    // Match: "    at file:line:col"
+    match = line.match(/^\s*at\s+(.+?):(\d+):(\d+)/);
+    if (match) {
+      frames.push({ func: "{anonymous}", file: match[1], line: parseInt(match[2], 10), column: parseInt(match[3], 10) });
+    }
+  }
+  return frames;
+}
+
+function readSourceLines(filename: string, lineno: number): Array<[number, string, boolean]> {
+  try {
+    const absPath = resolve(filename);
+    const content = readFileSync(absPath, "utf-8");
+    const allLines = content.split("\n");
+    const start = Math.max(0, lineno - CONTEXT_LINES - 1);
+    const end = Math.min(allLines.length, lineno + CONTEXT_LINES);
+    const result: Array<[number, string, boolean]> = [];
+    for (let i = start; i < end; i++) {
+      const num = i + 1;
+      result.push([num, allLines[i] ?? "", num === lineno]);
+    }
+    return result;
+  } catch {
+    return [];
+  }
+}
+
+function formatSourceBlock(filename: string, lineno: number): string {
+  const lines = readSourceLines(filename, lineno);
+  if (lines.length === 0) return "";
+
+  const rows = lines.map(([num, text, isError]) => {
+    const bg = isError ? `background:${ERROR_LINE_BG};` : "";
+    const marker = isError ? "&#x25b6;" : " ";
+    return `<div style="${bg}display:flex;padding:1px 0;">`
+      + `<span style="color:${YELLOW};min-width:3.5em;text-align:right;padding-right:1em;user-select:none;">${num}</span>`
+      + `<span style="color:${RED};width:1.2em;user-select:none;">${marker}</span>`
+      + `<span style="color:${TEXT};white-space:pre-wrap;tab-size:4;">${esc(text)}</span>`
+      + `</div>`;
+  }).join("\n");
+
+  return `<div style="background:${SURFACE};border-radius:6px;padding:12px;overflow-x:auto;`
+    + `font-family:'SF Mono','Fira Code','Consolas',monospace;font-size:13px;line-height:1.6;">`
+    + rows + `</div>`;
+}
+
+function formatFrame(frame: StackFrame): string {
+  const source = frame.file && frame.line > 0 ? formatSourceBlock(frame.file, frame.line) : "";
+  return `<div style="margin-bottom:16px;">`
+    + `<div style="margin-bottom:4px;">`
+    + `<span style="color:${BLUE};">${esc(frame.file)}</span>`
+    + `<span style="color:${SUBTEXT};"> : </span>`
+    + `<span style="color:${YELLOW};">${frame.line}</span>`
+    + `<span style="color:${SUBTEXT};"> in </span>`
+    + `<span style="color:${GREEN};">${esc(frame.func)}</span>`
+    + `</div>`
+    + source
+    + `</div>`;
+}
+
+function collapsible(title: string, content: string, openByDefault = false): string {
+  const open = openByDefault ? " open" : "";
+  return `<details style="margin-top:16px;"${open}>`
+    + `<summary style="cursor:pointer;color:${LAVENDER};font-weight:600;font-size:15px;`
+    + `padding:8px 0;user-select:none;">${esc(title)}</summary>`
+    + `<div style="padding:8px 0;">${content}</div>`
+    + `</details>`;
+}
+
+function table(pairs: Array<[string, string]>): string {
+  if (pairs.length === 0) return `<span style="color:${SUBTEXT};">None</span>`;
+  const rows = pairs.map(([key, val]) =>
+    `<tr>`
+    + `<td style="color:${PEACH};padding:4px 16px 4px 0;vertical-align:top;white-space:nowrap;">${esc(key)}</td>`
+    + `<td style="color:${TEXT};padding:4px 0;word-break:break-all;">${esc(val)}</td>`
+    + `</tr>`
+  ).join("");
+  return `<table style="border-collapse:collapse;width:100%;">${rows}</table>`;
+}
+
+/**
+ * Render a rich HTML error overlay.
+ *
+ * @param error - The caught error.
+ * @param request - Optional request object with method, url, headers, etc.
+ * @returns Complete HTML page string.
+ */
+export function renderErrorOverlay(error: Error, request?: any): string {
+  const excType = error.constructor?.name ?? "Error";
+  const excMsg = error.message ?? String(error);
+  const frames = error.stack ? parseStack(error.stack) : [];
+
+  // ── Stack trace ──
+  let framesHtml = "";
+  for (const frame of frames) {
+    framesHtml += formatFrame(frame);
+  }
+
+  // ── Request info ──
+  const requestPairs: Array<[string, string]> = [];
+  if (request != null) {
+    for (const attr of ["method", "url", "path"]) {
+      if (request[attr] != null) requestPairs.push([attr, String(request[attr])]);
+    }
+    if (request.headers && typeof request.headers === "object") {
+      for (const [hk, hv] of Object.entries(request.headers)) {
+        requestPairs.push([`headers.${hk}`, String(hv)]);
+      }
+    }
+    if (request.params && typeof request.params === "object") {
+      for (const [pk, pv] of Object.entries(request.params)) {
+        requestPairs.push([`params.${pk}`, String(pv)]);
+      }
+    }
+    if (request.query && typeof request.query === "object") {
+      for (const [qk, qv] of Object.entries(request.query)) {
+        requestPairs.push([`query.${qk}`, String(qv)]);
+      }
+    }
+  }
+  const requestSection = requestPairs.length > 0
+    ? collapsible("Request Details", table(requestPairs))
+    : "";
+
+  // ── Environment ──
+  const envPairs: Array<[string, string]> = [
+    ["Framework", "Tina4 Node.js"],
+    ["Node.js", process.version],
+    ["Platform", process.platform],
+    ["Arch", process.arch],
+    ["Debug", process.env.TINA4_DEBUG ?? "false"],
+    ["Log Level", process.env.TINA4_LOG_LEVEL ?? "ERROR"],
+  ];
+  const envSection = collapsible("Environment", table(envPairs));
+  const stackSection = collapsible("Stack Trace", framesHtml, true);
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Tina4 Error — ${esc(excType)}</title>
+<style>
+*{margin:0;padding:0;box-sizing:border-box;}
+body{background:${BG};color:${TEXT};font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;padding:24px;line-height:1.5;}
+</style>
+</head>
+<body>
+<div style="max-width:960px;margin:0 auto;">
+  <div style="margin-bottom:24px;">
+    <div style="display:flex;align-items:center;gap:12px;margin-bottom:12px;">
+      <span style="background:${RED};color:${BG};padding:4px 12px;border-radius:4px;font-weight:700;font-size:13px;text-transform:uppercase;">Error</span>
+      <span style="color:${SUBTEXT};font-size:14px;">Tina4 Debug Overlay</span>
+    </div>
+    <h1 style="color:${RED};font-size:28px;font-weight:700;margin-bottom:8px;">${esc(excType)}</h1>
+    <p style="color:${TEXT};font-size:18px;font-family:'SF Mono','Fira Code','Consolas',monospace;background:${SURFACE};padding:12px 16px;border-radius:6px;border-left:4px solid ${RED};">${esc(excMsg)}</p>
+  </div>
+  ${stackSection}
+  ${requestSection}
+  ${envSection}
+  <div style="margin-top:32px;padding-top:16px;border-top:1px solid ${OVERLAY};color:${SUBTEXT};font-size:12px;">
+    Tina4 Debug Overlay &mdash; This page is only shown in debug mode. Set TINA4_DEBUG=false in production.
+  </div>
+</div>
+</body>
+</html>`;
+}
+
+/**
+ * Render a safe, generic error page for production.
+ */
+export function renderProductionError(statusCode = 500, message = "Internal Server Error", path = ""): string {
+  const codeColor = statusCode === 403 ? "#f59e0b" : statusCode === 404 ? "#3b82f6" : "#ef4444";
+  const pathHtml = path ? `<div class="error-path">${esc(path)}</div><br>` : "";
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${statusCode} — ${esc(message)}</title>
+<style>
+* { box-sizing: border-box; margin: 0; padding: 0; }
+body { font-family: system-ui, -apple-system, sans-serif; background: #0f172a; color: #e2e8f0; min-height: 100vh; display: flex; align-items: center; justify-content: center; }
+.error-card { background: #1e293b; border: 1px solid #334155; border-radius: 1rem; padding: 3rem; text-align: center; max-width: 520px; width: 90%; }
+.error-code { font-size: 8rem; font-weight: 900; color: ${codeColor}; opacity: 0.6; line-height: 1; margin-bottom: 0.5rem; }
+.error-title { font-size: 1.5rem; font-weight: 700; margin-bottom: 0.75rem; }
+.error-msg { color: #94a3b8; font-size: 1rem; margin-bottom: 1.5rem; line-height: 1.5; }
+.error-path { font-family: 'SF Mono', monospace; background: #0f172a; color: ${codeColor}; padding: 0.5rem 1rem; border-radius: 0.5rem; font-size: 0.85rem; word-break: break-all; margin-bottom: 1.5rem; display: inline-block; }
+.error-home { display: inline-block; padding: 0.6rem 2rem; background: #3b82f6; color: #fff; text-decoration: none; border-radius: 0.5rem; font-size: 0.9rem; font-weight: 600; }
+.error-home:hover { opacity: 0.9; }
+.logo { font-size: 1.5rem; margin-bottom: 1rem; opacity: 0.5; }
+</style>
+</head>
+<body>
+<div class="error-card">
+    <div class="error-code">${statusCode}</div>
+    <div class="error-title">${esc(message)}</div>
+    <div class="error-msg">Something went wrong while processing your request.</div>
+    ${pathHtml}
+    <a href="/" class="error-home">Go Home</a>
+</div>
+</body>
+</html>`;
+}
+
+/**
+ * Check if TINA4_DEBUG is enabled.
+ */
+export function isDebugMode(): boolean {
+  return isTruthy(process.env.TINA4_DEBUG);
+}

package/packages/core/src/events.ts

@@ -0,0 +1,112 @@
+/**
+ * Tina4 Events — Simple observer pattern for decoupled communication.
+ *
+ * Zero-dependency event system. Fire events, register listeners.
+ *
+ *   Events.on("user.created", (user) => console.log(`Welcome ${user.name}!`));
+ *   Events.emit("user.created", { name: "Alice", email: "alice@example.com" });
+ *
+ * One-time listeners:
+ *
+ *   Events.once("app.ready", () => console.log("App started!"));
+ */
+
+interface ListenerEntry {
+    priority: number;
+    callback: (...args: unknown[]) => void;
+    once: boolean;
+}
+
+const _listeners: Map<string, ListenerEntry[]> = new Map();
+
+function getEntries(event: string): ListenerEntry[] {
+    let entries = _listeners.get(event);
+    if (!entries) {
+        entries = [];
+        _listeners.set(event, entries);
+    }
+    return entries;
+}
+
+export class Events {
+    /**
+     * Register a listener for an event.
+     * Higher priority runs first.
+     */
+    static on(event: string, callback: (...args: unknown[]) => void, priority: number = 0): void {
+        const entries = getEntries(event);
+        entries.push({ priority, callback, once: false });
+        entries.sort((a, b) => b.priority - a.priority);
+    }
+
+    /**
+     * Register a listener that fires only once then auto-removes.
+     */
+    static once(event: string, callback: (...args: unknown[]) => void, priority: number = 0): void {
+        const entries = getEntries(event);
+        entries.push({ priority, callback, once: true });
+        entries.sort((a, b) => b.priority - a.priority);
+    }
+
+    /**
+     * Remove a specific listener, or all listeners for an event.
+     *
+     *   Events.off("user.created", handler)  // remove specific
+     *   Events.off("user.created")           // remove all for event
+     */
+    static off(event: string, callback?: (...args: unknown[]) => void): void {
+        if (callback === undefined) {
+            _listeners.delete(event);
+        } else {
+            const entries = _listeners.get(event);
+            if (entries) {
+                const filtered = entries.filter((e) => e.callback !== callback);
+                _listeners.set(event, filtered);
+            }
+        }
+    }
+
+    /**
+     * Fire an event synchronously. Returns array of listener results.
+     */
+    static emit(event: string, ...args: unknown[]): unknown[] {
+        const entries = _listeners.get(event);
+        if (!entries) return [];
+
+        const snapshot = [...entries];
+        const results: unknown[] = [];
+
+        for (const entry of snapshot) {
+            if (entry.once) {
+                const idx = entries.indexOf(entry);
+                if (idx !== -1) entries.splice(idx, 1);
+            }
+            results.push(entry.callback(...args));
+        }
+
+        return results;
+    }
+
+    /**
+     * Get all listener callbacks for an event (in priority order).
+     */
+    static listeners(event: string): Array<(...args: unknown[]) => void> {
+        const entries = _listeners.get(event);
+        if (!entries) return [];
+        return entries.map((e) => e.callback);
+    }
+
+    /**
+     * List all registered event names.
+     */
+    static events(): string[] {
+        return [..._listeners.keys()];
+    }
+
+    /**
+     * Remove all listeners for all events.
+     */
+    static clear(): void {
+        _listeners.clear();
+    }
+}

package/packages/core/src/fakeData.ts

@@ -0,0 +1,309 @@
+// Tina4 FakeData — Fake data generation and database seeding, zero dependencies.
+// Instance-based with optional seeded PRNG for deterministic output.
+
+import { randomInt, randomUUID } from "node:crypto";
+import { existsSync, readdirSync } from "node:fs";
+import { resolve, join } from "node:path";
+
+// ── Word Banks ───────────────────────────────────────────────────
+
+const FIRST_NAMES = [
+  "Alice", "Bob", "Charlie", "Diana", "Eve", "Frank", "Grace", "Henry",
+  "Ivy", "Jack", "Kate", "Leo", "Mia", "Noah", "Olivia", "Pete",
+  "Quinn", "Rose", "Sam", "Tina", "Uma", "Vince", "Wendy", "Xander",
+  "Yara", "Zane", "Anna", "Ben", "Chloe", "Dan", "Emma", "Felix",
+  "Gina", "Hugo", "Iris", "Jake", "Lily", "Max", "Nora", "Oscar",
+  "Penny", "Ray", "Sara", "Tom", "Vera", "Will", "Xena", "Yves",
+  "Zara", "Amber", "Blake", "Clara",
+];
+
+const LAST_NAMES = [
+  "Smith", "Johnson", "Williams", "Brown", "Jones", "Garcia", "Miller",
+  "Davis", "Rodriguez", "Martinez", "Hernandez", "Lopez", "Wilson",
+  "Anderson", "Thomas", "Taylor", "Moore", "Jackson", "Martin", "Lee",
+  "Perez", "Thompson", "White", "Harris", "Clark", "Lewis", "Young",
+  "Walker", "Hall", "Allen", "King", "Wright", "Scott", "Green",
+  "Adams", "Baker", "Nelson", "Carter", "Mitchell", "Roberts", "Turner",
+  "Phillips", "Campbell", "Parker", "Evans", "Edwards", "Collins",
+  "Stewart", "Morris", "Murphy", "Cook",
+];
+
+const DOMAINS = ["example.com", "test.org", "demo.net", "mail.dev", "inbox.io"];
+
+const WORDS = [
+  "the", "quick", "brown", "fox", "jumps", "over", "lazy", "dog",
+  "lorem", "ipsum", "dolor", "sit", "amet", "consectetur", "adipiscing",
+  "elit", "sed", "do", "eiusmod", "tempor", "incididunt", "ut", "labore",
+  "magna", "aliqua", "enim", "minim", "veniam", "quis", "nostrud",
+  "exercitation", "ullamco", "laboris", "nisi", "aliquip", "commodo",
+  "consequat", "duis", "aute", "irure", "reprehenderit", "voluptate",
+];
+
+const CITIES = [
+  "New York", "London", "Tokyo", "Paris", "Sydney", "Berlin", "Toronto",
+  "Cape Town", "Mumbai", "Singapore", "Dubai", "Amsterdam", "Seoul",
+  "Barcelona", "Melbourne", "Stockholm", "Vienna", "Zurich", "Oslo",
+  "Helsinki", "Prague", "Warsaw", "Dublin", "Brussels", "Lisbon",
+];
+
+const COUNTRIES = [
+  "United States", "United Kingdom", "Japan", "France", "Australia",
+  "Germany", "Canada", "South Africa", "India", "Singapore", "UAE",
+  "Netherlands", "South Korea", "Spain", "Brazil", "Italy", "Mexico",
+  "Sweden", "Switzerland", "Norway",
+];
+
+const STREETS = [
+  "Main St", "Oak Ave", "Park Rd", "Cedar Ln", "Elm St", "Pine Dr",
+  "Maple Way", "River Rd", "Lake Blvd", "Hill Ct", "Valley View",
+  "Sunset Blvd", "Broadway", "Church St", "Mill Rd",
+];
+
+const JOB_TITLES = [
+  "Software Engineer", "Product Manager", "Data Analyst", "Designer",
+  "DevOps Engineer", "QA Engineer", "Project Manager", "CTO",
+  "Marketing Manager", "Sales Director", "HR Manager", "Accountant",
+  "Consultant", "Architect", "Team Lead", "VP Engineering",
+  "Frontend Developer", "Backend Developer", "Full Stack Developer",
+  "Systems Administrator",
+];
+
+const COLORS = [
+  "red", "blue", "green", "yellow", "purple", "orange", "pink",
+  "cyan", "magenta", "teal", "indigo", "violet", "coral", "salmon",
+  "turquoise", "maroon", "navy", "olive", "silver", "gold",
+];
+
+const CURRENCIES = [
+  "USD", "EUR", "GBP", "JPY", "AUD", "CAD", "CHF", "CNY",
+  "SEK", "NZD", "MXN", "SGD", "HKD", "NOK", "ZAR", "INR",
+];
+
+// ── Seeded PRNG (mulberry32) ─────────────────────────────────────
+
+/**
+ * Mulberry32: a simple 32-bit seeded PRNG.
+ * Returns a function that produces values in [0, 1).
+ */
+function mulberry32(seed: number): () => number {
+  let s = seed | 0;
+  return () => {
+    s = (s + 0x6D2B79F5) | 0;
+    let t = Math.imul(s ^ (s >>> 15), 1 | s);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+// ── FakeData Class ───────────────────────────────────────────────
+
+export class FakeData {
+  private rng: () => number;
+  private seeded: boolean;
+
+  constructor(seed?: number) {
+    if (seed !== undefined) {
+      this.rng = mulberry32(seed);
+      this.seeded = true;
+    } else {
+      this.rng = Math.random;
+      this.seeded = false;
+    }
+  }
+
+  /** Static factory — create a seeded FakeData instance. */
+  static seed(seed: number): FakeData {
+    return new FakeData(seed);
+  }
+
+  /** Returns a random integer in [min, max) using the instance PRNG. */
+  private randInt(min: number, max: number): number {
+    if (this.seeded) {
+      return min + Math.floor(this.rng() * (max - min));
+    }
+    return randomInt(min, max);
+  }
+
+  /** Pick a random element from an array. */
+  private pick<T>(arr: readonly T[]): T {
+    return arr[this.randInt(0, arr.length)];
+  }
+
+  firstName(): string {
+    return this.pick(FIRST_NAMES);
+  }
+
+  lastName(): string {
+    return this.pick(LAST_NAMES);
+  }
+
+  fullName(): string {
+    return `${this.firstName()} ${this.lastName()}`;
+  }
+
+  email(): string {
+    const first = this.firstName().toLowerCase();
+    const last = this.lastName().toLowerCase();
+    const domain = this.pick(DOMAINS);
+    return `${first}.${last}@${domain}`;
+  }
+
+  phone(): string {
+    const area = this.randInt(200, 1000);
+    const mid = this.randInt(100, 1000);
+    const end = this.randInt(1000, 10000);
+    return `+1 (${area}) ${mid}-${end}`;
+  }
+
+  address(): string {
+    const num = this.randInt(1, 1000);
+    const street = this.pick(STREETS);
+    const city = this.pick(CITIES);
+    return `${num} ${street}, ${city}`;
+  }
+
+  city(): string {
+    return this.pick(CITIES);
+  }
+
+  country(): string {
+    return this.pick(COUNTRIES);
+  }
+
+  zipCode(): string {
+    return String(this.randInt(10000, 100000));
+  }
+
+  company(): string {
+    const last = this.pick(LAST_NAMES);
+    const suffixes = ["Inc", "LLC", "Corp", "Ltd", "Group", "Solutions", "Tech"];
+    return `${last} ${this.pick(suffixes)}`;
+  }
+
+  jobTitle(): string {
+    return this.pick(JOB_TITLES);
+  }
+
+  paragraph(sentences = 4): string {
+    const parts: string[] = [];
+    for (let i = 0; i < sentences; i++) {
+      parts.push(this.sentence(this.randInt(5, 13)));
+    }
+    return parts.join(" ");
+  }
+
+  sentence(words = 8): string {
+    const parts: string[] = [];
+    for (let i = 0; i < words; i++) {
+      parts.push(this.pick(WORDS));
+    }
+    const s = parts.join(" ");
+    return s.charAt(0).toUpperCase() + s.slice(1) + ".";
+  }
+
+  word(): string {
+    return this.pick(WORDS);
+  }
+
+  integer(min = 0, max = 10000): number {
+    return this.randInt(min, max + 1);
+  }
+
+  float(min = 0, max = 1000, decimals = 2): number {
+    const raw = min + this.rng() * (max - min);
+    return Number(raw.toFixed(decimals));
+  }
+
+  boolean(): boolean {
+    return this.randInt(0, 2) === 1;
+  }
+
+  date(start?: string, end?: string): string {
+    const startDate = start ? new Date(start) : new Date("2020-01-01");
+    const endDate = end ? new Date(end) : new Date("2025-12-31");
+    const diffDays = Math.floor((endDate.getTime() - startDate.getTime()) / 86400000);
+    const offset = this.randInt(0, diffDays + 1);
+    const d = new Date(startDate.getTime() + offset * 86400000);
+    const yyyy = d.getFullYear();
+    const mm = String(d.getMonth() + 1).padStart(2, "0");
+    const dd = String(d.getDate()).padStart(2, "0");
+    return `${yyyy}-${mm}-${dd}`;
+  }
+
+  uuid(): string {
+    if (this.seeded) {
+      // Generate a UUID-like string from seeded PRNG
+      const hex = () => this.randInt(0, 16).toString(16);
+      const block = (n: number) => Array.from({ length: n }, hex).join("");
+      return `${block(8)}-${block(4)}-${block(4)}-${block(4)}-${block(12)}`;
+    }
+    return randomUUID();
+  }
+
+  url(): string {
+    const domain = this.pick(DOMAINS);
+    const p1 = this.pick(WORDS);
+    const p2 = this.pick(WORDS);
+    return `https://${domain}/${p1}/${p2}`;
+  }
+
+  ipAddress(): string {
+    return `${this.randInt(1, 256)}.${this.randInt(0, 256)}.${this.randInt(0, 256)}.${this.randInt(1, 256)}`;
+  }
+
+  color(): string {
+    return this.pick(COLORS);
+  }
+
+  hexColor(): string {
+    const hex = this.randInt(0, 0x1000000).toString(16).padStart(6, "0");
+    return `#${hex}`;
+  }
+
+  /** Returns fake test credit card numbers (Luhn-valid test patterns). */
+  creditCard(): string {
+    const prefixes = ["4111111111111111", "5500000000000004", "340000000000009", "30000000000004"];
+    return this.pick(prefixes);
+  }
+
+  currency(): string {
+    return this.pick(CURRENCIES);
+  }
+
+  /**
+   * Run seed files from a directory. Each file should export a default async function.
+   * Returns an array of executed file paths.
+   */
+  async runSeeds(seedDir?: string): Promise<string[]> {
+    const dir = resolve(seedDir ?? "src/seeds");
+    if (!existsSync(dir)) return [];
+    const files = readdirSync(dir)
+      .filter((f) => f.endsWith(".ts") || f.endsWith(".js"))
+      .sort();
+    const executed: string[] = [];
+    for (const file of files) {
+      const fullPath = join(dir, file);
+      try {
+        const mod = await import(fullPath);
+        if (typeof mod.default === "function") {
+          await mod.default();
+        }
+        executed.push(fullPath);
+      } catch {
+        // skip failed seed files
+      }
+    }
+    return executed;
+  }
+
+  /**
+   * Run a generator function `count` times and return the results.
+   */
+  run(fn: () => Record<string, unknown>, count = 1): Record<string, unknown>[] {
+    const results: Record<string, unknown>[] = [];
+    for (let i = 0; i < count; i++) {
+      results.push(fn());
+    }
+    return results;
+  }
+}