@zerotal/testing 1.0.0

package/src/fake.ts

@@ -0,0 +1,462 @@
+/**
+ * @zerotal/testing — fake data generator
+ *
+ * South-African-flavoured faker for use in factories, seeders, and tests.
+ * Zero external dependencies — all data lives in data.ts.
+ *
+ * @example
+ * import { fake } from '@zerotal/testing';
+ *
+ * fake.name()                     // "Sipho Dlamini"
+ * fake.email()                    // "sipho.dlamini73@gmail.com"
+ * fake.email({ corporate: true }) // "sipho.dlamini@shoprite.co.za"
+ * fake.sentence()                 // medium sentence
+ * fake.sentence({ length: 'long' })
+ * fake.paragraphs(3)              // 3 paragraphs joined with \n\n
+ * fake.phone()                    // "071 234 5678"
+ */
+
+import {
+  firstNames,
+  lastNames,
+  cities,
+  provinces,
+  suburbs,
+  streetNames,
+  streetTypes,
+  emailDomains,
+  companies,
+  mobileAreaCodes,
+  postalCodes,
+  jobTitles,
+  departments,
+  loremNouns,
+  loremAdjectives,
+  loremVerbs,
+  loremFillers,
+  titlePhrases,
+} from "./data.ts";
+import { Str } from "@zerotal/core";
+
+// ── Internal helpers ──────────────────────────────────────────────────────────
+
+function rng(): number {
+  return Math.random();
+}
+
+function pick<T>(arr: readonly T[]): T {
+  return arr[Math.floor(rng() * arr.length)] as T;
+}
+
+function pickN<T>(arr: readonly T[], n: number): T[] {
+  const copy = [...arr];
+  const out: T[] = [];
+  for (let i = 0; i < n && copy.length > 0; i++) {
+    const idx = Math.floor(rng() * copy.length);
+    out.push(copy[idx] as T);
+    copy.splice(idx, 1);
+  }
+  return out;
+}
+
+function int(min: number, max: number): number {
+  return Math.floor(rng() * (max - min + 1)) + min;
+}
+
+const capitalize = (s: string): string => Str.capitalize(s);
+const slugify = (text: string): string => Str.slugify(text);
+
+function companyDomain(company: string): string {
+  // Well-known abbreviations
+  const abbrevs: Record<string, string> = {
+    "first national bank": "fnb",
+    "pick n pay": "picknpay",
+    "amazon web services": "aws",
+    "microsoft south africa": "microsoft",
+    "old mutual": "oldmutual",
+    "standard bank": "standardbank",
+    discovery: "discovery",
+    "dis-chem": "dischem",
+    "cell c": "cellc",
+  };
+  const key = company.toLowerCase();
+  const base = abbrevs[key] ?? key.replace(/[^a-z0-9]/g, "");
+  return `${base}.co.za`;
+}
+
+// ── Sentence / paragraph builder ──────────────────────────────────────────────
+
+type TextLength = "short" | "medium" | "long";
+
+const WORD_COUNTS: Record<TextLength, [number, number]> = {
+  short: [5, 9],
+  medium: [11, 18],
+  long: [22, 38],
+};
+
+const SENTENCE_COUNTS: Record<TextLength, [number, number]> = {
+  short: [2, 3],
+  medium: [3, 5],
+  long: [5, 8],
+};
+
+// Sentence patterns — each token is picked from the right pool
+// Format:  N=noun  A=adjective  V=verb  F=filler  W=any
+const PATTERNS: Array<Array<"N" | "A" | "V" | "F">> = [
+  ["A", "N", "V", "N"],
+  ["N", "V", "A", "N"],
+  ["A", "N", "V", "A", "N"],
+  ["V", "A", "N", "F", "N"],
+  ["N", "F", "N", "V", "A", "N"],
+  ["A", "N", "F", "V", "N"],
+  ["V", "N", "A", "F", "A", "N"],
+  ["N", "V", "N", "F", "N"],
+];
+
+function buildSentence(): string {
+  const pattern = pick(PATTERNS);
+  const tokens = pattern.map((t) => {
+    switch (t) {
+      case "N":
+        return pick(loremNouns);
+      case "A":
+        return pick(loremAdjectives);
+      case "V":
+        return pick(loremVerbs);
+      case "F":
+        return pick(loremFillers);
+    }
+  });
+  return capitalize(tokens.join(" ")) + ".";
+}
+
+function buildWordSentence(wordCount: number): string {
+  // Single words only. The vocab holds a few noun *phrases* ("blog post"), so
+  // picking `wordCount` entries from the whole pool yields a sentence of more
+  // than `wordCount` words whenever a phrase is drawn — `fake.word()` already
+  // filters them out for the same reason.
+  const pool = singleWords();
+  const words = Array.from({ length: wordCount }, () => pick(pool));
+  return capitalize(words.join(" ")) + ".";
+}
+
+/** The lorem vocabulary with multi-word phrases removed. */
+function singleWords(): string[] {
+  return [...loremNouns, ...loremAdjectives, ...loremVerbs].filter((w) => !w.includes(" "));
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+export const fake = {
+  // ── Primitives ──────────────────────────────────────────────────────────────
+
+  /** Random element from an array. */
+  pick<T>(arr: readonly T[]): T {
+    return pick(arr);
+  },
+
+  /** Shuffled copy of an array. */
+  shuffle<T>(arr: readonly T[]): T[] {
+    const out = [...arr];
+    for (let i = out.length - 1; i > 0; i--) {
+      const j = Math.floor(rng() * (i + 1));
+      [out[i], out[j]] = [out[j]!, out[i]!];
+    }
+    return out;
+  },
+
+  /** n unique random elements from an array. */
+  sample<T>(arr: readonly T[], n: number): T[] {
+    return pickN(arr, n);
+  },
+
+  /** Random integer between min and max (inclusive). */
+  number(min = 0, max = 1000): number {
+    return int(min, max);
+  },
+
+  /** Random float between min and max with optional decimal places. */
+  float(min = 0, max = 1, decimals = 2): number {
+    const raw = rng() * (max - min) + min;
+    return Number(raw.toFixed(decimals));
+  },
+
+  /** Random boolean, optionally weighted (default 50/50). */
+  boolean(trueWeight = 0.5): boolean {
+    return rng() < trueWeight;
+  },
+
+  /** UUID v4. */
+  uuid(): string {
+    return crypto.randomUUID();
+  },
+
+  /** Random alphanumeric string of given length. */
+  string(length = 10): string {
+    const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
+    let out = "";
+    for (let i = 0; i < length; i++) out += pick([...chars]);
+    return out;
+  },
+
+  /**
+   * Return value with given probability; null otherwise.
+   * @example fake.maybe(fake.phone(), 0.7)  // phone 70% of the time
+   */
+  maybe<T>(value: T, probability = 0.5): T | null {
+    return rng() < probability ? value : null;
+  },
+
+  // ── Dates ────────────────────────────────────────────────────────────────────
+
+  /** Random Date in the given range (defaults: last year → now). */
+  date(from?: Date, to?: Date): Date {
+    const end = (to ?? new Date()).getTime();
+    const start = (from ?? new Date(end - 365 * 24 * 60 * 60 * 1000)).getTime();
+    return new Date(start + rng() * (end - start));
+  },
+
+  /** Random Date in the past, within `years` years. */
+  pastDate(years = 3): Date {
+    const now = Date.now();
+    return new Date(now - rng() * years * 365 * 24 * 60 * 60 * 1000);
+  },
+
+  /** Random Date in the future, within `years` years. */
+  futureDate(years = 2): Date {
+    const now = Date.now();
+    return new Date(now + rng() * years * 365 * 24 * 60 * 60 * 1000);
+  },
+
+  /** ISO 8601 date string (e.g. "2024-03-15T10:23:00.000Z"). */
+  isoDate(from?: Date, to?: Date): string {
+    return fake.date(from, to).toISOString();
+  },
+
+  /** Unix timestamp in seconds. */
+  timestamp(): number {
+    return Math.floor(fake.date().getTime() / 1000);
+  },
+
+  // ── Names ────────────────────────────────────────────────────────────────────
+
+  /** Random first name drawn from the full SA-diverse pool. */
+  firstName(): string {
+    return pick(firstNames);
+  },
+
+  /** Random last name drawn from the full SA-diverse pool. */
+  lastName(): string {
+    return pick(lastNames);
+  },
+
+  /** Full name: "FirstName LastName". */
+  name(): string {
+    return `${fake.firstName()} ${fake.lastName()}`;
+  },
+
+  // ── Contact ──────────────────────────────────────────────────────────────────
+
+  /**
+   * Realistic email address.
+   *
+   * @param opts.name      Seed string (defaults to a generated name).
+   * @param opts.corporate If true, uses a slugified company domain (.co.za).
+   * @param opts.number    Append a number to the local part (default: 50% chance).
+   */
+  email(opts?: { name?: string; corporate?: boolean; number?: boolean }): string {
+    const rawName = opts?.name ?? fake.name();
+    const parts = rawName
+      .toLowerCase()
+      .replace(/[^a-z\s]/g, "")
+      .split(/\s+/)
+      .filter(Boolean);
+    const style = int(0, 2);
+
+    let local: string;
+    if (style === 0 && parts.length >= 2) {
+      local = `${parts[0]}.${parts[1]}`;
+    } else if (style === 1 && parts.length >= 2) {
+      local = `${parts[0]![0]}${parts[1]}`;
+    } else {
+      local = parts[0] ?? "user";
+    }
+
+    const addNum = opts?.number ?? rng() < 0.4;
+    if (addNum) local += int(1, 99);
+
+    const domain = opts?.corporate ? companyDomain(pick(companies)) : pick(emailDomains);
+
+    return `${local}@${domain}`;
+  },
+
+  /**
+   * SA mobile phone number.
+   * Format: "0XX XXX XXXX"
+   */
+  phone(): string {
+    const area = pick(mobileAreaCodes);
+    const mid = String(int(100, 999));
+    const last = String(int(1000, 9999));
+    return `${area} ${mid} ${last}`;
+  },
+
+  // ── Location ─────────────────────────────────────────────────────────────────
+
+  city(): string {
+    return pick(cities);
+  },
+  province(): string {
+    return pick(provinces);
+  },
+  suburb(): string {
+    return pick(suburbs);
+  },
+
+  /** "12 Mandela Street" style address line. */
+  streetAddress(): string {
+    return `${int(1, 299)} ${pick(streetNames)} ${pick(streetTypes)}`;
+  },
+
+  /** 4-digit SA postal code. */
+  postalCode(): string {
+    return pick(postalCodes);
+  },
+
+  /** Full postal address. */
+  address(): string {
+    return [
+      fake.streetAddress(),
+      pick(suburbs),
+      pick(cities),
+      pick(provinces),
+      fake.postalCode(),
+    ].join(", ");
+  },
+
+  // ── Organisation ─────────────────────────────────────────────────────────────
+
+  company(): string {
+    return pick(companies);
+  },
+  jobTitle(): string {
+    return pick(jobTitles);
+  },
+  department(): string {
+    return pick(departments);
+  },
+
+  // ── Text ─────────────────────────────────────────────────────────────────────
+
+  /** Single word from the lorem vocabulary. */
+  word(): string {
+    // The vocab includes a few noun *phrases* ("blog post", "trade show") that are
+    // useful for sentences but not for a single word — exclude anything with a space.
+    return pick(singleWords());
+  },
+
+  /** n space-joined words. */
+  words(n = 5): string {
+    // Single words, so `words(n).split(" ")` really has n entries.
+    const pool = singleWords();
+    return Array.from({ length: n }, () => pick(pool)).join(" ");
+  },
+
+  /**
+   * A single sentence.
+   *
+   * @param opts.length  'short' (5-9 words) | 'medium' (11-18) | 'long' (22-38). Default: 'medium'.
+   * @param opts.words   Exact word count override.
+   */
+  sentence(opts?: { length?: TextLength; words?: number }): string {
+    if (opts?.words) return buildWordSentence(opts.words);
+    const len = opts?.length ?? "medium";
+    const [min, max] = WORD_COUNTS[len];
+    if (len === "short") return buildSentence();
+    return buildWordSentence(int(min, max));
+  },
+
+  /** n sentences joined with a space. */
+  sentences(n = 3, opts?: { length?: TextLength }): string {
+    return Array.from({ length: n }, () => fake.sentence(opts)).join(" ");
+  },
+
+  /**
+   * A paragraph of sentences.
+   *
+   * @param opts.length  'short' (2-3 sentences) | 'medium' (3-5) | 'long' (5-8). Default: 'medium'.
+   */
+  paragraph(opts?: { length?: TextLength }): string {
+    const len = opts?.length ?? "medium";
+    const [min, max] = SENTENCE_COUNTS[len];
+    const n = int(min, max);
+    return Array.from({ length: n }, () => fake.sentence({ length: len })).join(" ");
+  },
+
+  /** n paragraphs joined with a blank line. */
+  paragraphs(n = 3, opts?: { length?: TextLength }): string {
+    return Array.from({ length: n }, () => fake.paragraph(opts)).join("\n\n");
+  },
+
+  // ── Titles & slugs ───────────────────────────────────────────────────────────
+
+  /**
+   * A realistic article/post title.
+   * Returns a pre-written phrase 70% of the time; constructs one otherwise.
+   */
+  title(): string {
+    if (rng() < 0.7) return pick(titlePhrases);
+    const adj = capitalize(pick(loremAdjectives));
+    const noun = capitalize(pick(loremNouns));
+    const verb = capitalize(pick(loremVerbs));
+    return pick([
+      `${verb}ing ${adj} ${noun}s`,
+      `Understanding ${adj} ${noun}`,
+      `A Guide to ${adj} ${noun}`,
+      `${adj} ${noun}: Best Practices`,
+      `How to ${verb} Your ${noun}`,
+      `The ${adj} ${noun} Playbook`,
+    ]);
+  },
+
+  /** URL-safe slug from a title or generated one. */
+  slug(text?: string): string {
+    return slugify(text ?? fake.title());
+  },
+
+  // ── URLs & passwords ─────────────────────────────────────────────────────────
+
+  /** Random HTTPS URL. */
+  url(opts?: { path?: boolean }): string {
+    const domain = companyDomain(pick(companies));
+    const path = opts?.path !== false ? `/${fake.slug()}-${int(1, 999)}` : "";
+    return `https://www.${domain}${path}`;
+  },
+
+  /**
+   * Realistic-looking password.
+   *
+   * @param opts.length  Total length (default: 12).
+   * @param opts.simple  If true, lowercase + digits only (for test fixtures).
+   */
+  password(opts?: { length?: number; simple?: boolean }): string {
+    const len = opts?.length ?? 12;
+    if (opts?.simple) return fake.string(len);
+
+    const upper = "ABCDEFGHJKLMNPQRSTUVWXYZ";
+    const lower = "abcdefghjkmnpqrstuvwxyz";
+    const digits = "23456789";
+    const syms = "!@#$%^&*";
+
+    // Guarantee at least one of each type
+    const out = [pick([...upper]), pick([...lower]), pick([...digits]), pick([...syms])];
+
+    const all = upper + lower + digits + syms;
+    while (out.length < len) out.push(pick([...all]));
+
+    // Shuffle to avoid predictable prefix
+    return fake.shuffle(out).join("");
+  },
+};
+
+export type Fake = typeof fake;

package/src/fakeFile.ts

@@ -0,0 +1,229 @@
+/**
+ * @zerotal/testing — file builders for upload tests.
+ *
+ * The files here are *real*: a PNG built by `fakeFile.image()` has the PNG
+ * signature, a valid IHDR at the size you asked for, and compressed pixel data.
+ * That matters because the framework does not trust what an upload claims to
+ * be — `UploadedFile.store()` and `detectType()` sniff the leading bytes and
+ * name the stored file from what they find. A placeholder full of zero bytes
+ * declared as `image/png` would sail through a `mimes` check and then be stored
+ * as `application/octet-stream`, so the test would pass while the behaviour it
+ * describes never happened.
+ *
+ * @example
+ * import { fakeFile } from '@zerotal/testing';
+ *
+ * await app.multipart('/avatar', { avatar: fakeFile.image('me.png') });
+ * await app.multipart('/docs', { doc: fakeFile.pdf('terms.pdf') });
+ * await app.multipart('/import', { csv: fakeFile.create('rows.csv', 'a,b\n1,2', 'text/csv') });
+ */
+
+import { deflateSync } from "node:zlib";
+
+export const fakeFile = {
+  /**
+   * A file with exactly the contents you give it.
+   *
+   * @param name - Filename sent with the upload.
+   * @param content - File contents; a string is encoded as UTF-8.
+   * @param type - MIME type declared for the part.
+   */
+  create(name: string, content: string | Uint8Array = "", type = "text/plain"): File {
+    const parts: BlobPart[] = [typeof content === "string" ? content : (content as BlobPart)];
+    return new File(parts, name, { type });
+  },
+
+  /**
+   * A file of `size` bytes, for exercising size limits. The contents are filler,
+   * so use {@link image} or {@link pdf} when the bytes have to be recognisable.
+   *
+   * @example
+   * // Over a 2 MB limit
+   * fakeFile.sized('huge.bin', 3 * 1024 * 1024);
+   */
+  sized(name: string, size: number, type = "application/octet-stream"): File {
+    return new File([new Uint8Array(size)], name, { type });
+  },
+
+  /**
+   * A valid PNG image of the given dimensions.
+   *
+   * @param name - Filename sent with the upload.
+   * @param options.width - Pixel width (default 10).
+   * @param options.height - Pixel height (default 10).
+   *
+   * @example
+   * fakeFile.image('avatar.png', { width: 64, height: 64 });
+   */
+  image(name = "image.png", options: { width?: number; height?: number } = {}): File {
+    const { width = 10, height = 10 } = options;
+    return new File([_png(width, height)], name, { type: "image/png" });
+  },
+
+  /** A minimal but structurally valid JPEG. */
+  jpeg(name = "image.jpg"): File {
+    return new File([_jpeg()], name, { type: "image/jpeg" });
+  },
+
+  /** A minimal GIF89a image. */
+  gif(name = "image.gif"): File {
+    const bytes = new Uint8Array([
+      0x47,
+      0x49,
+      0x46,
+      0x38,
+      0x39,
+      0x61, // "GIF89a"
+      0x01,
+      0x00,
+      0x01,
+      0x00,
+      0x80,
+      0x00,
+      0x00,
+      0x00,
+      0x00,
+      0x00,
+      0xff,
+      0xff,
+      0xff,
+      0x21,
+      0xf9,
+      0x04,
+      0x01,
+      0x00,
+      0x00,
+      0x00,
+      0x00,
+      0x2c,
+      0x00,
+      0x00,
+      0x00,
+      0x00,
+      0x01,
+      0x00,
+      0x01,
+      0x00,
+      0x00,
+      0x02,
+      0x02,
+      0x44,
+      0x01,
+      0x00,
+      0x3b,
+    ]);
+    return new File([bytes], name, { type: "image/gif" });
+  },
+
+  /** A minimal one-page PDF. */
+  pdf(name = "document.pdf"): File {
+    return new File([_PDF], name, { type: "application/pdf" });
+  },
+};
+
+export type FakeFile = typeof fakeFile;
+
+// ── Format builders ───────────────────────────────────────────────────────────
+
+/** Build a solid-white PNG of `width`×`height`. */
+function _png(width: number, height: number): Uint8Array<ArrayBuffer> {
+  // Raw scanlines: each row is a filter byte (0 = None) followed by RGB triples.
+  const stride = width * 3 + 1;
+  const raw = new Uint8Array(stride * height);
+  for (let y = 0; y < height; y++) {
+    raw[y * stride] = 0;
+    raw.fill(0xff, y * stride + 1, y * stride + stride);
+  }
+
+  const ihdr = new Uint8Array(13);
+  const view = new DataView(ihdr.buffer);
+  view.setUint32(0, width);
+  view.setUint32(4, height);
+  ihdr[8] = 8; // bit depth
+  ihdr[9] = 2; // colour type: truecolour
+  ihdr[10] = 0; // compression
+  ihdr[11] = 0; // filter
+  ihdr[12] = 0; // interlace
+
+  return _concat([
+    new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    _chunk("IHDR", ihdr),
+    _chunk("IDAT", new Uint8Array(deflateSync(raw))),
+    _chunk("IEND", new Uint8Array(0)),
+  ]);
+}
+
+/** length ‖ type ‖ data ‖ CRC32(type ‖ data) — the PNG chunk layout. */
+function _chunk(type: string, data: Uint8Array): Uint8Array<ArrayBuffer> {
+  const typeBytes = new Uint8Array([...type].map((c) => c.charCodeAt(0)));
+  const out = new Uint8Array(12 + data.length);
+  const view = new DataView(out.buffer);
+  view.setUint32(0, data.length);
+  out.set(typeBytes, 4);
+  out.set(data, 8);
+  view.setUint32(8 + data.length, _crc32(_concat([typeBytes, data])));
+  return out;
+}
+
+let _crcTable: Uint32Array | null = null;
+
+function _crc32(bytes: Uint8Array): number {
+  if (!_crcTable) {
+    _crcTable = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+      let c = n;
+      for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+      _crcTable[n] = c >>> 0;
+    }
+  }
+  let crc = 0xffffffff;
+  for (const byte of bytes) crc = _crcTable[(crc ^ byte) & 0xff]! ^ (crc >>> 8);
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+/** SOI ‖ JFIF APP0 ‖ EOI — enough for the signature check and a real header. */
+function _jpeg(): Uint8Array<ArrayBuffer> {
+  return new Uint8Array([
+    0xff,
+    0xd8, // SOI
+    0xff,
+    0xe0,
+    0x00,
+    0x10, // APP0, length 16
+    0x4a,
+    0x46,
+    0x49,
+    0x46,
+    0x00, // "JFIF\0"
+    0x01,
+    0x01, // version 1.1
+    0x00, // units: none
+    0x00,
+    0x01,
+    0x00,
+    0x01, // density 1×1
+    0x00,
+    0x00, // no thumbnail
+    0xff,
+    0xd9, // EOI
+  ]);
+}
+
+const _PDF = `%PDF-1.4
+1 0 obj<</Type/Catalog/Pages 2 0 R>>endobj
+2 0 obj<</Type/Pages/Kids[3 0 R]/Count 1>>endobj
+3 0 obj<</Type/Page/Parent 2 0 R/MediaBox[0 0 612 792]>>endobj
+trailer<</Root 1 0 R>>
+%%EOF
+`;
+
+function _concat(chunks: Uint8Array[]): Uint8Array<ArrayBuffer> {
+  const total = chunks.reduce((sum, c) => sum + c.length, 0);
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return out;
+}

package/src/global.d.ts

@@ -0,0 +1,20 @@
+// Ambient declarations specific to this package.
+// Bun, Node (node:*), and bun:test types come from @types/bun (→ bun-types).
+// Only declarations bun-types does NOT provide are kept here.
+
+// ── Bun globals ───────────────────────────────────────────────────────────────
+interface Request {
+  readonly params?: Record<string, string>;
+  readonly cookies: Bun.CookieMap;
+}
+
+interface BunProcess { exited: Promise<number> }
+
+interface SQLInstance {
+  <T = Record<string, unknown>>(
+    strings: TemplateStringsArray,
+    ...values: unknown[]
+  ): Promise<T[]>;
+  begin<T>(fn: (tx: SQLInstance) => Promise<T>): Promise<T>;
+  end(): Promise<void>;
+}