veryfront 0.1.324 → 0.1.327

package/src/src/testing/deno-compat.ts

@@ -0,0 +1,206 @@
+/**
+ * Deno API compatibility shims for cross-runtime testing.
+ *
+ * Provides portable implementations of common Deno testing APIs:
+ * - Deno.makeTempDir() → makeTempDir()
+ * - Deno.makeTempFile() → makeTempFile()
+ * - Deno.writeTextFile() → writeTextFile()
+ * - Deno.readTextFile() → readTextFile()
+ * - Deno.remove() → remove()
+ * - Deno.mkdir() → mkdir()
+ * - Deno.stat() → stat()
+ * - Deno.env.get/set/delete → getEnv/setEnv/deleteEnv
+ *
+ * @module
+ */
+import * as dntShim from "../../_dnt.shims.js";
+
+
+import { isDeno } from "../platform/compat/runtime.js";
+import { scaleMs } from "./timing.js";
+import { TIMEOUT_ERROR } from "../errors/index.js";
+
+export {
+  chmod,
+  createFileSystem,
+  exists,
+  isAlreadyExistsError,
+  isNotFoundError,
+  makeTempDir,
+  mkdir,
+  readDir,
+  readFile,
+  readTextFile,
+  remove,
+  stat,
+  writeFile,
+  writeTextFile,
+} from "../platform/compat/fs.js";
+
+export {
+  cwd,
+  deleteEnv,
+  env,
+  getArgs,
+  getEnv,
+  setEnv,
+} from "../platform/compat/process.js";
+
+export async function makeTempFile(
+  options?: { prefix?: string; suffix?: string },
+): Promise<string> {
+  if (isDeno) {
+    // @ts-ignore - Deno global
+    return await dntShim.Deno.makeTempFile(options);
+  }
+
+  const [{ default: os }, { default: fs }, { default: path }] = await Promise.all([
+    import("node:os"),
+    import("node:fs/promises"),
+    import("node:path"),
+  ]);
+
+  const prefix = options?.prefix ?? "tmp-";
+  const suffix = options?.suffix ?? "";
+  const randomPart = Math.random().toString(36).substring(2, 10);
+  const filename = `${prefix}${randomPart}${suffix}`;
+  const tempPath = path.join(os.tmpdir(), filename);
+
+  await fs.writeFile(tempPath, "");
+  return tempPath;
+}
+
+export async function makeTempDirWithOptions(options?: {
+  prefix?: string;
+  dir?: string;
+}): Promise<string> {
+  if (isDeno) {
+    // @ts-ignore - Deno global
+    return await dntShim.Deno.makeTempDir(options);
+  }
+
+  const [{ default: os }, { default: fs }, { default: path }] = await Promise.all([
+    import("node:os"),
+    import("node:fs/promises"),
+    import("node:path"),
+  ]);
+
+  const baseDir = options?.dir ?? os.tmpdir();
+  const prefix = options?.prefix ?? "tmp-";
+  const randomPart = Math.random().toString(36).substring(2, 10);
+  const dirname = `${prefix}${randomPart}`;
+  const tempPath = path.join(baseDir, dirname);
+
+  await fs.mkdir(tempPath, { recursive: true });
+  return tempPath;
+}
+
+export async function waitFor(
+  condition: () => boolean | Promise<boolean>,
+  options?: {
+    timeout?: number;
+    interval?: number;
+    message?: string;
+  },
+): Promise<void> {
+  const timeout = scaleMs(options?.timeout ?? 5000, 10);
+  const interval = scaleMs(options?.interval ?? 100, 5);
+  const message = options?.message ?? "Condition not met within timeout";
+  const start = Date.now();
+
+  while (Date.now() - start < timeout) {
+    if (await condition()) return;
+    // no cleanup needed: one-shot
+    await new Promise<void>((resolve) => dntShim.setTimeout(resolve, interval));
+  }
+
+  throw TIMEOUT_ERROR.create({ detail: `${message} (timeout: ${timeout}ms)` });
+}
+
+// no cleanup needed: one-shot
+export function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => dntShim.setTimeout(resolve, scaleMs(ms)));
+}
+
+export function exit(code: number): never {
+  if (isDeno) {
+    // @ts-ignore - Deno global
+    dntShim.Deno.exit(code);
+  }
+
+  process.exit(code);
+}
+
+export async function withTempDir<T>(
+  fn: (tempDir: string) => Promise<T>,
+  options?: { prefix?: string },
+): Promise<T> {
+  const tempDir = await makeTempDirWithOptions({ prefix: options?.prefix ?? "test-" });
+
+  try {
+    return await fn(tempDir);
+  } finally {
+    try {
+      if (isDeno) {
+        // @ts-ignore - Deno global
+        await dntShim.Deno.remove(tempDir, { recursive: true });
+      } else {
+        const { default: fs } = await import("node:fs/promises");
+        await fs.rm(tempDir, { recursive: true, force: true });
+      }
+    } catch (_) {
+      /* expected: temp dir may already be removed or inaccessible */
+    }
+  }
+}
+
+export async function withTempFile<T>(
+  fn: (tempFile: string) => Promise<T>,
+  options?: { prefix?: string; suffix?: string },
+): Promise<T> {
+  const tempFile = await makeTempFile({ prefix: options?.prefix, suffix: options?.suffix });
+
+  try {
+    return await fn(tempFile);
+  } finally {
+    try {
+      if (isDeno) {
+        // @ts-ignore - Deno global
+        await dntShim.Deno.remove(tempFile);
+      } else {
+        const { default: fs } = await import("node:fs/promises");
+        await fs.rm(tempFile, { force: true });
+      }
+    } catch (_) {
+      /* expected: temp file may already be removed or inaccessible */
+    }
+  }
+}
+
+export async function withEnv<T>(
+  vars: Record<string, string>,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const { getEnv, setEnv, deleteEnv } = await import("../platform/compat/process.js");
+
+  const original: Record<string, string | undefined> = {};
+  for (const key of Object.keys(vars)) {
+    original[key] = getEnv(key);
+  }
+
+  for (const [key, value] of Object.entries(vars)) {
+    setEnv(key, value);
+  }
+
+  try {
+    return await fn();
+  } finally {
+    for (const [key, value] of Object.entries(original)) {
+      if (value === undefined) {
+        deleteEnv(key);
+      } else {
+        setEnv(key, value);
+      }
+    }
+  }
+}

