@excom/kit-utils 0.1.0

package/queue-manager.ts

@@ -0,0 +1,214 @@
+import { toArray } from "./common";
+
+type QueueName = string;
+type QueueStatus =
+  | "pending"
+  | "settling"
+  | "canceled"
+  | "resolved"
+  | "rejected";
+type State = { status: QueueStatus; value?: any };
+type Config = {
+  name?: QueueName;
+  initialValue?: any;
+};
+type QueueCallback = (state: State, config: Config) => any;
+type OneOrManyCbs = QueueCallback | QueueCallback[];
+
+export class Queue {
+  config: Config;
+  state: State;
+  callbacks: {
+    [key in QueueStatus]: Array<QueueCallback>;
+  } = {
+    pending: [],
+    settling: [],
+    canceled: [],
+    resolved: [],
+    rejected: [],
+  };
+  waitingStates = ["pending", "settling"];
+  finishedStates = ["resolved", "rejected", "canceled"];
+
+  constructor(opts?: Config) {
+    this.init(opts);
+  }
+  private init(opts: Config = {}) {
+    this.config = {
+      name: opts?.name,
+      initialValue: opts?.initialValue,
+    };
+    // drop stale state so a finished queue cannot leak
+    // @ts-expect-error - these are set in the subsequent call to _changeState
+    this.state = undefined;
+    return this._changeState({ status: "pending", value: opts?.initialValue });
+  }
+
+  onPending(cbs: OneOrManyCbs) {
+    return this._on("pending", cbs);
+  }
+  offPending(cbs: OneOrManyCbs) {
+    return this._off("pending", cbs);
+  }
+  oncePending(cbs: OneOrManyCbs) {
+    return this._once("pending", cbs);
+  }
+  reset(opts: Config = this.config) {
+    this.cancel();
+    this.init(opts);
+    return this;
+  }
+  onResolved(cbs: OneOrManyCbs) {
+    return this._on("resolved", cbs);
+  }
+  offResolved(cbs: OneOrManyCbs) {
+    return this._off("resolved", cbs);
+  }
+  onceResolved(cbs: OneOrManyCbs) {
+    return this._once("resolved", cbs);
+  }
+  resolve(value?: any) {
+    return this._changeState({ status: "resolved", value });
+  }
+  onRejected(cbs: OneOrManyCbs) {
+    return this._on("rejected", cbs);
+  }
+  offRejected(cbs: OneOrManyCbs) {
+    return this._off("rejected", cbs);
+  }
+  onceRejected(cbs: OneOrManyCbs) {
+    return this._once("rejected", cbs);
+  }
+  reject(value?: any) {
+    return this._changeState({ status: "rejected", value });
+  }
+  onCanceled(cbs: OneOrManyCbs) {
+    return this._on("canceled", cbs);
+  }
+  offCanceled(cbs: OneOrManyCbs) {
+    return this._off("canceled", cbs);
+  }
+  onceCanceled(cbs: OneOrManyCbs) {
+    return this._once("canceled", cbs);
+  }
+  cancel(value?: any) {
+    return this._changeState({ status: "canceled", value });
+  }
+  onSettling(cbs: OneOrManyCbs) {
+    return this._on("settling", cbs);
+  }
+  offSettling(cbs: OneOrManyCbs) {
+    return this._off("settling", cbs);
+  }
+  onceSettling(cbs: OneOrManyCbs) {
+    return this._once("settling", cbs);
+  }
+  settle(syncOrAsyncValue?: any) {
+    if (syncOrAsyncValue instanceof Promise) {
+      this._changeState({ status: "settling", value: syncOrAsyncValue });
+      syncOrAsyncValue
+        .then(
+          (v) =>
+            // still this promise, and the queue has not finished
+            this.state.value === syncOrAsyncValue &&
+            !this.isFinished(this?.state?.status) &&
+            this._changeState({ status: "resolved", value: v })
+        )
+        .catch(
+          (v) =>
+            // still this promise, and the queue has not finished
+            this.state.value === syncOrAsyncValue &&
+            !this.isFinished(this?.state?.status) &&
+            this._changeState({ status: "rejected", value: v })
+        );
+      return this;
+    } else if (!this.isFinished(this?.state?.status)) {
+      return this._changeState({ status: "resolved", value: syncOrAsyncValue });
+    } else {
+      return this;
+    }
+  }
+  private _on(status: QueueStatus, _cbs: OneOrManyCbs) {
+    const callbacks = toArray(_cbs);
+    callbacks.forEach((cb) => {
+      if (!this.callbacks[status].includes(cb)) {
+        this.callbacks[status].push(cb);
+      }
+      if (this.state.status === status) {
+        cb(this.state, this.config);
+      }
+    });
+    return this;
+  }
+  private _off(status: QueueStatus, _cbs: OneOrManyCbs) {
+    const callbacks = toArray(_cbs);
+    this.callbacks[status] = this.callbacks[status].filter(
+      (cb) => !callbacks.includes(cb)
+    );
+    return this;
+  }
+  private _once(status: QueueStatus, _cbs: OneOrManyCbs) {
+    const callbacks = toArray(_cbs);
+    const onceCb = () => {
+      callbacks.forEach((cb) => cb(this.state, this.config));
+      this._off(status, onceCb);
+    };
+    return this._on(status, onceCb);
+  }
+  private _changeState({
+    status,
+    value,
+  }: {
+    status: QueueStatus;
+    value?: any;
+  }) {
+    if (this.isFinished(this?.state?.status) && status === "settling") {
+      // finished queues do not re-enter settling
+      return this;
+    }
+    if (this.isWaiting(status) || this.isWaiting(this?.state?.status)) {
+      this.state = {
+        value,
+        status,
+      };
+      // snapshot: a callback may `.offResolved` (etc.) mid-loop
+      [...this.callbacks[status]].forEach((cb) => cb(this.state, this.config));
+    }
+    return this;
+  }
+
+  private isFinished(status: QueueStatus) {
+    return this.finishedStates.includes(status);
+  }
+
+  private isWaiting(status: QueueStatus) {
+    return this.waitingStates.includes(status);
+  }
+}
+/*
+ * Callbacks run synchronously: on enqueue if the queue is already
+ * resolved, or in the same turn it resolves. No microtask hop (unlike
+ * Promise). Also supports cancel.
+ */
+export class QueueManager {
+  queues: Record<QueueName, Queue> = {};
+  createQueue(queueName: QueueName, initialConf: Config = {}) {
+    if (this.queues[queueName]) {
+      this.queues[queueName].cancel();
+    }
+    this.queues[queueName] = new Queue({ name: queueName, ...initialConf });
+    return this.queues[queueName];
+  }
+  deleteQueue(queueName: QueueName) {
+    if (this.queues[queueName]) {
+      this.queues[queueName].cancel();
+      delete this.queues[queueName];
+      return true;
+    } else {
+      return false;
+    }
+  }
+  getQueue(queueName: QueueName, initialConf?: Config) {
+    return this.queues[queueName] || this.createQueue(queueName, initialConf);
+  }
+}

