@mandujs/core 0.53.2 → 0.54.0

package/src/id/index.ts

@@ -1,105 +1,105 @@
-/**
- * @mandujs/core/id
- *
- * Centralized ID generation utilities.
- *
- * Uses `crypto.randomUUIDv7()` when available (Bun 1.3+) so that generated IDs
- * are time-ordered — lexicographic string sort matches chronological creation
- * order. This makes v7 UUIDs ideal for log correlation, database primary keys,
- * and any context where sortability is useful.
- *
- * On older runtimes we fall back to `crypto.randomUUID()` (v4). The fallback
- * emits a single dev-only warning so integrators notice the reduced guarantee,
- * and remains silent in production.
- */
-
-interface CryptoWithUUIDv7 {
-  randomUUIDv7?: () => string;
-  randomUUID: () => string;
-}
-
-interface BunWithUUIDv7 {
-  randomUUIDv7?: () => string;
-}
-
-const FALLBACK_WARNING =
-  "[@mandujs/core/id] randomUUIDv7 is unavailable — falling back to randomUUID (v4). IDs will not be time-ordered. Upgrade to Bun >= 1.3 for v7 support.";
-
-let fallbackWarned = false;
-
-function getCrypto(): CryptoWithUUIDv7 {
-  // `crypto` is available globally in Bun, Node 20+, Deno, and modern browsers.
-  // We type-assert via the narrow interface we actually use.
-  return globalThis.crypto as unknown as CryptoWithUUIDv7;
-}
-
-function getBun(): BunWithUUIDv7 | undefined {
-  // `Bun` is only present when running under the Bun runtime. Access via
-  // a dynamic lookup so the module stays importable in Node / browsers.
-  const g = globalThis as unknown as { Bun?: BunWithUUIDv7 };
-  return g.Bun;
-}
-
-function warnFallbackOnce(): void {
-  if (fallbackWarned) return;
-  fallbackWarned = true;
-  if (
-    typeof process !== "undefined" &&
-    process.env &&
-    process.env.NODE_ENV !== "production"
-  ) {
-    console.warn(FALLBACK_WARNING);
-  }
-}
-
-/**
- * Resolves the concrete UUID generator function once per call. Exported
- * internally so tests can validate the resolution order without monkey
- * patching non-configurable globals.
- *
- * @internal
- */
-export function _resolveGenerator(
-  c: CryptoWithUUIDv7 = getCrypto(),
-  bun: BunWithUUIDv7 | undefined = getBun(),
-): () => string {
-  if (typeof c.randomUUIDv7 === "function") {
-    return c.randomUUIDv7.bind(c);
-  }
-  if (bun && typeof bun.randomUUIDv7 === "function") {
-    return bun.randomUUIDv7.bind(bun);
-  }
-  warnFallbackOnce();
-  return c.randomUUID.bind(c);
-}
-
-/**
- * Generates a UUID v7 — a time-ordered UUID whose string sort matches
- * chronological order.
- *
- * Resolution order:
- *   1. `crypto.randomUUIDv7()` — web standard, Node 24+, newer Bun
- *   2. `Bun.randomUUIDv7()`    — Bun 1.3+ runtime API
- *   3. `crypto.randomUUID()`   — v4 fallback (non-monotonic)
- *
- * The fallback path emits a one-time warning in dev mode.
- *
- * @returns A 36-character UUID string in canonical 8-4-4-4-12 form.
- */
-export function newId(): string {
-  return _resolveGenerator()();
-}
-
-/**
- * First 8 hex characters of a UUID v7 — suitable for log correlation IDs
- * where collision risk is acceptable within a single request lifetime.
- *
- * Because v7 encodes the timestamp in its high bits, two short IDs generated
- * within the same millisecond share a prefix; this is normal and expected.
- * For strong uniqueness use {@link newId} instead.
- *
- * @returns Exactly 8 lowercase hex characters.
- */
-export function newShortId(): string {
-  return newId().slice(0, 8);
-}
+/**
+ * @mandujs/core/id
+ *
+ * Centralized ID generation utilities.
+ *
+ * Uses `crypto.randomUUIDv7()` when available (Bun 1.3+) so that generated IDs
+ * are time-ordered — lexicographic string sort matches chronological creation
+ * order. This makes v7 UUIDs ideal for log correlation, database primary keys,
+ * and any context where sortability is useful.
+ *
+ * On older runtimes we fall back to `crypto.randomUUID()` (v4). The fallback
+ * emits a single dev-only warning so integrators notice the reduced guarantee,
+ * and remains silent in production.
+ */
+
+interface CryptoWithUUIDv7 {
+  randomUUIDv7?: () => string;
+  randomUUID: () => string;
+}
+
+interface BunWithUUIDv7 {
+  randomUUIDv7?: () => string;
+}
+
+const FALLBACK_WARNING =
+  "[@mandujs/core/id] randomUUIDv7 is unavailable — falling back to randomUUID (v4). IDs will not be time-ordered. Upgrade to Bun >= 1.3 for v7 support.";
+
+let fallbackWarned = false;
+
+function getCrypto(): CryptoWithUUIDv7 {
+  // `crypto` is available globally in Bun, Node 20+, Deno, and modern browsers.
+  // We type-assert via the narrow interface we actually use.
+  return globalThis.crypto as unknown as CryptoWithUUIDv7;
+}
+
+function getBun(): BunWithUUIDv7 | undefined {
+  // `Bun` is only present when running under the Bun runtime. Access via
+  // a dynamic lookup so the module stays importable in Node / browsers.
+  const g = globalThis as unknown as { Bun?: BunWithUUIDv7 };
+  return g.Bun;
+}
+
+function warnFallbackOnce(): void {
+  if (fallbackWarned) return;
+  fallbackWarned = true;
+  if (
+    typeof process !== "undefined" &&
+    process.env &&
+    process.env.NODE_ENV !== "production"
+  ) {
+    console.warn(FALLBACK_WARNING);
+  }
+}
+
+/**
+ * Resolves the concrete UUID generator function once per call. Exported
+ * internally so tests can validate the resolution order without monkey
+ * patching non-configurable globals.
+ *
+ * @internal
+ */
+export function _resolveGenerator(
+  c: CryptoWithUUIDv7 = getCrypto(),
+  bun: BunWithUUIDv7 | undefined = getBun(),
+): () => string {
+  if (typeof c.randomUUIDv7 === "function") {
+    return c.randomUUIDv7.bind(c);
+  }
+  if (bun && typeof bun.randomUUIDv7 === "function") {
+    return bun.randomUUIDv7.bind(bun);
+  }
+  warnFallbackOnce();
+  return c.randomUUID.bind(c);
+}
+
+/**
+ * Generates a UUID v7 — a time-ordered UUID whose string sort matches
+ * chronological order.
+ *
+ * Resolution order:
+ *   1. `crypto.randomUUIDv7()` — web standard, Node 24+, newer Bun
+ *   2. `Bun.randomUUIDv7()`    — Bun 1.3+ runtime API
+ *   3. `crypto.randomUUID()`   — v4 fallback (non-monotonic)
+ *
+ * The fallback path emits a one-time warning in dev mode.
+ *
+ * @returns A 36-character UUID string in canonical 8-4-4-4-12 form.
+ */
+export function newId(): string {
+  return _resolveGenerator()();
+}
+
+/**
+ * First 8 hex characters of a UUID v7 — suitable for log correlation IDs
+ * where collision risk is acceptable within a single request lifetime.
+ *
+ * Because v7 encodes the timestamp in its high bits, two short IDs generated
+ * within the same millisecond share a prefix; this is normal and expected.
+ * For strong uniqueness use {@link newId} instead.
+ *
+ * @returns Exactly 8 lowercase hex characters.
+ */
+export function newShortId(): string {
+  return newId().slice(0, 8);
+}

package/src/index.ts

@@ -100,8 +100,8 @@ import { defineContract, generateAllFromContract, generateOpenAPISpec } from "./
 import { island, isIsland } from "./island";
 import { intent, isIntent } from "./intent";
 import { initializeHook, reportError, ManduDevTools, getStateManager } from "./devtools";
-
-
+
+
 
 /**
  * Mandu - Unified Namespace