@dcrosstech/dct-ts-utils 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./lib/queue.js";
+export * from "./lib/fifoqueue.js";
+export * from "./lib/heap.js";
+export * from "./lib/priorityqueue.js";
+export * from "./lib/stablepriorityqueue.js";
+export * from "./lib/sleep.js";
+export * from "./lib/semaphore.js";
+export * from "./lib/retry.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from "./lib/queue.js";
+export * from "./lib/fifoqueue.js";
+export * from "./lib/heap.js";
+export * from "./lib/priorityqueue.js";
+export * from "./lib/stablepriorityqueue.js";
+export * from "./lib/sleep.js";
+export * from "./lib/semaphore.js";
+export * from "./lib/retry.js";

package/dist/lib/fifoqueue.d.ts

@@ -0,0 +1,12 @@
+import { Queue } from "./queue";
+export 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[];
+}

package/dist/lib/fifoqueue.js

@@ -0,0 +1,31 @@
+export class FifoQueue {
+    constructor() {
+        this.q = [];
+        this.head = 0;
+    }
+    size() { return this.q.length - this.head; }
+    isEmpty() { return this.size() === 0; }
+    peek() {
+        return this.isEmpty() ? undefined : this.q[this.head];
+    }
+    enqueue(x) {
+        this.q.push(x);
+    }
+    dequeue() {
+        if (this.isEmpty())
+            return undefined;
+        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);
+    }
+}

package/dist/lib/heap.d.ts

@@ -0,0 +1,25 @@
+export 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[];
+}
+export 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;
+}

package/dist/lib/heap.js

@@ -0,0 +1,73 @@
+export class BinaryHeap {
+    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] : undefined;
+    }
+    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 undefined;
+        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;
+    }
+}

package/dist/lib/priorityqueue.d.ts

@@ -0,0 +1,16 @@
+import { Queue } from "./queue";
+export interface PriorityQueue<T> extends Queue<T> {
+    enqueue(value: T, priority?: number): void;
+}
+export 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[];
+}

package/dist/lib/priorityqueue.js

@@ -0,0 +1,40 @@
+import { BinaryHeap } from "./heap";
+export class HeapPriorityQueue {
+    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; // stable on ties
+        });
+    }
+    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);
+    }
+}

package/dist/lib/queue.d.ts

@@ -0,0 +1,9 @@
+export interface Queue<T> {
+    size(): number;
+    isEmpty(): boolean;
+    peek(): T | undefined;
+    enqueue(x: T): void;
+    dequeue(): T | undefined;
+    clear(): void;
+    toArray(): T[];
+}

package/dist/lib/queue.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/retry.d.ts

@@ -0,0 +1,18 @@
+export declare class RetryError<Args = unknown> extends Error {
+    readonly retryArgs: Args;
+    readonly finalError?: Error;
+    constructor(message: string, retryArgs: Args, finalError?: Error);
+}
+export declare class TerminalError extends Error {
+    constructor(message: string);
+}
+export type BackoffConfig = {
+    quantumMs?: number;
+    minDelayMs?: number;
+    maxDelayMs?: number;
+    maxRetries?: number;
+    factor?: number;
+    maxExponent?: number;
+    jitter?: number;
+};
+export declare function executeWithExponentialBackoff<Args, R>(cfg: BackoffConfig | undefined, fn: (args: Args) => Promise<R> | R, initialArgs: Args): Promise<R>;

package/dist/lib/retry.js

@@ -0,0 +1,102 @@
+import { sleep } from "./sleep";
+export class RetryError extends Error {
+    constructor(message, retryArgs, finalError) {
+        super(message);
+        this.name = "RetryError";
+        this.retryArgs = retryArgs;
+        this.finalError = finalError;
+    }
+}
+export class TerminalError 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 !== undefined) {
+        mustFinite("maxDelayMs", maxDelayMs, maxDelayMs < 0 ? "must be >= 0" : "");
+    }
+    const maxD = maxDelayMs === undefined ? undefined : Math.trunc(maxDelayMs);
+    const maxRetries = cfg?.maxRetries;
+    if (maxRetries !== undefined) {
+        mustFinite("maxRetries", maxRetries, maxRetries < 0 ? "must be >= 0" : "");
+    }
+    const maxR = maxRetries === undefined ? undefined : 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 !== undefined) {
+        mustFinite("maxExponent", maxExponent, maxExponent < 0 ? "must be >= 0" : "");
+    }
+    const maxE = maxExponent === undefined ? undefined : Math.trunc(maxExponent);
+    const jitter = cfg?.jitter;
+    if (jitter !== undefined) {
+        mustFinite("jitter", jitter, jitter < 0 || jitter > 1 ? "must be in [0,1]" : "");
+    }
+    const j = jitter;
+    if (maxD !== undefined && 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 === undefined ? 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 !== undefined && d > 0) {
+        const r = (Math.random() * 2 - 1) * jitter;
+        d = d * (1 + r);
+    }
+    if (d < minD)
+        d = minD;
+    if (maxD !== undefined && d > maxD)
+        d = maxD;
+    return Math.trunc(d);
+}
+export async function executeWithExponentialBackoff(cfg, fn, initialArgs) {
+    const { q, minD, maxD, maxR, f, maxE, j } = normalizeConfig(cfg);
+    let args = initialArgs;
+    for (let attemptIndex = 0;; attemptIndex++) {
+        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;
+            }
+            // Out of retries?
+            if (maxR !== undefined && attemptIndex >= maxR) {
+                if (finalOnExhaustion) {
+                    throw finalOnExhaustion;
+                }
+                throw err;
+            }
+            const retryAttempt = attemptIndex + 1; // 1-based retry count
+            const delayMs = computeDelayMs(q, minD, maxD, f, maxE, j, retryAttempt);
+            if (delayMs > 0) {
+                await sleep(delayMs);
+            }
+        }
+    }
+}

