@heyramzi/utils 0.0.0-stage → 1.13.0

package/src/timing.test.ts

@@ -0,0 +1,166 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vite-plus/test";
+import { debounce, throttle, sleep } from "#src/timing.ts";
+
+describe("debounce", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("does not call the function before the delay", () => {
+    const fn = vi.fn();
+    const debounced = debounce(fn, 100);
+
+    debounced();
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it("calls the function after the delay", () => {
+    const fn = vi.fn();
+    const debounced = debounce(fn, 100);
+
+    debounced();
+    vi.advanceTimersByTime(100);
+
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("only calls once when invoked multiple times within the delay", () => {
+    const fn = vi.fn();
+    const debounced = debounce(fn, 100);
+
+    debounced();
+    debounced();
+    debounced();
+    vi.advanceTimersByTime(100);
+
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("resets the timer on each call", () => {
+    const fn = vi.fn();
+    const debounced = debounce(fn, 100);
+
+    debounced();
+    vi.advanceTimersByTime(50);
+    debounced();
+    vi.advanceTimersByTime(50);
+
+    expect(fn).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(50);
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("forwards arguments to the wrapped function", () => {
+    const fn = vi.fn();
+    const debounced = debounce(fn, 100);
+
+    debounced("arg1", "arg2");
+    vi.advanceTimersByTime(100);
+
+    expect(fn).toHaveBeenCalledWith("arg1", "arg2");
+  });
+
+  it("can be called multiple times after each delay period", () => {
+    const fn = vi.fn();
+    const debounced = debounce(fn, 100);
+
+    debounced();
+    vi.advanceTimersByTime(100);
+    debounced();
+    vi.advanceTimersByTime(100);
+
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe("throttle", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("calls the function immediately on the first invocation", () => {
+    const fn = vi.fn();
+    const throttled = throttle(fn, 100);
+
+    throttled();
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not call the function again within the limit", () => {
+    const fn = vi.fn();
+    const throttled = throttle(fn, 100);
+
+    throttled();
+    throttled();
+    throttled();
+
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("allows a second call after the limit period has passed", () => {
+    const fn = vi.fn();
+    const throttled = throttle(fn, 100);
+
+    throttled();
+    vi.advanceTimersByTime(100);
+    throttled();
+
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it("forwards arguments to the wrapped function", () => {
+    const fn = vi.fn();
+    const throttled = throttle(fn, 100);
+
+    throttled("hello", 42);
+    expect(fn).toHaveBeenCalledWith("hello", 42);
+  });
+});
+
+describe("sleep", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("returns a Promise", () => {
+    const result = sleep(100);
+    expect(result).toBeInstanceOf(Promise);
+    vi.runAllTimers();
+  });
+
+  it("resolves after the given number of milliseconds", async () => {
+    let resolved = false;
+    sleep(500).then(() => {
+      resolved = true;
+    });
+
+    expect(resolved).toBe(false);
+    vi.advanceTimersByTime(499);
+    await Promise.resolve(); // flush microtasks
+    expect(resolved).toBe(false);
+
+    vi.advanceTimersByTime(1);
+    await Promise.resolve();
+    expect(resolved).toBe(true);
+  });
+
+  it("resolves with undefined", async () => {
+    const promise = sleep(10);
+    vi.advanceTimersByTime(10);
+    const result = await promise;
+    expect(result).toBeUndefined();
+  });
+});

package/src/timing.ts

@@ -0,0 +1,28 @@
+export function debounce<T extends (...args: Parameters<T>) => ReturnType<T>>(
+  fn: T,
+  delay: number,
+): (...args: Parameters<T>) => void {
+  let timeoutId: ReturnType<typeof setTimeout>;
+  return (...args: Parameters<T>) => {
+    clearTimeout(timeoutId);
+    timeoutId = setTimeout(() => fn(...args), delay);
+  };
+}
+
+export function throttle<T extends (...args: Parameters<T>) => ReturnType<T>>(
+  fn: T,
+  limit: number,
+): (...args: Parameters<T>) => void {
+  let inThrottle = false;
+  return (...args: Parameters<T>) => {
+    if (!inThrottle) {
+      fn(...args);
+      inThrottle = true;
+      setTimeout(() => (inThrottle = false), limit);
+    }
+  };
+}
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/vite.d.ts

@@ -0,0 +1,12 @@
+import type { Plugin } from "vite";
+
+export declare function packageImportsOverKitAlias(): Plugin;
+
+/**
+ * Vite plugin: before the dev server binds, kill whatever is already listening on the configured port and take the port back, instead of letting Vite drift to the next free
+ */
+
+/*
+ * port. Dev-only, macOS/Linux only, no-op on Windows or any failure.
+ */
+export declare function reclaimPort(): Plugin;

package/src/vite.js

@@ -0,0 +1,265 @@
+import { execFileSync } from "node:child_process";
+import net from "node:net";
+
+/** Let dependencies resolve their own package imports instead of Kit's app aliases. */
+export function packageImportsOverKitAlias() {
+  return {
+    name: "package-imports-over-kit-alias",
+    config(config) {
+      const alias = config.resolve?.alias;
+      if (!config.resolve || !Array.isArray(alias)) return;
+      config.resolve.alias = alias.filter(
+        (entry) => !/^\^#(src|scripts)\\?\//.test(String(entry.find).slice(1)),
+      );
+    },
+  };
+}
+
+/** Both loopback stacks: a dev server may be bound to only one of them. */
+const HOSTS = ["127.0.0.1", "::1"];
+
+/**
+ * Vite plugin: before the dev server binds, kill whatever is already listening on the configured port and take the port back.
+ */
+
+/*
+ * Without this, Vite silently increments to the next free port when the configured one is busy (e.g. a stale dev server left running),
+ */
+
+/*
+ * so you end up on 3161/3162 instead of the 3160 you asked for. This plugin reclaims the intended port instead of drifting.
+ */
+
+/*
+ * It reclaims a port from a listener that has stopped answering.
+ */
+
+/*
+ * It never takes one from a dev server that is still serving: that server belongs to somebody, and on this machine "somebody" is routinely a second agent session working in
+ */
+
+/*
+ * the same repo. A dedicated port range per project makes the owner predictable, not disposable. Pass `RECLAIM_PORT_FORCE=1` to take the port from a live server anyway.
+ */
+
+/*
+ * Reads `server.port` from the resolved config, so it works whether the port is set in `vite.config.ts` or passed as `--port` on the CLI.
+ */
+
+/*
+ * Dev-only and macOS/Linux only (uses `lsof`). On Windows or any failure it is a no-op and Vite falls back to its default behaviour.
+ */
+
+/*
+ * WHY `apply: "serve"` is not enough on its own: Vitest and `vite preview` both resolve the same config in serve mode without ever binding `server.port`,
+ */
+
+/*
+ * so either one used to reach this hook, find the running dev server on that port and SIGTERM it.
+ */
+
+/*
+ * The developer sees their dev terminal exit 143 with no explanation, which reads as the machine dying on its own.
+ */
+
+/*
+ * Anything that does not bind the port must never reclaim it.
+ */
+
+/*
+ * WHY this is plain JS (not vite.ts): vite.config.ts is read by config loaders (vp / native node strip-types) that refuse to type-strip a `.ts` file under
+ */
+
+/*
+ * node_modules. Shipping the entry as JS + a `.d.ts` lets every consumer load it from their config regardless of loader. Types live in vite.d.ts.
+ */
+
+/*
+ * Usage in vite.config.ts: import { reclaimPort } from "@heyramzi/utils/vite"; plugins: [reclaimPort(), ...]
+ */
+export function reclaimPort() {
+  // WHY a closure: `isPreview` rides on the ConfigEnv the `config` hook is
+  // handed, and never reaches the resolved config, so `configResolved` alone
+  // cannot tell `vite preview` from `vite dev`.
+  let isPreview = false;
+
+  return {
+    name: "reclaim-port",
+    apply: "serve",
+    enforce: "pre",
+    config(_userConfig, env) {
+      isPreview = Boolean(env?.isPreview);
+    },
+    async configResolved(config) {
+      if (isPreview || isNotBindingTheDevPort(config)) return;
+
+      const port = config.server.port;
+      if (!port || process.platform === "win32") return;
+
+      // WHY the self/parent filter: a `vite.config.ts` edit restarts the dev server inside the SAME process, and the old server still holds the port at that moment.
+
+      // Without this the plugin SIGTERMs its own pid and the developer's dev server dies on a config save.
+      const pids = listenerPids(port).filter((pid) => pid !== process.pid && pid !== process.ppid);
+      if (pids.length === 0) return;
+
+      // WHY liveness is tested and not assumed: this plugin was written for a stale server, and "stale" was never checked.
+
+      // It killed whatever held the port, so a second terminal, a second worktree or a second agent session running `pnpm dev` SIGTERMed a colleague's working server and that terminal died
+
+      // on `Exit status 143` with nothing to read. A port that still answers has an owner; only a port that has stopped answering is abandoned.
+      if (!isForced() && (await isServing(port))) {
+        throw new Error(
+          `[reclaim-port] Port ${port} is already serving (pid ${pids.join(", ")}).\n` +
+            `Another dev server is live on it, so this one will not take it.\n` +
+            `Use the server that is already running at http://localhost:${port},\n` +
+            `or stop it first. To take the port from a live server anyway, set ` +
+            `RECLAIM_PORT_FORCE=1.`,
+        );
+      }
+
+      config.logger.info(
+        `[reclaim-port] port ${port} held by an unresponsive listener, reclaiming (killing ${pids.join(", ")})`,
+      );
+      for (const pid of pids) {
+        try {
+          process.kill(pid, "SIGTERM");
+        } catch {
+          // already gone, or not ours to kill -- ignore and let the wait below decide
+        }
+      }
+      await waitForPortFree(port);
+    },
+  };
+}
+
+/**
+ * Whether this config is being resolved by something other than a dev server about to bind `server.port`.
+ */
+
+/*
+ * Several independent signals, because any one alone is a single point of failure: Vitest sets `VITEST` before the config loads and its resolved config carries a `test` block that a
+ */
+
+/*
+ * plain dev server never has, and `middlewareMode` marks an embedder such as Storybook or an SSR harness that never listens itself.
+ */
+
+/*
+ * `vite preview` is caught in the `config` hook above, the only place it declares itself.
+ */
+
+/*
+ * A false positive costs a port that is not reclaimed; a false negative kills the developer's session, so every doubtful case resolves to "do not touch it".
+ */
+function isNotBindingTheDevPort(config) {
+  return Boolean(
+    config.server?.middlewareMode ||
+    process.env.VITEST ||
+    process.env.VITEST_WORKER_ID ||
+    config.test,
+  );
+}
+
+/** PIDs of processes LISTENing on the port (IPv4 + IPv6), via lsof. */
+function listenerPids(port) {
+  try {
+    const out = execFileSync("lsof", ["-ti", `tcp:${port}`, "-sTCP:LISTEN"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return [
+      ...new Set(
+        out
+          .split("\n")
+          .map((line) => Number(line.trim()))
+          .filter((pid) => Number.isInteger(pid) && pid > 0),
+      ),
+    ];
+  } catch {
+    // lsof missing, or nothing listening (non-zero exit) -> nothing to reclaim
+    return [];
+  }
+}
+
+/** Resolve once the port stops accepting connections, or the timeout elapses. */
+function waitForPortFree(port, timeoutMs = 2000) {
+  const deadline = Date.now() + timeoutMs;
+  return new Promise((resolve) => {
+    const probe = () => {
+      const socket = net.connect({ port, host: "127.0.0.1" });
+      socket.once("connect", () => {
+        socket.destroy();
+        if (Date.now() > deadline) return resolve();
+        setTimeout(probe, 50);
+      });
+      socket.once("error", () => {
+        socket.destroy();
+        resolve(); // connection refused -> port is free
+      });
+    };
+    probe();
+  });
+}
+
+/** An explicit opt-in to take a port from a server that is still serving. */
+function isForced() {
+  return process.env.RECLAIM_PORT_FORCE === "1";
+}
+
+/**
+ * Whether something on this port still answers a request.
+ */
+
+/*
+ * WHY both stacks: vite binds `localhost`, which on macOS resolves to `::1` first, so a running dev server routinely appears on IPv6 ONLY.
+ */
+
+/*
+ * A probe to 127.0.0.1 is refused, the port reads as free, and the guard waves through the exact start it exists to stop.
+ */
+
+/*
+ * Verified against a live server on 3160: the IPv4-only probe returned "free" while the server was serving.
+ */
+
+/*
+ * WHY a written request and not a bare `connect`: connecting succeeds against a listener that will never reply, and telling those two apart is the whole job.
+ */
+
+/*
+ * Any byte back counts; the status line does not matter.
+ */
+function isServing(port, timeoutMs = 1000) {
+  return Promise.all(HOSTS.map((host) => answers(host, port, timeoutMs))).then((results) =>
+    results.some(Boolean),
+  );
+}
+
+function answers(host, port, timeoutMs) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (answer) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.destroy();
+      resolve(answer);
+    };
+
+    const timer = setTimeout(() => done(false), timeoutMs);
+    const socket = net.connect({ port, host });
+
+    socket.setTimeout(timeoutMs, () => done(false));
+    socket.once("error", () => done(false));
+    socket.once("data", () => done(true));
+    socket.once("close", () => done(false));
+    socket.once("connect", () => {
+      socket.write(`GET / HTTP/1.0\r\nHost: ${formatHost(host)}:${port}\r\n\r\n`);
+    });
+  });
+}
+
+/** An IPv6 literal needs brackets in a Host header. */
+function formatHost(host) {
+  return host.includes(":") ? `[${host}]` : host;
+}

package/src/vite.test.js

@@ -0,0 +1,235 @@
+// WHY `vite-plus/test` and not `vitest`: `vp test` is the runner, and the two resolve to different instances.
+
+// Imported from `vitest`, the `beforeEach` below belongs to a runner that never fires it, so `VITEST` is never cleared, the plugin returns on its own env guard,
+
+// and the three tests that assert a refusal pass through and fail.
+import { afterEach, beforeEach, describe, expect, it } from "vite-plus/test";
+import { spawn } from "node:child_process";
+import net from "node:net";
+import { reclaimPort } from "#src/vite.js";
+
+/**
+ * These tests park a REAL listener in a REAL child process and assert what the plugin does to it.
+ */
+
+/*
+ * The regression they exist for cannot be caught against a mock: the plugin's whole job is a side effect on somebody else's process,
+ */
+
+/*
+ * and it is the second session's process that keeps dying.
+ */
+
+/*
+ * WHY the listener is a child and not a server in this process: `configResolved` filters `process.pid` and `process.ppid` out of the kill list,
+ */
+
+/*
+ * so an in-process listener is spared by a rule that has nothing to do with what is under test, and every assertion would pass whatever the plugin did.
+ */
+
+/*
+ * WHY `VITEST` is cleared per test: vitest sets it, and the plugin's first guard returns early on exactly that variable.
+ */
+
+/*
+ * Left in place, every test here would exercise the guard instead of the behaviour, and pass green forever.
+ */
+
+const children = [];
+let savedEnv;
+
+beforeEach(() => {
+  savedEnv = {
+    VITEST: process.env.VITEST,
+    VITEST_WORKER_ID: process.env.VITEST_WORKER_ID,
+    RECLAIM_PORT_FORCE: process.env.RECLAIM_PORT_FORCE,
+  };
+  delete process.env.VITEST;
+  delete process.env.VITEST_WORKER_ID;
+  delete process.env.RECLAIM_PORT_FORCE;
+});
+
+afterEach(() => {
+  for (const child of children.splice(0)) {
+    if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
+  }
+  for (const [key, value] of Object.entries(savedEnv)) {
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+});
+
+/** A free port, found by binding one and letting go. */
+function freePort() {
+  return new Promise((resolve, reject) => {
+    const probe = net.createServer();
+    probe.once("error", reject);
+    probe.listen(0, "127.0.0.1", () => {
+      const { port } = probe.address();
+      probe.close(() => resolve(port));
+    });
+  });
+}
+
+/**
+ * Spawn a child holding `port`.
+ * `mode: "serving"` answers HTTP, the way a working dev server does.
+ * `mode: "mute"` accepts the socket and never writes, the way a wedged one does.
+ */
+function listener(port, mode, host = "127.0.0.1") {
+  const source =
+    mode === "serving"
+      ? `require("http").createServer((q,s)=>s.end("ok")).listen(${port},"${host}",()=>console.log("up"))`
+      : `require("net").createServer(()=>{}).listen(${port},"${host}",()=>console.log("up"))`;
+
+  const child = spawn(process.execPath, ["-e", source], { stdio: ["ignore", "pipe", "ignore"] });
+  children.push(child);
+  return new Promise((resolve, reject) => {
+    child.stdout.once("data", () => resolve(child));
+    child.once("error", reject);
+    child.once("exit", () => reject(new Error(`listener exited before binding ${port}`)));
+  });
+}
+
+/** Whether the child is still alive, after giving a signal time to land. */
+async function aliveAfterSettle(child) {
+  await new Promise((resolve) => setTimeout(resolve, 300));
+  return child.exitCode === null && child.signalCode === null;
+}
+
+function configFor(port, extra = {}) {
+  return {
+    server: { port },
+    logger: { info() {}, warn() {}, error() {} },
+    ...extra,
+  };
+}
+
+/**
+ * Both hooks, in Vite's order. `config` is where preview declares itself, so a
+ * test that calls `configResolved` alone cannot see a preview at all.
+ */
+const run = (config, env = { command: "serve" }) => {
+  const plugin = reclaimPort();
+  plugin.config({}, env);
+  return plugin.configResolved(config);
+};
+
+describe("reclaimPort", () => {
+  it("refuses to take a port from a server that is still serving", async () => {
+    const port = await freePort();
+    const child = await listener(port, "serving");
+
+    // The regression this file exists for: a second `pnpm dev`, in a second terminal or a second agent session, used to SIGTERM this server.
+
+    // The owner saw `Exit status 143` and nothing else.
+    await expect(run(configFor(port))).rejects.toThrow(/already serving/i);
+    expect(await aliveAfterSettle(child)).toBe(true);
+  });
+
+  it("leaves the port alone when Vite runs in middleware mode", async () => {
+    const port = await freePort();
+    const child = await listener(port, "serving");
+
+    // Storybook and every SSR harness resolve the config in serve mode and then
+    // never listen, so the port they name is somebody else's dev server.
+    await expect(
+      run(configFor(port, { server: { port, middlewareMode: true } })),
+    ).resolves.toBeUndefined();
+    expect(await aliveAfterSettle(child)).toBe(true);
+  });
+
+  it("names the port and the escape hatch when it refuses", async () => {
+    const port = await freePort();
+    await listener(port, "serving");
+
+    await expect(run(configFor(port))).rejects.toThrow(
+      new RegExp(`${port}[\\s\\S]*RECLAIM_PORT_FORCE`),
+    );
+  });
+
+  it("reclaims a port from a listener that has stopped answering", async () => {
+    const port = await freePort();
+    const child = await listener(port, "mute");
+
+    await expect(run(configFor(port))).resolves.toBeUndefined();
+    expect(await aliveAfterSettle(child)).toBe(false);
+  });
+
+  it("takes the port from a live server only when explicitly forced", async () => {
+    const port = await freePort();
+    const child = await listener(port, "serving");
+    process.env.RECLAIM_PORT_FORCE = "1";
+
+    await expect(run(configFor(port))).resolves.toBeUndefined();
+    expect(await aliveAfterSettle(child)).toBe(false);
+  });
+
+  it("refuses when the live server is bound to IPv6 only", async () => {
+    const port = await freePort();
+    const child = await listener(port, "serving", "::1");
+
+    // vite binds `localhost`, which resolves to ::1 first on macOS, so a real dev server routinely listens on IPv6 ONLY.
+
+    // An IPv4-only probe reported that port free and waved through the start it exists to stop. Caught against the live server on 3160, not in review.
+    await expect(run(configFor(port))).rejects.toThrow(/already serving/i);
+    expect(await aliveAfterSettle(child)).toBe(true);
+  });
+
+  it("does nothing when the port is free", async () => {
+    const port = await freePort();
+    await expect(run(configFor(port))).resolves.toBeUndefined();
+  });
+
+  it("leaves a live server alone when vitest is resolving the config", async () => {
+    const port = await freePort();
+    const child = await listener(port, "serving");
+    process.env.VITEST = "true";
+
+    await expect(run(configFor(port))).resolves.toBeUndefined();
+    expect(await aliveAfterSettle(child)).toBe(true);
+  });
+
+  it("leaves a mute listener alone when vitest is resolving the config", async () => {
+    const port = await freePort();
+    const child = await listener(port, "mute");
+    process.env.VITEST = "true";
+
+    // The 17 Aug 2026 incident in the other direction: a test run must not
+    // reclaim, whether or not the holder answers.
+    await expect(run(configFor(port))).resolves.toBeUndefined();
+    expect(await aliveAfterSettle(child)).toBe(true);
+  });
+
+  it("leaves a mute listener alone in preview mode", async () => {
+    const port = await freePort();
+    const child = await listener(port, "mute");
+
+    await expect(
+      run(configFor(port), { command: "serve", isPreview: true }),
+    ).resolves.toBeUndefined();
+    expect(await aliveAfterSettle(child)).toBe(true);
+  });
+
+  it("leaves a live server alone in preview mode", async () => {
+    const port = await freePort();
+    const child = await listener(port, "serving");
+
+    // `pnpm gate` runs the e2e walk against `vite preview` while the dev server is up.
+
+    // Preview read `server.port`, found it live and SIGTERMed it: the dev terminal died on exit 143 on every gate run (cbam, 15 Sep 2026).
+    await expect(
+      run(configFor(port), { command: "serve", isPreview: true }),
+    ).resolves.toBeUndefined();
+    expect(await aliveAfterSettle(child)).toBe(true);
+  });
+
+  it("leaves a mute listener alone when a test block is present", async () => {
+    const port = await freePort();
+    const child = await listener(port, "mute");
+
+    await expect(run(configFor(port, { test: {} }))).resolves.toBeUndefined();
+    expect(await aliveAfterSettle(child)).toBe(true);
+  });
+});