package/src/src/testing/index.ts

@@ -0,0 +1,92 @@
+/**
+ * Cross-runtime test utilities — BDD framework (describe/it), assertions,
+ * test isolation, filesystem/env helpers, and timing utilities for Deno, Node, and Bun.
+ *
+ * @example
+ * ```ts
+ * import { assertEquals, describe, it } from "veryfront/testing";
+ *
+ * describe("math", () => {
+ *   it("adds numbers", () => {
+ *     assertEquals(1 + 1, 2);
+ *   });
+ * });
+ * ```
+ *
+ * @module testing
+ */
+
+// Initialize test environment before any other imports
+import "../../_dnt.polyfills.js";
+
+import "./init.js";
+
+export {
+  assert,
+  assertEquals,
+  assertExists,
+  assertGreater,
+  assertGreaterOrEqual,
+  assertInstanceOf,
+  assertLess,
+  assertLessOrEqual,
+  assertMatch,
+  assertNotEquals,
+  assertNotStrictEquals,
+  assertObjectMatch,
+  assertRejects,
+  assertStrictEquals,
+  assertStringIncludes,
+  assertThrows,
+  fail,
+} from "./assert.js";
+
+export { deepEquals, safeStringify } from "./utils.js";
+
+export {
+  afterAll,
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  it,
+  test,
+} from "./bdd.js";
+export type { BddTestContext, TestOptions } from "./bdd.js";
+
+export { registerTestCleanup, resetAllTestState } from "./isolation.js";
+
+export {
+  chmod,
+  createFileSystem,
+  cwd,
+  delay,
+  deleteEnv,
+  env,
+  exists,
+  exit,
+  getArgs,
+  getEnv,
+  isAlreadyExistsError,
+  isNotFoundError,
+  makeTempDir,
+  makeTempDirWithOptions,
+  makeTempFile,
+  mkdir,
+  readDir,
+  readFile,
+  readTextFile,
+  remove,
+  setEnv,
+  stat,
+  waitFor,
+  withEnv,
+  withTempDir,
+  withTempFile,
+  writeFile,
+  writeTextFile,
+} from "./deno-compat.js";
+
+export { getTestTimeScale, scaleMs, testDelay } from "./timing.js";
+
+export { isBun, isDeno, isNode } from "../platform/compat/runtime.js";

