@dcrosstech/dct-ts-utils 1.1.0 → 1.2.0

package/dist/index.cjs

@@ -0,0 +1,523 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// index.ts
+var index_exports = {};
+__export(index_exports, {
+  BinaryHeap: () => BinaryHeap,
+  CancellationError: () => CancellationError,
+  FifoQueue: () => FifoQueue,
+  HeapPriorityQueue: () => HeapPriorityQueue,
+  RetryError: () => RetryError,
+  Semaphore: () => Semaphore,
+  StablePriorityQueue: () => StablePriorityQueue,
+  TerminalError: () => TerminalError,
+  executeWithExponentialBackoff: () => executeWithExponentialBackoff,
+  sleep: () => sleep
+});
+module.exports = __toCommonJS(index_exports);
+
+// lib/fifoqueue.ts
+var FifoQueue = class {
+  constructor() {
+    this.q = [];
+    this.head = 0;
+  }
+  size() {
+    return this.q.length - this.head;
+  }
+  isEmpty() {
+    return this.size() === 0;
+  }
+  peek() {
+    return this.isEmpty() ? void 0 : this.q[this.head];
+  }
+  enqueue(x) {
+    this.q.push(x);
+  }
+  dequeue() {
+    if (this.isEmpty()) return void 0;
+    const x = this.q[this.head++];
+    if (this.head > 64 && this.head * 2 > this.q.length) {
+      this.q = this.q.slice(this.head);
+      this.head = 0;
+    }
+    return x;
+  }
+  clear() {
+    this.q.length = 0;
+    this.head = 0;
+  }
+  toArray() {
+    return this.q.slice(this.head);
+  }
+};
+
+// lib/heap.ts
+var BinaryHeap = class {
+  constructor(compare) {
+    this.heap = [];
+    this.compare = compare ?? ((a, b) => a - b);
+  }
+  size() {
+    return this.heap.length;
+  }
+  isEmpty() {
+    return this.heap.length === 0;
+  }
+  peek() {
+    return this.heap.length ? this.heap[0] : void 0;
+  }
+  push(value) {
+    this.heap.push(value);
+    this.siftUp(this.heap.length - 1);
+    return this.heap.length;
+  }
+  pop() {
+    const n = this.heap.length;
+    if (n === 0) return void 0;
+    const top = this.heap[0];
+    const last = this.heap.pop();
+    if (n > 1) {
+      this.heap[0] = last;
+      this.siftDown(0);
+    }
+    return top;
+  }
+  clear() {
+    this.heap.length = 0;
+  }
+  heapify(values) {
+    this.heap = Array.from(values);
+    for (let i = (this.heap.length >> 1) - 1; i >= 0; i--) {
+      this.siftDown(i);
+    }
+    return this;
+  }
+  toArray() {
+    return this.heap.slice();
+  }
+  siftUp(i) {
+    const { heap, compare } = this;
+    const x = heap[i];
+    while (i > 0) {
+      const p = i - 1 >> 1;
+      const pv = heap[p];
+      if (compare(x, pv) >= 0) break;
+      heap[i] = pv;
+      i = p;
+    }
+    heap[i] = x;
+  }
+  siftDown(i) {
+    const { heap, compare } = this;
+    const n = heap.length;
+    const x = heap[i];
+    while (true) {
+      const l = (i << 1) + 1;
+      if (l >= n) break;
+      const r = l + 1;
+      let c = l;
+      if (r < n && compare(heap[r], heap[l]) < 0) c = r;
+      if (compare(heap[c], x) >= 0) break;
+      heap[i] = heap[c];
+      i = c;
+    }
+    heap[i] = x;
+  }
+};
+
+// lib/priorityqueue.ts
+var HeapPriorityQueue = class {
+  constructor() {
+    this.seq = 0;
+    this.heap = new BinaryHeap((a, b) => {
+      if (a.priority !== b.priority) return a.priority - b.priority;
+      return a.seq - b.seq;
+    });
+  }
+  size() {
+    return this.heap.size();
+  }
+  isEmpty() {
+    return this.heap.isEmpty();
+  }
+  peek() {
+    return this.heap.peek()?.value;
+  }
+  enqueue(value, priority = 0) {
+    if (!Number.isFinite(priority)) {
+      throw new TypeError(`priority must be finite; got ${priority}`);
+    }
+    this.heap.push({
+      value,
+      priority: Math.trunc(priority),
+      seq: this.seq++
+    });
+  }
+  dequeue() {
+    return this.heap.pop()?.value;
+  }
+  clear() {
+    this.heap.clear();
+    this.seq = 0;
+  }
+  toArray() {
+    return this.heap.toArray().map((n) => n.value);
+  }
+};
+
+// lib/stablepriorityqueue.ts
+var StablePriorityQueue = class {
+  constructor() {
+    this.seq = 0;
+    this.heap = new BinaryHeap((a, b) => {
+      if (a.priority !== b.priority) return a.priority - b.priority;
+      return a.seq - b.seq;
+    });
+  }
+  size() {
+    return this.heap.size();
+  }
+  isEmpty() {
+    return this.heap.isEmpty();
+  }
+  peek() {
+    return this.heap.peek()?.value;
+  }
+  enqueue(value, priority = 0) {
+    if (!Number.isFinite(priority)) {
+      throw new TypeError(`priority must be finite; got ${priority}`);
+    }
+    this.heap.push({
+      value,
+      priority: Math.trunc(priority),
+      seq: this.seq++
+    });
+  }
+  dequeue() {
+    return this.heap.pop()?.value;
+  }
+  clear() {
+    this.heap.clear();
+    this.seq = 0;
+  }
+  toArray() {
+    return this.heap.toArray().map((n) => n.value);
+  }
+};
+
+// lib/sleep.ts
+var CancellationError = class extends Error {
+  constructor(message, remainingMs) {
+    super(message);
+    this.name = "CancellationError";
+    this.remainingMs = remainingMs;
+  }
+};
+function sleep(durationMs) {
+  if (!Number.isFinite(durationMs)) {
+    throw new TypeError(`durationMs must be finite; got ${durationMs}`);
+  }
+  const delay = Math.max(0, Math.trunc(durationMs));
+  const startMs = Date.now();
+  let completed = false;
+  let cancelled = false;
+  let executedAtMs = null;
+  let cancelledAtMs = null;
+  let timer = null;
+  let resolveFn;
+  let rejectFn;
+  const promise = new Promise((resolve, reject) => {
+    resolveFn = resolve;
+    rejectFn = reject;
+    timer = setTimeout(() => {
+      if (cancelled) return;
+      completed = true;
+      executedAtMs = Date.now();
+      resolve();
+    }, delay);
+  });
+  function remainingAt(nowMs) {
+    if (cancelled && cancelledAtMs != null) {
+      return delay - (cancelledAtMs - startMs);
+    }
+    if (completed) {
+      const exec = executedAtMs ?? startMs + delay;
+      return -(nowMs - exec);
+    }
+    const r = delay - (nowMs - startMs);
+    return r <= 0 ? 0 : r;
+  }
+  promise.cancel = (reason) => {
+    if (completed || cancelled) return false;
+    cancelled = true;
+    cancelledAtMs = Date.now();
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    const remaining = remainingAt(cancelledAtMs);
+    rejectFn(
+      reason ?? new CancellationError(
+        `Sleep cancelled with ${remaining}ms remaining`,
+        remaining
+      )
+    );
+    return true;
+  };
+  promise.hasCompleted = () => completed;
+  promise.remainingTime = () => remainingAt(Date.now());
+  return promise;
+}
+
+// lib/semaphore.ts
+var Semaphore = class {
+  constructor(max, opts = {}, initialCount) {
+    this.inFlightWeight = 0;
+    if (!Number.isFinite(max) || max < 0) {
+      throw new TypeError(`max must be finite and >= 0; got ${max}`);
+    }
+    this.max = Math.trunc(max);
+    const start = initialCount ?? this.max;
+    if (!Number.isFinite(start)) {
+      throw new TypeError(`initialCount must be finite; got ${start}`);
+    }
+    this.count = Math.trunc(start);
+    if (opts.usePriorityQueue) {
+      const pq = new StablePriorityQueue();
+      this.queue = pq;
+      this.pqueue = pq;
+    } else {
+      this.queue = new FifoQueue();
+      this.pqueue = null;
+    }
+  }
+  getMax() {
+    return this.max;
+  }
+  getCount() {
+    return this.count;
+  }
+  setMax(newMax) {
+    if (!Number.isFinite(newMax) || newMax < 0) {
+      throw new TypeError(`newMax must be finite and >= 0; got ${newMax}`);
+    }
+    newMax = Math.trunc(newMax);
+    if (newMax < this.inFlightWeight) {
+      throw new RangeError(`newMax (${newMax}) < inFlightWeight (${this.inFlightWeight})`);
+    }
+    for (const item of this.queue.toArray()) {
+      if (item.weight > newMax) {
+        throw new RangeError(`queued weight ${item.weight} exceeds newMax ${newMax}`);
+      }
+    }
+    this.max = newMax;
+    this.drain();
+  }
+  setCount(newCount) {
+    if (!Number.isFinite(newCount)) {
+      throw new TypeError(`newCount must be finite; got ${newCount}`);
+    }
+    this.count = Math.trunc(newCount);
+    for (const item of this.queue.toArray()) {
+      if (item.weight > this.max) {
+        throw new RangeError(`queued weight ${item.weight} exceeds max ${this.max}`);
+      }
+    }
+    this.drain();
+  }
+  run(fn, opts = {}) {
+    const weight = Math.trunc(opts.weight ?? 1);
+    const priority = Math.trunc(opts.priority ?? 0);
+    if (!Number.isFinite(weight) || weight <= 0) {
+      throw new TypeError(`weight must be a finite integer > 0; got ${opts.weight}`);
+    }
+    if (!Number.isFinite(priority)) {
+      throw new TypeError(`priority must be finite; got ${opts.priority}`);
+    }
+    if (weight > this.max) {
+      throw new RangeError(`weight (${weight}) exceeds semaphore max (${this.max})`);
+    }
+    return new Promise((resolve, reject) => {
+      const item = { weight, priority, fn, resolve, reject };
+      if (this.queue.isEmpty() && this.count >= weight) {
+        this.start(item);
+        return;
+      }
+      if (this.pqueue) this.pqueue.enqueue(item, priority);
+      else this.queue.enqueue(item);
+      this.drain();
+    });
+  }
+  drain() {
+    while (true) {
+      const head = this.queue.peek();
+      if (!head) return;
+      if (this.count < head.weight) return;
+      this.start(this.queue.dequeue());
+    }
+  }
+  releaseAndScheduleDrain(weight) {
+    this.count += weight;
+    this.inFlightWeight -= weight;
+    this.drain();
+  }
+  completeResolve(item, value) {
+    this.releaseAndScheduleDrain(item.weight);
+    item.resolve(value);
+  }
+  completeReject(item, error) {
+    this.releaseAndScheduleDrain(item.weight);
+    item.reject(error);
+  }
+  start(item) {
+    this.count -= item.weight;
+    this.inFlightWeight += item.weight;
+    let r;
+    try {
+      r = item.fn();
+    } catch (e) {
+      this.completeReject(item, e);
+      return;
+    }
+    if (r && typeof r.then === "function") {
+      r.then(
+        (v) => this.completeResolve(item, v),
+        (e) => this.completeReject(item, e)
+      );
+      return;
+    }
+    this.completeResolve(item, r);
+  }
+};
+
+// lib/retry.ts
+var RetryError = class extends Error {
+  constructor(message, retryArgs, finalError, retryAfter) {
+    super(message);
+    this.name = "RetryError";
+    this.retryArgs = retryArgs;
+    this.finalError = finalError;
+    this.retryAfter = retryAfter;
+  }
+};
+var TerminalError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TerminalError";
+  }
+};
+function mustFinite(name, v, extra) {
+  if (!Number.isFinite(v)) throw new TypeError(`${name} must be finite; got ${v}`);
+  if (extra) throw new TypeError(`${name} ${extra}; got ${v}`);
+}
+function normalizeConfig(cfg) {
+  const quantumMs = cfg?.quantumMs ?? 10;
+  mustFinite("quantumMs", quantumMs, quantumMs < 0 ? "must be >= 0" : "");
+  const q = Math.trunc(quantumMs);
+  const minDelayMs = cfg?.minDelayMs ?? q;
+  mustFinite("minDelayMs", minDelayMs, minDelayMs < 0 ? "must be >= 0" : "");
+  const minD = Math.trunc(minDelayMs);
+  const maxDelayMs = cfg?.maxDelayMs;
+  if (maxDelayMs !== void 0) {
+    mustFinite("maxDelayMs", maxDelayMs, maxDelayMs < 0 ? "must be >= 0" : "");
+  }
+  const maxD = maxDelayMs === void 0 ? void 0 : Math.trunc(maxDelayMs);
+  const maxRetries = cfg?.maxRetries;
+  if (maxRetries !== void 0) {
+    mustFinite("maxRetries", maxRetries, maxRetries < 0 ? "must be >= 0" : "");
+  }
+  const maxR = maxRetries === void 0 ? void 0 : Math.trunc(maxRetries);
+  const factor = cfg?.factor ?? 2;
+  mustFinite("factor", factor, factor <= 0 ? "must be > 0" : "");
+  const f = factor;
+  const maxExponent = cfg?.maxExponent;
+  if (maxExponent !== void 0) {
+    mustFinite("maxExponent", maxExponent, maxExponent < 0 ? "must be >= 0" : "");
+  }
+  const maxE = maxExponent === void 0 ? void 0 : Math.trunc(maxExponent);
+  const jitter = cfg?.jitter;
+  if (jitter !== void 0) {
+    mustFinite("jitter", jitter, jitter < 0 || jitter > 1 ? "must be in [0,1]" : "");
+  }
+  const j = jitter;
+  if (maxD !== void 0 && maxD < minD) {
+    throw new RangeError(`maxDelayMs (${maxD}) < minDelayMs (${minD})`);
+  }
+  return { q, minD, maxD, maxR, f, maxE, j };
+}
+function computeDelayMs(q, minD, maxD, factor, maxE, jitter, retryAttempt) {
+  const k = maxE === void 0 ? retryAttempt : Math.min(retryAttempt, maxE);
+  const pow = Math.pow(factor, k);
+  const upperSteps = Number.isFinite(pow) ? Math.max(0, Math.floor(pow) - 1) : Number.MAX_SAFE_INTEGER;
+  const steps = upperSteps === 0 ? 0 : Math.floor(Math.random() * (upperSteps + 1));
+  let d = steps * q;
+  if (jitter !== void 0 && d > 0) {
+    const r = (Math.random() * 2 - 1) * jitter;
+    d = d * (1 + r);
+  }
+  if (d < minD) d = minD;
+  if (maxD !== void 0 && d > maxD) d = maxD;
+  return Math.trunc(d);
+}
+async function executeWithExponentialBackoff(cfg, fn, initialArgs) {
+  const { q, minD, maxD, maxR, f, maxE, j } = normalizeConfig(cfg);
+  let args = initialArgs;
+  let retryAfter;
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await fn(args);
+    } catch (err) {
+      if (err instanceof TerminalError) throw err;
+      let finalOnExhaustion;
+      if (err instanceof RetryError) {
+        args = err.retryArgs;
+        finalOnExhaustion = err.finalError;
+        retryAfter = err.retryAfter;
+      }
+      if (maxR !== void 0 && attempt >= maxR) {
+        if (finalOnExhaustion) {
+          throw finalOnExhaustion;
+        }
+        throw err;
+      }
+      const retryAttempt = attempt + 1;
+      if (!retryAfter) {
+        retryAfter = computeDelayMs(q, minD, maxD, f, maxE, j, retryAttempt);
+      }
+      if (retryAfter > 0) {
+        await sleep(retryAfter);
+      }
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BinaryHeap,
+  CancellationError,
+  FifoQueue,
+  HeapPriorityQueue,
+  RetryError,
+  Semaphore,
+  StablePriorityQueue,
+  TerminalError,
+  executeWithExponentialBackoff,
+  sleep
+});

