@mandujs/core 0.41.2 → 0.43.0

package/src/i18n/locale-resolver.ts

@@ -1,214 +1,214 @@
-/**
- * Phase 18.μ — locale resolution.
- *
- * Given a request + i18n config, return the active {@link ResolvedLocale}.
- * Resolution order depends on `config.strategy`:
- *
- *   path-prefix → URL path segment → cookie → Accept-Language → default
- *   domain      → Host header      → cookie → Accept-Language → default
- *   header      → Accept-Language  → cookie → default
- *   cookie      → Cookie           → Accept-Language → default
- *
- * In every mode, an invalid locale signal (e.g. `/fr/docs` when `fr`
- * isn't configured) falls through to the next signal — invalid inputs
- * never short-circuit to an error. The final tier is always the
- * configured `defaultLocale` or `fallback`.
- *
- * This module is pure; it never touches the server registry or
- * `ctx.cookies`. Callers assemble the result and bolt it onto the
- * request via `ManduContext` — see `runtime/server.ts` μ dispatch
- * section.
- */
-
-import type { I18nDefinition, LocaleCode, ResolvedLocale } from "./types";
-import { DEFAULT_I18N_COOKIE } from "./define";
-
-/**
- * Remove a locale prefix from a URL pathname. Returns `{ locale, rest }`
- * when the pathname starts with `/<locale>(/...)?` for a known locale;
- * otherwise `{ locale: undefined, rest: pathname }`.
- *
- * Handles trailing + empty slashes so `/en`, `/en/`, `/en/docs` all
- * match `locale="en"` with the rest normalized to `"/"`, `"/"`, `"/docs"`.
- */
-export function stripLocalePrefix(
-  pathname: string,
-  locales: readonly LocaleCode[]
-): { locale: LocaleCode | undefined; rest: string } {
-  if (!pathname.startsWith("/")) {
-    return { locale: undefined, rest: pathname };
-  }
-  // Fast path: root.
-  if (pathname === "/") return { locale: undefined, rest: "/" };
-  const slashIdx = pathname.indexOf("/", 1);
-  const first = slashIdx === -1 ? pathname.slice(1) : pathname.slice(1, slashIdx);
-  if (!locales.includes(first)) {
-    return { locale: undefined, rest: pathname };
-  }
-  const rest = slashIdx === -1 ? "/" : pathname.slice(slashIdx);
-  return { locale: first, rest };
-}
-
-/**
- * Parse the `Accept-Language` header and pick the best supported
- * locale. Honours q-weights; falls back to undefined when nothing
- * matches.
- *
- * Comparison is case-insensitive, and we accept exact-match only
- * (no Accept-Language `en-US` → `en` widening — userland can list
- * both in `config.locales` when they want fallback behaviour).
- */
-export function parseAcceptLanguage(
-  header: string | null | undefined,
-  locales: readonly LocaleCode[]
-): LocaleCode | undefined {
-  if (!header) return undefined;
-  const want = new Map<string, number>();
-  for (const piece of header.split(",")) {
-    const [tagRaw, ...params] = piece.trim().split(";");
-    if (!tagRaw) continue;
-    const tag = tagRaw.trim().toLowerCase();
-    if (!tag || tag === "*") continue;
-    let q = 1.0;
-    for (const p of params) {
-      const m = /^\s*q\s*=\s*([0-9.]+)\s*$/i.exec(p);
-      if (m) q = parseFloat(m[1]!);
-    }
-    if (Number.isFinite(q) && q > 0 && !want.has(tag)) {
-      want.set(tag, q);
-    }
-  }
-  // Highest-q first; stable within equal weights.
-  const sorted = [...want.entries()].sort((a, b) => b[1] - a[1]);
-  const lowerLocales = locales.map((l) => ({ raw: l, lower: l.toLowerCase() }));
-  for (const [tag] of sorted) {
-    for (const { raw, lower } of lowerLocales) {
-      if (lower === tag) return raw;
-    }
-  }
-  // Widening fallback: `zh-TW` → try `zh` if only `zh` is configured.
-  for (const [tag] of sorted) {
-    const short = tag.split("-")[0]!;
-    for (const { raw, lower } of lowerLocales) {
-      if (lower === short) return raw;
-    }
-  }
-  return undefined;
-}
-
-/**
- * Read the locale cookie from the raw `Cookie` header. A nano-parser
- * so the resolver stays dependency-free (the `CookieManager` in
- * `filling/context.ts` lives on the request-wrapping side, not here).
- */
-export function readLocaleCookie(
-  header: string | null | undefined,
-  cookieName: string,
-  locales: readonly LocaleCode[]
-): LocaleCode | undefined {
-  if (!header) return undefined;
-  const target = `${cookieName}=`;
-  for (const piece of header.split(";")) {
-    const trimmed = piece.trim();
-    if (!trimmed.startsWith(target)) continue;
-    const raw = trimmed.slice(target.length);
-    try {
-      const value = decodeURIComponent(raw);
-      if (locales.includes(value)) return value;
-    } catch {
-      // fallthrough
-    }
-  }
-  return undefined;
-}
-
-/**
- * Resolve the locale for this request.
- *
- * The returned {@link ResolvedLocale} is always valid w.r.t.
- * `config.locales` — when every signal misses, we fall back to
- * `fallback` then `defaultLocale` (in that order) and flag the
- * result with `strategy: "fallback"` / `"default"`.
- */
-export function resolveLocale(
-  request: Request,
-  config: I18nDefinition
-): ResolvedLocale {
-  const url = new URL(request.url);
-  const cookieName = config.cookieName ?? DEFAULT_I18N_COOKIE;
-  const cookieHeader = request.headers.get("cookie");
-  const acceptLanguage = request.headers.get("accept-language");
-
-  switch (config.strategy) {
-    case "path-prefix": {
-      const { locale } = stripLocalePrefix(url.pathname, config.locales);
-      if (locale) {
-        return { code: locale, isDefault: false, strategy: "path-prefix", source: url.pathname };
-      }
-      const cookie = readLocaleCookie(cookieHeader, cookieName, config.locales);
-      if (cookie) {
-        return { code: cookie, isDefault: false, strategy: "cookie", source: cookieHeader ?? undefined };
-      }
-      const accept = parseAcceptLanguage(acceptLanguage, config.locales);
-      if (accept) {
-        return { code: accept, isDefault: false, strategy: "header", source: acceptLanguage ?? undefined };
-      }
-      return finalFallback(config);
-    }
-
-    case "domain": {
-      const host = request.headers.get("host") || url.host;
-      const mapped = config.domains?.[host];
-      if (mapped) {
-        return { code: mapped, isDefault: false, strategy: "domain", source: host };
-      }
-      const cookie = readLocaleCookie(cookieHeader, cookieName, config.locales);
-      if (cookie) {
-        return { code: cookie, isDefault: false, strategy: "cookie", source: cookieHeader ?? undefined };
-      }
-      const accept = parseAcceptLanguage(acceptLanguage, config.locales);
-      if (accept) {
-        return { code: accept, isDefault: false, strategy: "header", source: acceptLanguage ?? undefined };
-      }
-      return finalFallback(config);
-    }
-
-    case "cookie": {
-      const cookie = readLocaleCookie(cookieHeader, cookieName, config.locales);
-      if (cookie) {
-        return { code: cookie, isDefault: false, strategy: "cookie", source: cookieHeader ?? undefined };
-      }
-      const accept = parseAcceptLanguage(acceptLanguage, config.locales);
-      if (accept) {
-        return { code: accept, isDefault: false, strategy: "header", source: acceptLanguage ?? undefined };
-      }
-      return finalFallback(config);
-    }
-
-    case "header": {
-      const accept = parseAcceptLanguage(acceptLanguage, config.locales);
-      if (accept) {
-        return { code: accept, isDefault: false, strategy: "header", source: acceptLanguage ?? undefined };
-      }
-      const cookie = readLocaleCookie(cookieHeader, cookieName, config.locales);
-      if (cookie) {
-        return { code: cookie, isDefault: false, strategy: "cookie", source: cookieHeader ?? undefined };
-      }
-      return finalFallback(config);
-    }
-  }
-
-  // Exhaustive check
-  return finalFallback(config);
-}
-
-function finalFallback(config: I18nDefinition): ResolvedLocale {
-  if (config.fallback && config.fallback !== config.defaultLocale) {
-    return {
-      code: config.fallback,
-      isDefault: config.fallback === config.defaultLocale,
-      strategy: "fallback",
-    };
-  }
-  return { code: config.defaultLocale, isDefault: true, strategy: "default" };
-}
+/**
+ * Phase 18.μ — locale resolution.
+ *
+ * Given a request + i18n config, return the active {@link ResolvedLocale}.
+ * Resolution order depends on `config.strategy`:
+ *
+ *   path-prefix → URL path segment → cookie → Accept-Language → default
+ *   domain      → Host header      → cookie → Accept-Language → default
+ *   header      → Accept-Language  → cookie → default
+ *   cookie      → Cookie           → Accept-Language → default
+ *
+ * In every mode, an invalid locale signal (e.g. `/fr/docs` when `fr`
+ * isn't configured) falls through to the next signal — invalid inputs
+ * never short-circuit to an error. The final tier is always the
+ * configured `defaultLocale` or `fallback`.
+ *
+ * This module is pure; it never touches the server registry or
+ * `ctx.cookies`. Callers assemble the result and bolt it onto the
+ * request via `ManduContext` — see `runtime/server.ts` μ dispatch
+ * section.
+ */
+
+import type { I18nDefinition, LocaleCode, ResolvedLocale } from "./types";
+import { DEFAULT_I18N_COOKIE } from "./define";
+
+/**
+ * Remove a locale prefix from a URL pathname. Returns `{ locale, rest }`
+ * when the pathname starts with `/<locale>(/...)?` for a known locale;
+ * otherwise `{ locale: undefined, rest: pathname }`.
+ *
+ * Handles trailing + empty slashes so `/en`, `/en/`, `/en/docs` all
+ * match `locale="en"` with the rest normalized to `"/"`, `"/"`, `"/docs"`.
+ */
+export function stripLocalePrefix(
+  pathname: string,
+  locales: readonly LocaleCode[]
+): { locale: LocaleCode | undefined; rest: string } {
+  if (!pathname.startsWith("/")) {
+    return { locale: undefined, rest: pathname };
+  }
+  // Fast path: root.
+  if (pathname === "/") return { locale: undefined, rest: "/" };
+  const slashIdx = pathname.indexOf("/", 1);
+  const first = slashIdx === -1 ? pathname.slice(1) : pathname.slice(1, slashIdx);
+  if (!locales.includes(first)) {
+    return { locale: undefined, rest: pathname };
+  }
+  const rest = slashIdx === -1 ? "/" : pathname.slice(slashIdx);
+  return { locale: first, rest };
+}
+
+/**
+ * Parse the `Accept-Language` header and pick the best supported
+ * locale. Honours q-weights; falls back to undefined when nothing
+ * matches.
+ *
+ * Comparison is case-insensitive, and we accept exact-match only
+ * (no Accept-Language `en-US` → `en` widening — userland can list
+ * both in `config.locales` when they want fallback behaviour).
+ */
+export function parseAcceptLanguage(
+  header: string | null | undefined,
+  locales: readonly LocaleCode[]
+): LocaleCode | undefined {
+  if (!header) return undefined;
+  const want = new Map<string, number>();
+  for (const piece of header.split(",")) {
+    const [tagRaw, ...params] = piece.trim().split(";");
+    if (!tagRaw) continue;
+    const tag = tagRaw.trim().toLowerCase();
+    if (!tag || tag === "*") continue;
+    let q = 1.0;
+    for (const p of params) {
+      const m = /^\s*q\s*=\s*([0-9.]+)\s*$/i.exec(p);
+      if (m) q = parseFloat(m[1]!);
+    }
+    if (Number.isFinite(q) && q > 0 && !want.has(tag)) {
+      want.set(tag, q);
+    }
+  }
+  // Highest-q first; stable within equal weights.
+  const sorted = [...want.entries()].sort((a, b) => b[1] - a[1]);
+  const lowerLocales = locales.map((l) => ({ raw: l, lower: l.toLowerCase() }));
+  for (const [tag] of sorted) {
+    for (const { raw, lower } of lowerLocales) {
+      if (lower === tag) return raw;
+    }
+  }
+  // Widening fallback: `zh-TW` → try `zh` if only `zh` is configured.
+  for (const [tag] of sorted) {
+    const short = tag.split("-")[0]!;
+    for (const { raw, lower } of lowerLocales) {
+      if (lower === short) return raw;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Read the locale cookie from the raw `Cookie` header. A nano-parser
+ * so the resolver stays dependency-free (the `CookieManager` in
+ * `filling/context.ts` lives on the request-wrapping side, not here).
+ */
+export function readLocaleCookie(
+  header: string | null | undefined,
+  cookieName: string,
+  locales: readonly LocaleCode[]
+): LocaleCode | undefined {
+  if (!header) return undefined;
+  const target = `${cookieName}=`;
+  for (const piece of header.split(";")) {
+    const trimmed = piece.trim();
+    if (!trimmed.startsWith(target)) continue;
+    const raw = trimmed.slice(target.length);
+    try {
+      const value = decodeURIComponent(raw);
+      if (locales.includes(value)) return value;
+    } catch {
+      // fallthrough
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Resolve the locale for this request.
+ *
+ * The returned {@link ResolvedLocale} is always valid w.r.t.
+ * `config.locales` — when every signal misses, we fall back to
+ * `fallback` then `defaultLocale` (in that order) and flag the
+ * result with `strategy: "fallback"` / `"default"`.
+ */
+export function resolveLocale(
+  request: Request,
+  config: I18nDefinition
+): ResolvedLocale {
+  const url = new URL(request.url);
+  const cookieName = config.cookieName ?? DEFAULT_I18N_COOKIE;
+  const cookieHeader = request.headers.get("cookie");
+  const acceptLanguage = request.headers.get("accept-language");
+
+  switch (config.strategy) {
+    case "path-prefix": {
+      const { locale } = stripLocalePrefix(url.pathname, config.locales);
+      if (locale) {
+        return { code: locale, isDefault: false, strategy: "path-prefix", source: url.pathname };
+      }
+      const cookie = readLocaleCookie(cookieHeader, cookieName, config.locales);
+      if (cookie) {
+        return { code: cookie, isDefault: false, strategy: "cookie", source: cookieHeader ?? undefined };
+      }
+      const accept = parseAcceptLanguage(acceptLanguage, config.locales);
+      if (accept) {
+        return { code: accept, isDefault: false, strategy: "header", source: acceptLanguage ?? undefined };
+      }
+      return finalFallback(config);
+    }
+
+    case "domain": {
+      const host = request.headers.get("host") || url.host;
+      const mapped = config.domains?.[host];
+      if (mapped) {
+        return { code: mapped, isDefault: false, strategy: "domain", source: host };
+      }
+      const cookie = readLocaleCookie(cookieHeader, cookieName, config.locales);
+      if (cookie) {
+        return { code: cookie, isDefault: false, strategy: "cookie", source: cookieHeader ?? undefined };
+      }
+      const accept = parseAcceptLanguage(acceptLanguage, config.locales);
+      if (accept) {
+        return { code: accept, isDefault: false, strategy: "header", source: acceptLanguage ?? undefined };
+      }
+      return finalFallback(config);
+    }
+
+    case "cookie": {
+      const cookie = readLocaleCookie(cookieHeader, cookieName, config.locales);
+      if (cookie) {
+        return { code: cookie, isDefault: false, strategy: "cookie", source: cookieHeader ?? undefined };
+      }
+      const accept = parseAcceptLanguage(acceptLanguage, config.locales);
+      if (accept) {
+        return { code: accept, isDefault: false, strategy: "header", source: acceptLanguage ?? undefined };
+      }
+      return finalFallback(config);
+    }
+
+    case "header": {
+      const accept = parseAcceptLanguage(acceptLanguage, config.locales);
+      if (accept) {
+        return { code: accept, isDefault: false, strategy: "header", source: acceptLanguage ?? undefined };
+      }
+      const cookie = readLocaleCookie(cookieHeader, cookieName, config.locales);
+      if (cookie) {
+        return { code: cookie, isDefault: false, strategy: "cookie", source: cookieHeader ?? undefined };
+      }
+      return finalFallback(config);
+    }
+  }
+
+  // Exhaustive check
+  return finalFallback(config);
+}
+
+function finalFallback(config: I18nDefinition): ResolvedLocale {
+  if (config.fallback && config.fallback !== config.defaultLocale) {
+    return {
+      code: config.fallback,
+      isDefault: config.fallback === config.defaultLocale,
+      strategy: "fallback",
+    };
+  }
+  return { code: config.defaultLocale, isDefault: true, strategy: "default" };
+}

package/src/id/__tests__/id.test.ts

@@ -1,120 +1,120 @@
-import { describe, it, expect } from "bun:test";
-import { newId, newShortId, _resolveGenerator } from "../index";
-
-const UUID_REGEX =
-  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-const HEX8_REGEX = /^[0-9a-f]{8}$/i;
-
-interface CryptoLike {
-  randomUUIDv7?: () => string;
-  randomUUID: () => string;
-}
-
-describe("@mandujs/core/id — newId", () => {
-  it("returns a canonical UUID string", () => {
-    const id = newId();
-    expect(id).toMatch(UUID_REGEX);
-    expect(id.length).toBe(36);
-  });
-
-  it("returns distinct values across calls", () => {
-    const seen = new Set<string>();
-    for (let i = 0; i < 1000; i++) {
-      seen.add(newId());
-    }
-    expect(seen.size).toBe(1000);
-  });
-
-  it("is monotonic: lexicographic sort preserves generation order (v7 property)", async () => {
-    // Skip this invariant if neither global exposes v7 — the v4 fallback is
-    // correctly non-monotonic by design.
-    const c = globalThis.crypto as unknown as CryptoLike;
-    const bun = (globalThis as unknown as { Bun?: { randomUUIDv7?: () => string } }).Bun;
-    const v7Available =
-      typeof c.randomUUIDv7 === "function" ||
-      (bun !== undefined && typeof bun.randomUUIDv7 === "function");
-    if (!v7Available) {
-      return;
-    }
-
-    const generated: string[] = [];
-    for (let i = 0; i < 1000; i++) {
-      generated.push(newId());
-      // Force sub-millisecond spread across a few ticks so the time component
-      // advances at least once during the run. UUID v7 counter handles
-      // intra-millisecond monotonicity on its own.
-      if (i % 200 === 0) {
-        await new Promise((r) => setTimeout(r, 1));
-      }
-    }
-
-    const sorted = [...generated].sort();
-
-    // Require overall monotonic trend: the full sorted list equals the
-    // generation order. Bun's v7 implementation uses a per-millisecond
-    // monotonic counter, so ties within the same ms remain ordered.
-    expect(sorted).toEqual(generated);
-  });
-});
-
-describe("@mandujs/core/id — newShortId", () => {
-  it("returns exactly 8 hex characters", () => {
-    const short = newShortId();
-    expect(short).toMatch(HEX8_REGEX);
-    expect(short.length).toBe(8);
-  });
-
-  it("matches the prefix of the underlying UUID", () => {
-    // The short form is defined as the first 8 chars of the full ID, which is
-    // the first hex group of the UUID (pre-hyphen).
-    for (let i = 0; i < 50; i++) {
-      const short = newShortId();
-      expect(short).not.toContain("-");
-    }
-  });
-});
-
-describe("@mandujs/core/id — generator resolution", () => {
-  it("prefers crypto.randomUUIDv7 when present", () => {
-    const sentinel = "01912345-6789-7abc-def0-123456789abc";
-    const fakeCrypto = {
-      randomUUIDv7: () => sentinel,
-      randomUUID: () => "00000000-0000-4000-8000-000000000000",
-    };
-    const fakeBun = { randomUUIDv7: () => "SHOULD_NOT_BE_CALLED" };
-    const gen = _resolveGenerator(fakeCrypto, fakeBun);
-    expect(gen()).toBe(sentinel);
-  });
-
-  it("uses Bun.randomUUIDv7 when crypto.randomUUIDv7 is absent", () => {
-    const sentinel = "01abcdef-0123-7456-8789-abcdef012345";
-    const fakeCrypto = {
-      randomUUID: () => "00000000-0000-4000-8000-000000000000",
-    };
-    const fakeBun = { randomUUIDv7: () => sentinel };
-    const gen = _resolveGenerator(fakeCrypto, fakeBun);
-    expect(gen()).toBe(sentinel);
-  });
-
-  it("falls back to crypto.randomUUID when neither v7 source is available", () => {
-    const fakeCrypto = {
-      // No randomUUIDv7 — force fallback.
-      randomUUID: () => "00000000-0000-4000-8000-000000000000",
-    };
-    const fakeBun = {}; // also no randomUUIDv7
-    const gen = _resolveGenerator(fakeCrypto, fakeBun);
-    const id = gen();
-    expect(id).toMatch(UUID_REGEX);
-    expect(id.length).toBe(36);
-  });
-
-  it("falls back to crypto.randomUUID when Bun stub lacks randomUUIDv7", () => {
-    const fakeCrypto = {
-      randomUUID: () => "11111111-1111-4111-8111-111111111111",
-    };
-    // Pass an empty stub explicitly rather than `undefined` (which would
-    // trigger the default-parameter fallback to the real Bun global).
-    const gen = _resolveGenerator(fakeCrypto, {});
-    expect(gen()).toBe("11111111-1111-4111-8111-111111111111");
-  });
-});
+import { describe, it, expect } from "bun:test";
+import { newId, newShortId, _resolveGenerator } from "../index";
+
+const UUID_REGEX =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const HEX8_REGEX = /^[0-9a-f]{8}$/i;
+
+interface CryptoLike {
+  randomUUIDv7?: () => string;
+  randomUUID: () => string;
+}
+
+describe("@mandujs/core/id — newId", () => {
+  it("returns a canonical UUID string", () => {
+    const id = newId();
+    expect(id).toMatch(UUID_REGEX);
+    expect(id.length).toBe(36);
+  });
+
+  it("returns distinct values across calls", () => {
+    const seen = new Set<string>();
+    for (let i = 0; i < 1000; i++) {
+      seen.add(newId());
+    }
+    expect(seen.size).toBe(1000);
+  });
+
+  it("is monotonic: lexicographic sort preserves generation order (v7 property)", async () => {
+    // Skip this invariant if neither global exposes v7 — the v4 fallback is
+    // correctly non-monotonic by design.
+    const c = globalThis.crypto as unknown as CryptoLike;
+    const bun = (globalThis as unknown as { Bun?: { randomUUIDv7?: () => string } }).Bun;
+    const v7Available =
+      typeof c.randomUUIDv7 === "function" ||
+      (bun !== undefined && typeof bun.randomUUIDv7 === "function");
+    if (!v7Available) {
+      return;
+    }
+
+    const generated: string[] = [];
+    for (let i = 0; i < 1000; i++) {
+      generated.push(newId());
+      // Force sub-millisecond spread across a few ticks so the time component
+      // advances at least once during the run. UUID v7 counter handles
+      // intra-millisecond monotonicity on its own.
+      if (i % 200 === 0) {
+        await new Promise((r) => setTimeout(r, 1));
+      }
+    }
+
+    const sorted = [...generated].sort();
+
+    // Require overall monotonic trend: the full sorted list equals the
+    // generation order. Bun's v7 implementation uses a per-millisecond
+    // monotonic counter, so ties within the same ms remain ordered.
+    expect(sorted).toEqual(generated);
+  });
+});
+
+describe("@mandujs/core/id — newShortId", () => {
+  it("returns exactly 8 hex characters", () => {
+    const short = newShortId();
+    expect(short).toMatch(HEX8_REGEX);
+    expect(short.length).toBe(8);
+  });
+
+  it("matches the prefix of the underlying UUID", () => {
+    // The short form is defined as the first 8 chars of the full ID, which is
+    // the first hex group of the UUID (pre-hyphen).
+    for (let i = 0; i < 50; i++) {
+      const short = newShortId();
+      expect(short).not.toContain("-");
+    }
+  });
+});
+
+describe("@mandujs/core/id — generator resolution", () => {
+  it("prefers crypto.randomUUIDv7 when present", () => {
+    const sentinel = "01912345-6789-7abc-def0-123456789abc";
+    const fakeCrypto = {
+      randomUUIDv7: () => sentinel,
+      randomUUID: () => "00000000-0000-4000-8000-000000000000",
+    };
+    const fakeBun = { randomUUIDv7: () => "SHOULD_NOT_BE_CALLED" };
+    const gen = _resolveGenerator(fakeCrypto, fakeBun);
+    expect(gen()).toBe(sentinel);
+  });
+
+  it("uses Bun.randomUUIDv7 when crypto.randomUUIDv7 is absent", () => {
+    const sentinel = "01abcdef-0123-7456-8789-abcdef012345";
+    const fakeCrypto = {
+      randomUUID: () => "00000000-0000-4000-8000-000000000000",
+    };
+    const fakeBun = { randomUUIDv7: () => sentinel };
+    const gen = _resolveGenerator(fakeCrypto, fakeBun);
+    expect(gen()).toBe(sentinel);
+  });
+
+  it("falls back to crypto.randomUUID when neither v7 source is available", () => {
+    const fakeCrypto = {
+      // No randomUUIDv7 — force fallback.
+      randomUUID: () => "00000000-0000-4000-8000-000000000000",
+    };
+    const fakeBun = {}; // also no randomUUIDv7
+    const gen = _resolveGenerator(fakeCrypto, fakeBun);
+    const id = gen();
+    expect(id).toMatch(UUID_REGEX);
+    expect(id.length).toBe(36);
+  });
+
+  it("falls back to crypto.randomUUID when Bun stub lacks randomUUIDv7", () => {
+    const fakeCrypto = {
+      randomUUID: () => "11111111-1111-4111-8111-111111111111",
+    };
+    // Pass an empty stub explicitly rather than `undefined` (which would
+    // trigger the default-parameter fallback to the real Bun global).
+    const gen = _resolveGenerator(fakeCrypto, {});
+    expect(gen()).toBe("11111111-1111-4111-8111-111111111111");
+  });
+});