package/src/src/testing/init.ts

@@ -0,0 +1,21 @@
+/**
+ * Test environment initialization.
+ *
+ * This module sets up the testing environment by disabling features
+ * that can cause resource leaks in tests, like LRU cache cleanup intervals.
+ *
+ * IMPORTANT: Import this module before any other veryfront imports in test files
+ * to ensure the flags are set before module-level caches are initialized.
+ *
+ * @module
+ */
+import * as dntShim from "../../_dnt.shims.js";
+
+
+const g = dntShim.dntGlobalThis as Record<string, unknown>;
+
+g.__vfDisableLruInterval = true;
+g.__vfTestEnv = true;
+g.__vfTestEnvMask = {
+  prefixes: ["VERYFRONT_", "OTEL_", "OAUTH_", "GITHUB_", "OPENAI_", "ANTHROPIC_", "GOOGLE_"],
+};

package/src/src/testing/isolation.ts

@@ -0,0 +1,177 @@
+/**
+ * Test isolation utilities for cross-runtime execution.
+ *
+ * Provides default cleanup hooks to reduce cross-test leakage,
+ * especially in Bun where module caching and shared globals
+ * can cause flakiness.
+ *
+ * @module
+ */
+
+import { isBun } from "../platform/compat/runtime.js";
+
+type CleanupTask = () => void | Promise<void>;
+type LabeledCleanupTask = {
+  label: string;
+  task: CleanupTask;
+};
+
+const cleanupTasks = new Set<CleanupTask>();
+
+export function registerTestCleanup(task: CleanupTask): void {
+  cleanupTasks.add(task);
+}
+
+async function runBestEffortCleanups(cleanups: Iterable<LabeledCleanupTask>): Promise<void> {
+  for (const { label, task } of cleanups) {
+    try {
+      await task();
+    } catch (error) {
+      console.debug(`resetAllTestState ${label} failed`, error);
+    }
+  }
+}
+
+async function runRegisteredCleanups(): Promise<void> {
+  const tasks = Array.from(cleanupTasks);
+  cleanupTasks.clear();
+
+  await runBestEffortCleanups(
+    tasks.map((task) => ({
+      label: "registered cleanup",
+      task,
+    })),
+  );
+}
+
+/**
+ * Comprehensive reset of ALL test state across the application.
+ *
+ * This function clears all known caches and singletons that can cause
+ * test isolation issues when running tests in parallel. It should be
+ * called at the start and end of each test to ensure clean state.
+ *
+ * Includes:
+ * - Config state (_environmentConfig, runtimeConfig, configCache)
+ * - Layout discovery cache
+ * - SSR module caches
+ * - React cache and compat hooks
+ * - Snippet cache
+ * - API handler state
+ * - Reload notifier
+ */
+export async function resetAllTestState(): Promise<void> {
+  await runRegisteredCleanups();
+
+  const cleanupSteps: LabeledCleanupTask[] = [
+    // Config state - CRITICAL for test isolation
+    {
+      label: "config cache cleanup",
+      task: async () => {
+        const { clearConfigCache } = await import("../config/loader.js");
+        clearConfigCache();
+      },
+    },
+    {
+      label: "environment config cleanup",
+      task: async () => {
+        const { _resetEnvironmentConfig } = await import("../config/environment-config.js");
+        _resetEnvironmentConfig();
+      },
+    },
+    {
+      label: "runtime config cleanup",
+      task: async () => {
+        const { _resetRuntimeConfig } = await import("../config/runtime-config.js");
+        _resetRuntimeConfig();
+      },
+    },
+
+    // Layout discovery cache - prevents stale layouts across tests
+    {
+      label: "layout discovery cleanup",
+      task: async () => {
+        const { clearLayoutDiscoveryCache } = await import(
+          "../rendering/layouts/utils/discovery.js"
+        );
+        clearLayoutDiscoveryCache();
+      },
+    },
+
+    // SSR module caches
+    {
+      label: "SSR module cache cleanup",
+      task: async () => {
+        const { clearSSRModuleCache } = await import("../modules/index.js");
+        clearSSRModuleCache();
+      },
+    },
+
+    // React cache and compat hooks
+    {
+      label: "React cache cleanup",
+      task: async () => {
+        const { resetReactCache } = await import("../react/compat/ssr-adapter/server-loader.js");
+        resetReactCache();
+      },
+    },
+    {
+      label: "compat hooks cleanup",
+      task: async () => {
+        const { resetCompatHooksContext } = await import("../react/compat/hooks-adapter.js");
+        resetCompatHooksContext();
+      },
+    },
+
+    // Snippet cache
+    {
+      label: "snippet cache cleanup",
+      task: async () => {
+        const { clearSnippetCache } = await import("../rendering/snippet-renderer.js");
+        clearSnippetCache();
+      },
+    },
+
+    // API handler state
+    {
+      label: "API handler cleanup",
+      task: async () => {
+        const { resetApiHandler } = await import("../server/handlers/request/api/index.js");
+        await resetApiHandler();
+      },
+    },
+
+    // Reload notifier
+    {
+      label: "reload notifier cleanup",
+      task: async () => {
+        const { ReloadNotifier } = await import("../server/reload-notifier.js");
+        ReloadNotifier.reset();
+      },
+    },
+
+    // HTTP module in-flight fetches - prevents test interference from shared promises
+    {
+      label: "HTTP in-flight fetch cleanup",
+      task: async () => {
+        const { __clearInFlightHttpFetches } = await import("../transforms/esm/http-cache.js");
+        __clearInFlightHttpFetches();
+      },
+    },
+  ];
+
+  await runBestEffortCleanups(cleanupSteps);
+
+  // Bun-specific cleanup
+  if (isBun) {
+    await runBestEffortCleanups([
+      {
+        label: "bundler cleanup",
+        task: async () => {
+          const { cleanupBundler } = await import("../rendering/cleanup.js");
+          await cleanupBundler();
+        },
+      },
+    ]);
+  }
+}