package/dist/index.d.cts

@@ -0,0 +1,142 @@
+interface Queue<T> {
+    size(): number;
+    isEmpty(): boolean;
+    peek(): T | undefined;
+    enqueue(x: T): void;
+    dequeue(): T | undefined;
+    clear(): void;
+    toArray(): T[];
+}
+
+declare class FifoQueue<T> implements Queue<T> {
+    private q;
+    private head;
+    size(): number;
+    isEmpty(): boolean;
+    peek(): T | undefined;
+    enqueue(x: T): void;
+    dequeue(): T | undefined;
+    clear(): void;
+    toArray(): T[];
+}
+
+interface Heap<T> {
+    size(): number;
+    isEmpty(): boolean;
+    peek(): T | undefined;
+    push(value: T): number;
+    pop(): T | undefined;
+    clear(): void;
+    heapify(values: Iterable<T>): this;
+    toArray(): T[];
+}
+declare class BinaryHeap<T> implements Heap<T> {
+    private heap;
+    private readonly compare;
+    constructor(compare?: (a: T, b: T) => number);
+    size(): number;
+    isEmpty(): boolean;
+    peek(): T | undefined;
+    push(value: T): number;
+    pop(): T | undefined;
+    clear(): void;
+    heapify(values: Iterable<T>): this;
+    toArray(): T[];
+    private siftUp;
+    private siftDown;
+}
+
+interface PriorityQueue<T> extends Queue<T> {
+    enqueue(value: T, priority?: number): void;
+}
+declare class HeapPriorityQueue<T> implements PriorityQueue<T> {
+    private readonly heap;
+    private seq;
+    constructor();
+    size(): number;
+    isEmpty(): boolean;
+    peek(): T | undefined;
+    enqueue(value: T, priority?: number): void;
+    dequeue(): T | undefined;
+    clear(): void;
+    toArray(): T[];
+}
+
+declare class StablePriorityQueue<T> implements PriorityQueue<T> {
+    private readonly heap;
+    private seq;
+    constructor();
+    size(): number;
+    isEmpty(): boolean;
+    peek(): T | undefined;
+    enqueue(value: T, priority?: number): void;
+    dequeue(): T | undefined;
+    clear(): void;
+    toArray(): T[];
+}
+
+declare class CancellationError extends Error {
+    readonly remainingMs: number;
+    constructor(message: string, remainingMs: number);
+}
+interface SleepPromise extends Promise<void> {
+    cancel(reason?: unknown): boolean;
+    hasCompleted(): boolean;
+    remainingTime(): number;
+}
+declare function sleep(durationMs: number): SleepPromise;
+
+type SemaphoreRunOptions = {
+    weight?: number;
+    priority?: number;
+};
+type SemaphoreOptions = {
+    usePriorityQueue?: boolean;
+};
+type WorkItem<R> = {
+    weight: number;
+    priority: number;
+    fn: () => Promise<R> | R;
+    resolve: (v: R) => void;
+    reject: (e: unknown) => void;
+};
+declare class Semaphore {
+    private max;
+    private count;
+    private inFlightWeight;
+    private readonly queue;
+    private readonly pqueue;
+    constructor(max: number, opts?: SemaphoreOptions, initialCount?: number);
+    getMax(): number;
+    getCount(): number;
+    setMax(newMax: number): void;
+    setCount(newCount: number): void;
+    run<R>(fn: () => Promise<R> | R, opts?: SemaphoreRunOptions): Promise<R>;
+    private drain;
+    protected releaseAndScheduleDrain(weight: number): void;
+    protected completeResolve<R>(item: WorkItem<R>, value: R): void;
+    protected completeReject<R>(item: WorkItem<R>, error: unknown): void;
+    private start;
+}
+
+declare class RetryError<Args = unknown> extends Error {
+    readonly retryArgs: Args;
+    readonly finalError?: Error;
+    readonly retryAfter?: number;
+    constructor(message: string, retryArgs: Args, finalError?: Error, retryAfter?: number);
+}
+declare class TerminalError extends Error {
+    constructor(message: string);
+}
+type BackoffConfig = {
+    quantumMs?: number;
+    minDelayMs?: number;
+    maxDelayMs?: number;
+    maxRetries?: number;
+    factor?: number;
+    maxExponent?: number;
+    jitter?: number;
+};
+declare function executeWithExponentialBackoff<Args, R>(cfg: BackoffConfig | undefined, fn: (args: Args) => Promise<R> | R, initialArgs: Args): Promise<R>;
+
+export { type BackoffConfig, BinaryHeap, CancellationError, FifoQueue, type Heap, HeapPriorityQueue, type PriorityQueue, type Queue, RetryError, Semaphore, type SemaphoreOptions, type SemaphoreRunOptions, type SleepPromise, StablePriorityQueue, TerminalError, executeWithExponentialBackoff, sleep };