package/rush-logs/kit-utils.apply-exports.cache.log

@@ -0,0 +1 @@
+Caching has been disabled for this project's "apply-exports" command.

package/rush-logs/kit-utils.apply-exports.log

@@ -0,0 +1 @@
+Invoking: cd "$RUSH_PROJECT_FOLDER" && node ../heft-rig/scripts/apply-exports.mjs 

package/support/tests/batch-manager.test.ts

@@ -0,0 +1,381 @@
+import { BatchManager, ExecHandlerFn } from "../../batch-manager";
+import { LoopGuard, type LoopGuardTrip } from "../../loop-guard";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from "@excom/heft-rig/node_modules/vitest";
+
+const execHandler: ExecHandlerFn = ([deps, fn], notifs) =>
+  fn(deps.map((dep) => notifs[dep]));
+
+const doBatch = (batchManager: BatchManager, cb: () => void) => {
+  const doLock = !batchManager.isLocked;
+  if (doLock) batchManager.lock();
+  cb();
+  if (doLock) batchManager.unlock();
+};
+
+describe("BatchManager", () => {
+  it("should create a batchManager", () => {
+    const batchManager = new BatchManager({ handlers: [] });
+    expect(batchManager).toBeInstanceOf(BatchManager);
+  });
+
+  it("should add an handler", () => {
+    const handlers = [[["foo-0"], vi.fn()]] as const;
+    const batchManager = new BatchManager({ handlers, execHandler });
+    expect(batchManager.handlers).toEqual(handlers);
+  });
+
+  it("should call handlers if not locked", () => {
+    const handlers = [[["foo-0"], vi.fn()]] as const;
+    const batchManager = new BatchManager({ handlers, execHandler });
+    batchManager.notify("foo-0", "notified value");
+    expect(handlers[0][1]).toHaveBeenCalledWith(["notified value"]);
+  });
+
+  it("should flush handlers when unlocked", () => {
+    const handlers = [[["foo-0"], vi.fn()]] as const;
+    const batchManager = new BatchManager({ handlers, execHandler });
+    doBatch(batchManager, () => {
+      batchManager.notify("foo-0", "notified value");
+      expect(handlers[0][1]).not.toHaveBeenCalled();
+    });
+    expect(handlers[0][1]).toHaveBeenCalledWith(["notified value"]);
+  });
+
+  it("should call handlers sequentially when notify happens during flush", () => {
+    let batchManager;
+    const handlers = [
+      [["foo-0"], vi.fn()],
+      [
+        ["bar-1"],
+        vi.fn(() => {
+          batchManager.notify("foo-0", "notified value");
+          batchManager.notify("baz-2", "third value");
+        }),
+      ],
+      [["baz-2"], vi.fn()],
+    ] as const;
+    batchManager = new BatchManager({ handlers, execHandler });
+    doBatch(batchManager, () => {
+      batchManager.notify("foo-0", "notified value");
+      batchManager.notify("bar-1", "second value");
+    });
+    expect(handlers[0][1]).toHaveBeenCalledWith(["notified value"]);
+    expect(handlers[1][1]).toHaveBeenCalledWith(["second value"]);
+    expect(handlers[2][1]).toHaveBeenCalledWith(["third value"]);
+    expect(handlers[0][1]).toHaveBeenCalledTimes(2);
+    expect(handlers[1][1]).toHaveBeenCalledTimes(1);
+    expect(handlers[2][1]).toHaveBeenCalledTimes(1);
+  });
+
+  it("should call handlers with latest value", () => {
+    const handlers = [[["foo-0"], vi.fn()]] as const;
+    const batchManager = new BatchManager({ handlers, execHandler });
+    doBatch(batchManager, () => {
+      batchManager.notify("foo-0", "notified value");
+      batchManager.notify("foo-0", "another notified value");
+    });
+    expect(handlers[0][1]).toHaveBeenCalledWith(["another notified value"]);
+    expect(handlers[0][1]).toHaveBeenCalledTimes(1);
+  });
+
+  it("should call handlers with latest value, only once if not processed yet, handler called with object", () => {
+    let batchManager;
+    const handlers = [
+      [
+        ["apiUrl"],
+        vi.fn(() => {
+          doBatch(batchManager, () => {
+            batchManager.notify("payloadValue", "another value");
+            batchManager.notify("emit", "not value");
+          });
+        }),
+      ],
+      [
+        ["apiUrl"],
+        vi.fn(() => {
+          batchManager.notify("payloadValue", "another real value");
+        }),
+      ],
+      [
+        ["payloadValue"],
+        vi.fn((val) => {
+          batchManager.notify(
+            "emit",
+            val["payloadValue"] === "another real value"
+              ? "real value"
+              : "broken"
+          );
+        }),
+      ],
+      [["emit"], vi.fn()],
+    ] as const;
+    batchManager = new BatchManager({ handlers });
+    doBatch(batchManager, () => {
+      batchManager.notify("apiUrl", "a value");
+    });
+    expect(handlers[0][1]).toHaveBeenCalledWith(
+      expect.objectContaining({
+        apiUrl: "a value",
+      })
+    );
+    expect(handlers[1][1]).toHaveBeenCalledWith(
+      expect.objectContaining({
+        apiUrl: "a value",
+      })
+    );
+    expect(handlers[2][1]).toHaveBeenCalledWith(
+      expect.objectContaining({
+        payloadValue: "another real value",
+      })
+    );
+    expect(handlers[3][1]).toHaveBeenCalledWith(
+      expect.objectContaining({
+        emit: "real value",
+      })
+    );
+    expect(handlers[0][1]).toHaveBeenCalledTimes(1);
+    expect(handlers[1][1]).toHaveBeenCalledTimes(1);
+    expect(handlers[2][1]).toHaveBeenCalledTimes(1);
+  });
+
+  it("multiple dependencies: runs handlers correctly", () => {
+    const handlers = [
+      [["foo-0", "bar-1"], vi.fn()],
+      [["bar-1", "baz-2"], vi.fn()],
+      [["baz-2"], vi.fn()],
+    ] as const;
+    const batchManager = new BatchManager({ handlers, execHandler });
+    doBatch(batchManager, () => {
+      batchManager.notify("foo-0", "a value");
+      batchManager.notify("bar-1", "another value");
+      batchManager.notify("baz-2", "real value");
+    });
+    expect(handlers[0][1]).toHaveBeenCalledWith(["a value", "another value"]);
+    expect(handlers[1][1]).toHaveBeenCalledWith([
+      "another value",
+      "real value",
+    ]);
+    expect(handlers[2][1]).toHaveBeenCalledWith(["real value"]);
+    expect(handlers[0][1]).toHaveBeenCalledTimes(1);
+    expect(handlers[1][1]).toHaveBeenCalledTimes(1);
+    expect(handlers[2][1]).toHaveBeenCalledTimes(1);
+  });
+
+  it("multiple dependencies: should call handlers with latest value, only once if not processed yet", () => {
+    let batchManager;
+    const handlers = [
+      [
+        ["foo-0", "bar-1"],
+        vi.fn(() => {
+          doBatch(batchManager, () => {
+            batchManager.notify("foobar-3", "another value");
+            batchManager.notify("baz-2", "not value");
+          });
+        }),
+      ],
+      [
+        ["bar-1", "baz-2"],
+        vi.fn(() => {
+          batchManager.notify("foobar-3", "real value");
+        }),
+      ],
+      [["baz-2"], vi.fn()],
+      [["foobar-3"], vi.fn()],
+    ] as const;
+    batchManager = new BatchManager({ handlers, execHandler });
+    doBatch(batchManager, () => {
+      batchManager.notify("foo-0", "a value");
+      batchManager.notify("bar-1", "another value");
+    });
+    expect(handlers[0][1]).toHaveBeenCalledWith(["a value", "another value"]);
+    expect(handlers[1][1]).toHaveBeenCalledWith(["another value", "not value"]);
+    expect(handlers[2][1]).toHaveBeenCalledWith(["not value"]);
+    expect(handlers[3][1]).toHaveBeenCalledWith(["real value"]);
+    expect(handlers[0][1]).toHaveBeenCalledTimes(1);
+    expect(handlers[1][1]).toHaveBeenCalledTimes(1);
+    expect(handlers[2][1]).toHaveBeenCalledTimes(1);
+    expect(handlers[3][1]).toHaveBeenCalledTimes(1);
+  });
+
+  it("multiple dependencies: preserves order of dependency values", () => {
+    const handlers = [
+      [["foo-0", "bar-1"], vi.fn()],
+      [["bar-1", "baz-2"], vi.fn()],
+      [
+        ["baz-2", "foo-0"],
+        vi.fn(() => {
+          batchManager.notify("foobar-3", "some value");
+        }),
+      ],
+      [
+        ["foobar-3"],
+        vi.fn(() => {
+          batchManager.notify("bar-1", "new value");
+        }),
+      ],
+      [["bar-1", "baz-2", "foo-0"], vi.fn()],
+    ] as const;
+    const batchManager = new BatchManager({ handlers, execHandler });
+    doBatch(batchManager, () => {
+      batchManager.notify("foo-0", "a value");
+      batchManager.notify("baz-2", "real value");
+    });
+    expect(handlers[0][1]).toHaveBeenCalledWith(["a value", undefined]);
+    expect(handlers[1][1]).toHaveBeenCalledWith([undefined, "real value"]);
+    expect(handlers[2][1]).toHaveBeenCalledWith(["real value", "a value"]);
+    expect(handlers[3][1]).toHaveBeenCalledWith(["some value"]);
+    expect(handlers[4][1]).toHaveBeenCalledWith([
+      "new value",
+      "real value",
+      "a value",
+    ]);
+    expect(handlers[0][1]).toHaveBeenCalledTimes(2);
+    expect(handlers[1][1]).toHaveBeenCalledTimes(2);
+    expect(handlers[2][1]).toHaveBeenCalledTimes(1);
+    expect(handlers[3][1]).toHaveBeenCalledTimes(1);
+  });
+
+  it("a handler that locks mid-flush defers the rest until unlock", () => {
+    let batchManager: BatchManager;
+    const handlers = [
+      [
+        ["foo-0"],
+        vi.fn(() => {
+          batchManager.lock();
+        }),
+      ],
+      [["foo-0"], vi.fn()],
+    ] as const;
+    batchManager = new BatchManager({ handlers, execHandler });
+    batchManager.notify("foo-0", "value");
+    expect(handlers[0][1]).toHaveBeenCalledTimes(1);
+    expect(handlers[1][1]).not.toHaveBeenCalled();
+    // still queued, so the notifications are kept for the deferred handler
+    expect(batchManager.queuedHandlers).toHaveLength(1);
+    expect(batchManager.notifs).toEqual({ "foo-0": "value" });
+    batchManager.unlock();
+    expect(handlers[1][1]).toHaveBeenCalledWith(["value"]);
+    expect(batchManager.queuedHandlers).toHaveLength(0);
+    expect(batchManager.notifs).toEqual({});
+  });
+
+  it("uses a per-handler exec function and a custom clearNotifs", () => {
+    const perHandler = vi.fn();
+    const handlers = [
+      [["foo-0"], vi.fn(), perHandler],
+      [["foo-0"], vi.fn()],
+    ] as const;
+    const clearNotifs = vi.fn((notifs) => ({ ...notifs, cleared: true }));
+    const ctx = { name: "ctx" };
+    const batchManager = new BatchManager({
+      handlers,
+      execHandlerCtx: ctx,
+      clearNotifs,
+    });
+    batchManager.notify("foo-0", "v");
+    expect(perHandler).toHaveBeenCalledWith(handlers[0], { "foo-0": "v" });
+    expect(perHandler.mock.instances[0]).toBe(ctx);
+    expect(handlers[0][1]).not.toHaveBeenCalled();
+    // default exec handler calls fn with the notifs as `this` = ctx
+    expect(handlers[1][1]).toHaveBeenCalledWith({ "foo-0": "v" });
+    expect(handlers[1][1].mock.instances[0]).toBe(ctx);
+    expect(clearNotifs).toHaveBeenCalledTimes(1);
+    expect(batchManager.notifs).toEqual({ "foo-0": "v", cleared: true });
+  });
+});
+
+describe("BatchManager: loop guard", () => {
+  let trips: LoopGuardTrip[];
+  let off: () => void;
+
+  beforeEach(() => {
+    LoopGuard.reset();
+    LoopGuard.configure({ log: () => {} });
+    trips = [];
+    off = LoopGuard.onTrip((trip) => trips.push(trip));
+  });
+
+  afterEach(() => {
+    off();
+    LoopGuard.reset();
+  });
+
+  it("cuts a handler that keeps re-queuing itself inside one flush", () => {
+    LoopGuard.configure({ limit: 5 });
+    let batchManager: BatchManager;
+    const runs: number[] = [];
+    const handler = vi.fn((notifs: Record<string, number>) => {
+      runs.push(notifs.n);
+      /* Unlocked: an effect that writes the prop it reacts to would
+       * `notify` → nested flush → recurse forever. */
+      batchManager.notify("n", notifs.n + 1);
+    });
+    const ctx = { name: "ctx" };
+    batchManager = new BatchManager({
+      handlers: [[["n"], handler]],
+      execHandlerCtx: ctx,
+    });
+    expect(() => batchManager.notify("n", 0)).not.toThrow();
+    expect(handler).toHaveBeenCalledTimes(5);
+    expect(runs).toEqual([0, 1, 2, 3, 4]);
+    expect(trips).toHaveLength(1);
+    expect(trips[0]).toMatchObject({
+      kind: "batch",
+      target: ctx,
+      name: "n",
+      depth: 6,
+      limit: 5,
+    });
+    expect(batchManager.queuedHandlers).toEqual([]);
+    expect(batchManager.notifs).toEqual({});
+  });
+
+  it("cuts two handlers feeding each other through a locked batch", () => {
+    LoopGuard.configure({ limit: 4 });
+    let batchManager: BatchManager;
+    const a = vi.fn(() => doBatch(batchManager, () => batchManager.notify("b", 1)));
+    const b = vi.fn(() => doBatch(batchManager, () => batchManager.notify("a", 1)));
+    batchManager = new BatchManager({
+      handlers: [
+        [["a"], a],
+        [["b"], b],
+      ],
+    });
+    doBatch(batchManager, () => batchManager.notify("a", 0));
+    // one of the two crosses the limit first; the whole queue is dropped
+    expect(a.mock.calls.length + b.mock.calls.length).toBeLessThanOrEqual(9);
+    expect(trips).toHaveLength(1);
+    expect(trips[0].kind).toBe("batch");
+    expect(trips[0].target).toBe(batchManager);
+    expect(batchManager.queuedHandlers).toEqual([]);
+  });
+
+  it("counts runs per flush, so repeated separate notifications never trip", () => {
+    LoopGuard.configure({ limit: 3 });
+    const handler = vi.fn();
+    const batchManager = new BatchManager({ handlers: [[["n"], handler]] });
+    for (let i = 0; i < 20; i++) batchManager.notify("n", i);
+    expect(handler).toHaveBeenCalledTimes(20);
+    expect(trips).toEqual([]);
+  });
+
+  it("does not trip a handler legitimately re-run once per dependency", () => {
+    LoopGuard.configure({ limit: 3 });
+    let batchManager: BatchManager;
+    const handler = vi.fn((notifs: Record<string, unknown>) => {
+      // reacting to `a` writes `b` once; reacting to `b` writes nothing
+      if ("a" in notifs && !("b" in notifs)) batchManager.notify("b", 1);
+    });
+    batchManager = new BatchManager({ handlers: [[["a", "b"], handler]] });
+    doBatch(batchManager, () => batchManager.notify("a", 1));
+    expect(handler).toHaveBeenCalledTimes(2);
+    expect(trips).toEqual([]);
+  });
+});