package/src/src/testing/timing.ts

@@ -0,0 +1,27 @@
+import * as dntShim from "../../_dnt.shims.js";
+import { getEnv } from "../platform/compat/process.js";
+
+const DEFAULT_SCALE = 1;
+
+function readScale(): number {
+  const raw = getEnv("VF_TEST_TIME_SCALE");
+  if (!raw) return DEFAULT_SCALE;
+
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_SCALE;
+
+  return parsed;
+}
+
+export function getTestTimeScale(): number {
+  return readScale();
+}
+
+export function scaleMs(ms: number, minMs = 1): number {
+  return Math.max(minMs, Math.round(ms * readScale()));
+}
+
+// no cleanup needed: one-shot
+export function testDelay(ms: number): Promise<void> {
+  return new Promise((resolve) => dntShim.setTimeout(resolve, scaleMs(ms)));
+}

package/src/src/testing/utils.ts

@@ -0,0 +1,44 @@
+/***********************
+ * Shared utility functions for cross-runtime testing.
+ ***********************/
+
+export function deepEquals(a: unknown, b: unknown, seen: WeakSet<object> = new WeakSet()): boolean {
+  if (a === b) return true;
+  if (a === null || b === null) return a === b;
+  if (typeof a !== typeof b) return false;
+  if (typeof a !== "object") return a === b;
+
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b)) return false;
+    if (a.length !== b.length) return false;
+    return a.every((val, i) => deepEquals(val, b[i], seen));
+  }
+
+  const aObj = a as object;
+  const bObj = b as object;
+
+  if (seen.has(aObj)) return true;
+  seen.add(aObj);
+
+  const aKeys = Object.keys(aObj);
+  const bKeys = Object.keys(bObj);
+  if (aKeys.length !== bKeys.length) return false;
+
+  const aRec = a as Record<string, unknown>;
+  const bRec = b as Record<string, unknown>;
+
+  return aKeys.every((key) => deepEquals(aRec[key], bRec[key], seen));
+}
+
+export function safeStringify(value: unknown): string {
+  try {
+    return JSON.stringify(value);
+  } catch (_) {
+    /* expected: value may contain circular references or non-serializable types */
+    if (value === null) return "null";
+    if (value === undefined) return "undefined";
+    if (typeof value === "function") return "[Function]";
+    if (typeof value === "object") return `[${(value as object).constructor?.name ?? "Object"}]`;
+    return String(value);
+  }
+}