package/dist/lib/semaphore.d.ts

@@ -0,0 +1,33 @@
+export type SemaphoreRunOptions = {
+    weight?: number;
+    priority?: number;
+};
+export type SemaphoreOptions = {
+    usePriorityQueue?: boolean;
+};
+type WorkItem<R> = {
+    weight: number;
+    priority: number;
+    fn: () => Promise<R> | R;
+    resolve: (v: R) => void;
+    reject: (e: unknown) => void;
+};
+export 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;
+}
+export {};

package/dist/lib/semaphore.js

@@ -0,0 +1,121 @@
+import { StablePriorityQueue } from "./stablepriorityqueue";
+import { FifoQueue } from "./fifoqueue";
+export class Semaphore {
+    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 };
+            // Don't bypass queued work: only run immediately if queue is empty.
+            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);
+    }
+}

package/dist/lib/sleep.d.ts

@@ -0,0 +1,10 @@
+export declare class CancellationError extends Error {
+    readonly remainingMs: number;
+    constructor(message: string, remainingMs: number);
+}
+export interface SleepPromise extends Promise<void> {
+    cancel(reason?: unknown): boolean;
+    hasCompleted(): boolean;
+    remainingTime(): number;
+}
+export declare function sleep(durationMs: number): SleepPromise;

package/dist/lib/sleep.js

@@ -0,0 +1,60 @@
+export class CancellationError extends Error {
+    constructor(message, remainingMs) {
+        super(message);
+        this.name = "CancellationError";
+        this.remainingMs = remainingMs;
+    }
+}
+export 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;
+}

package/dist/lib/stablepriorityqueue.d.ts

@@ -0,0 +1,13 @@
+import { PriorityQueue } from "./priorityqueue";
+export 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[];
+}

package/dist/lib/stablepriorityqueue.js

@@ -0,0 +1,40 @@
+import { BinaryHeap } from "./heap";
+export class StablePriorityQueue {
+    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; // FIFO on ties
+        });
+    }
+    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);
+    }
+}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@dcrosstech/dct-ts-utils",
+  "version": "1.0.0",
+  "description": "Common TypeScript utilities (sleep, semaphore, queues, heaps, exponential backoff)",
+  "license": "ISC",
+  "author": "David Cross <david@crossfamilyweb.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://git.dcrosstech.com/public/dct-ts-utils"
+  },
+  "keywords": [
+    "sleep",
+    "semaphore",
+    "exponential-backoff",
+    "priority-queue",
+    "heap",
+    "queue",
+    "typescript",
+    "async"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./fifoqueue": {
+      "types": "./dist/lib/fifoqueue.d.ts",
+      "import": "./dist/lib/fifoqueue.js"
+    },
+    "./heap": {
+      "types": "./dist/lib/heap.d.ts",
+      "import": "./dist/lib/heap.js"
+    },
+    "./priorityqueue": {
+      "types": "./dist/lib/priorityqueue.d.ts",
+      "import": "./dist/lib/priorityqueue.js"
+    },
+    "./queue": {
+      "types": "./dist/lib/queue.d.ts",
+      "import": "./dist/lib/queue.js"
+    },
+    "./retry": {
+      "types": "./dist/lib/retry.d.ts",
+      "import": "./dist/lib/retry.js"
+    },
+    "./semaphore": {
+      "types": "./dist/lib/semaphore.d.ts",
+      "import": "./dist/lib/semaphore.js"
+    },
+    "./sleep": {
+      "types": "./dist/lib/sleep.d.ts",
+      "import": "./dist/lib/sleep.js"
+    },
+    "./stablepriorityqueue": {
+      "types": "./dist/lib/stablepriorityqueue.d.ts",
+      "import": "./dist/lib/stablepriorityqueue.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "test": "echo \"No tests specified\" && exit 0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  }
+}