package/src/src/types/global-guards.ts

@@ -0,0 +1,21 @@
+export type { GlobalWithBun, GlobalWithDeno, GlobalWithProcess } from "../utils/index.js";
+export { hasBunRuntime, hasDenoRuntime, hasNodeProcess } from "../utils/index.js";
+
+export interface GlobalWithReactDOM {
+  ReactDOM?: typeof import("../../deps/esm.sh/react-dom@19.2.4/client.js");
+}
+
+export interface GlobalWithVeryFrontCache {
+  __VF_CACHE_NAMESPACE__?: string;
+}
+
+export function hasReactDOM(global: unknown): global is GlobalWithReactDOM {
+  if (typeof global !== "object" || global === null) return false;
+  return "ReactDOM" in global &&
+    typeof (global as Record<string, unknown>)["ReactDOM"] !== "undefined";
+}
+
+export function hasVeryFrontCache(global: unknown): global is GlobalWithVeryFrontCache {
+  if (typeof global !== "object" || global === null) return false;
+  return "__VF_CACHE_NAMESPACE__" in global;
+}

package/src/src/utils/cache/keys/namespace.ts

@@ -0,0 +1,25 @@
+import * as dntShim from "../../../../_dnt.shims.js";
+import { getEnv } from "../../../platform/compat/process.js";
+import { serverLogger } from "../../logger/logger.js";
+import type { GlobalWithVeryFrontCache } from "../../../types/global-guards.js";
+
+const logger = serverLogger.component("cache");
+
+const globalCache = dntShim.dntGlobalThis as GlobalWithVeryFrontCache;
+
+let cacheNamespace: string | undefined = globalCache.__VF_CACHE_NAMESPACE__ ??
+  getEnv("VF_CACHE_NAMESPACE");
+
+export function setCacheNamespace(namespace?: string): void {
+  cacheNamespace = namespace ?? undefined;
+
+  try {
+    globalCache.__VF_CACHE_NAMESPACE__ = cacheNamespace;
+  } catch (e) {
+    logger.debug("setCacheNamespace failed", e);
+  }
+}
+
+export function getCacheNamespace(): string | undefined {
+  return cacheNamespace;
+}

package/src/src/utils/clsx.ts

@@ -2,8 +2,8 @@
  * Inline implementation of the `clsx` class-name joining utility.
  *
  * API-compatible with the MIT-licensed `clsx` npm package — this is a
- * clean-room rewrite against the public API (named `clsx` export, `ClassValue`
- * type, default export alias); no source was copied.
+ * clean-room rewrite against the public API surface veryfront uses (named
+ * `clsx` export and `ClassValue` type); no source was copied.
  *
  * Replaces the `clsx` npm dep per spec §8.3 (inline micro-utilities in core).
  */
@@ -36,5 +36,3 @@ export function clsx(...args: Value[]): string {
   }
   return out.join(" ");
 }
-
-export default clsx;

package/src/src/utils/mime-types.ts

@@ -151,5 +151,3 @@ export function charset(mime: string): string | false {
 export function extension(mime: string): string | false {
   return Object.hasOwn(EXT_BY_MIME, mime) ? EXT_BY_MIME[mime]! : false;
 }
-
-export default { lookup, charset, extension };

package/src/src/utils/version-constant.ts

@@ -1,3 +1,3 @@
 // Keep in sync with deno.json version.
 // scripts/release.ts updates this constant during releases.
-export const VERSION = "0.1.324";
+export const VERSION = "0.1.327";