@aztec/foundation 0.0.0-test.0

package/dest/queue/bounded_serial_queue.js

@@ -0,0 +1,84 @@
+import { createLogger } from '../log/index.js';
+import { Semaphore } from './semaphore.js';
+import { SerialQueue } from './serial_queue.js';
+/**
+ * Leverages the unbounded SerialQueue and Semaphore to create a SerialQueue that will block when putting an item
+ * if the queue size = maxQueueSize.
+ */ export class BoundedSerialQueue {
+    log;
+    queue;
+    semaphore;
+    constructor(maxQueueSize, log = createLogger('foundation:bounded_serial_queue')){
+        this.log = log;
+        this.queue = new SerialQueue();
+        this.semaphore = new Semaphore(maxQueueSize);
+    }
+    /**
+   * Initializes the underlying SerialQueue instance, allowing items to be processed from the queue.
+   * The start method should be called before using the BoundedSerialQueue to ensure proper functionality.
+   */ start() {
+        this.queue.start();
+    }
+    /**
+   * Returns the current number of items in the queue.
+   * This is useful for monitoring the size of BoundedSerialQueue and understanding its utilization.
+   *
+   * @returns The length of the queue as an integer value.
+   */ length() {
+        return this.queue.length();
+    }
+    /**
+   * Cancels the current operation in the SerialQueue, if any, and clears the queue.
+   * Any pending tasks in the queue will not be executed, and the queue will be emptied.
+   * This method is useful for cleaning up resources and stopping ongoing processes when they are no longer needed.
+   * @returns A promise, resolved once cancelled.
+   */ cancel() {
+        return this.queue.cancel();
+    }
+    /**
+   * Ends the queue processing gracefully, preventing new items from being added.
+   * The currently executing item, if any, will complete and remaining queued items
+   * will be processed in order. Once all items have been processed, the queue becomes
+   * permanently unusable.
+   *
+   * @returns A promise that resolves when all items in the queue have been processed.
+   */ end() {
+        return this.queue.end();
+    }
+    /**
+   * The caller will block until fn is successfully enqueued.
+   * The fn itself is execute asynchronously and its result discarded.
+   * TODO(AD) do we need this if we have exec()?
+   * @param fn - The function to call once unblocked.
+   */ async put(fn) {
+        await this.semaphore.acquire();
+        this.queue.put(async ()=>{
+            try {
+                await fn();
+            } finally{
+                this.semaphore.release();
+            }
+        }).catch((err)=>{
+            this.log.error('BoundedSerialQueue handler exception:', err);
+        });
+    }
+    /**
+   * The caller will block until fn is successfully executed, and it's result returned.
+   * @param fn - The function.
+   * @returns A promise that resolves with the result once executed.
+   */ async exec(fn) {
+        await this.semaphore.acquire();
+        return this.queue.put(async ()=>{
+            try {
+                return await fn();
+            } finally{
+                this.semaphore.release();
+            }
+        });
+    }
+    /**
+   * Awaiting this ensures the queue is empty before resuming.
+   */ async syncPoint() {
+        await this.queue.syncPoint();
+    }
+}

package/dest/queue/fifo_memory_queue.d.ts

@@ -0,0 +1,21 @@
+import type { Logger } from '../log/index.js';
+import { BaseMemoryQueue } from './base_memory_queue.js';
+/**
+ * A simple fifo queue. It can grow unbounded. It can have multiple producers and consumers.
+ * Putting an item onto the queue always succeeds, unless either end() or cancel() has been called in which case
+ * the item being pushed is simply discarded.
+ */
+export declare class FifoMemoryQueue<T> extends BaseMemoryQueue<T> {
+    private container;
+    constructor(log?: Logger);
+    protected get items(): FifoQueue<T>;
+}
+declare class FifoQueue<T> {
+    private items;
+    put(item: T): void;
+    get(): T | undefined;
+    get length(): number;
+    clear(): void;
+}
+export {};
+//# sourceMappingURL=fifo_memory_queue.d.ts.map

package/dest/queue/fifo_memory_queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fifo_memory_queue.d.ts","sourceRoot":"","sources":["../../src/queue/fifo_memory_queue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD;;;;GAIG;AACH,qBAAa,eAAe,CAAC,CAAC,CAAE,SAAQ,eAAe,CAAC,CAAC,CAAC;IACxD,OAAO,CAAC,SAAS,CAAsB;gBAE3B,GAAG,CAAC,EAAE,MAAM;IAIxB,cAAuB,KAAK,iBAE3B;CACF;AAED,cAAM,SAAS,CAAC,CAAC;IACf,OAAO,CAAC,KAAK,CAAW;IAEjB,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI;IAIlB,GAAG,IAAI,CAAC,GAAG,SAAS;IAI3B,IAAW,MAAM,IAAI,MAAM,CAE1B;IAEM,KAAK;CAGb"}

package/dest/queue/fifo_memory_queue.js

@@ -0,0 +1,29 @@
+import { BaseMemoryQueue } from './base_memory_queue.js';
+/**
+ * A simple fifo queue. It can grow unbounded. It can have multiple producers and consumers.
+ * Putting an item onto the queue always succeeds, unless either end() or cancel() has been called in which case
+ * the item being pushed is simply discarded.
+ */ export class FifoMemoryQueue extends BaseMemoryQueue {
+    container = new FifoQueue();
+    constructor(log){
+        super(log);
+    }
+    get items() {
+        return this.container;
+    }
+}
+class FifoQueue {
+    items = [];
+    put(item) {
+        this.items.push(item);
+    }
+    get() {
+        return this.items.shift();
+    }
+    get length() {
+        return this.items.length;
+    }
+    clear() {
+        this.items = [];
+    }
+}

package/dest/queue/index.d.ts

@@ -0,0 +1,7 @@
+export * from './fifo_memory_queue.js';
+export * from './priority_memory_queue.js';
+export * from './serial_queue.js';
+export * from './bounded_serial_queue.js';
+export * from './semaphore.js';
+export * from './batch_queue.js';
+//# sourceMappingURL=index.d.ts.map

package/dest/queue/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/queue/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,mBAAmB,CAAC;AAClC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC"}

package/dest/queue/index.js

@@ -0,0 +1,6 @@
+export * from './fifo_memory_queue.js';
+export * from './priority_memory_queue.js';
+export * from './serial_queue.js';
+export * from './bounded_serial_queue.js';
+export * from './semaphore.js';
+export * from './batch_queue.js';

package/dest/queue/priority_memory_queue.d.ts

@@ -0,0 +1,13 @@
+import { BaseMemoryQueue } from './base_memory_queue.js';
+import { PriorityQueue } from './priority_queue.js';
+/**
+ * A priority queue. It can grow unbounded. It can have multiple producers and consumers.
+ * Putting an item onto the queue always succeeds, unless either end() or cancel() has been called in which case
+ * the item being pushed is simply discarded.
+ */
+export declare class PriorityMemoryQueue<T> extends BaseMemoryQueue<T> {
+    private container;
+    constructor(comparator: (a: T, b: T) => number);
+    protected get items(): PriorityQueue<T>;
+}
+//# sourceMappingURL=priority_memory_queue.d.ts.map

package/dest/queue/priority_memory_queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"priority_memory_queue.d.ts","sourceRoot":"","sources":["../../src/queue/priority_memory_queue.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD;;;;GAIG;AACH,qBAAa,mBAAmB,CAAC,CAAC,CAAE,SAAQ,eAAe,CAAC,CAAC,CAAC;IAC5D,OAAO,CAAC,SAAS,CAAmB;gBAExB,UAAU,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,MAAM;IAK9C,cAAuB,KAAK,qBAE3B;CACF"}

package/dest/queue/priority_memory_queue.js

@@ -0,0 +1,16 @@
+import { BaseMemoryQueue } from './base_memory_queue.js';
+import { PriorityQueue } from './priority_queue.js';
+/**
+ * A priority queue. It can grow unbounded. It can have multiple producers and consumers.
+ * Putting an item onto the queue always succeeds, unless either end() or cancel() has been called in which case
+ * the item being pushed is simply discarded.
+ */ export class PriorityMemoryQueue extends BaseMemoryQueue {
+    container;
+    constructor(comparator){
+        super();
+        this.container = new PriorityQueue(comparator);
+    }
+    get items() {
+        return this.container;
+    }
+}

package/dest/queue/priority_queue.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Priority queue implementation based on a custom comparator.
+ */
+export declare class PriorityQueue<T> {
+    private comparator;
+    private items;
+    constructor(comparator: (a: T, b: T) => number);
+    put(item: T): void;
+    get(): T | undefined;
+    peek(): T | undefined;
+    clear(): void;
+    get length(): number;
+}
+//# sourceMappingURL=priority_queue.d.ts.map

package/dest/queue/priority_queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"priority_queue.d.ts","sourceRoot":"","sources":["../../src/queue/priority_queue.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,aAAa,CAAC,CAAC;IAGd,OAAO,CAAC,UAAU;IAF9B,OAAO,CAAC,KAAK,CAAM;gBAEC,UAAU,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,MAAM;IAI/C,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI;IAQlB,GAAG,IAAI,CAAC,GAAG,SAAS;IAIpB,IAAI,IAAI,CAAC,GAAG,SAAS;IAIrB,KAAK;IAIZ,IAAW,MAAM,IAAI,MAAM,CAE1B;CACF"}

package/dest/queue/priority_queue.js

@@ -0,0 +1,29 @@
+/**
+ * Priority queue implementation based on a custom comparator.
+ */ export class PriorityQueue {
+    comparator;
+    items;
+    constructor(comparator){
+        this.comparator = comparator;
+        this.items = [];
+    }
+    put(item) {
+        let i = 0;
+        while(i < this.items.length && this.comparator(item, this.items[i]) >= 0){
+            i++;
+        }
+        this.items.splice(i, 0, item);
+    }
+    get() {
+        return this.items.shift();
+    }
+    peek() {
+        return this.items[0];
+    }
+    clear() {
+        this.items = [];
+    }
+    get length() {
+        return this.items.length;
+    }
+}

package/dest/queue/semaphore.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Allows the acquiring of up to `size` tokens before calls to acquire block, waiting for a call to release().
+ */
+export declare class Semaphore {
+    private readonly queue;
+    constructor(size: number);
+    /**
+     * Acquires a token from the Semaphore, allowing access to a limited resource.
+     * If no tokens are available, the call will block and wait until a token is released.
+     * Use in conjunction with the release() method to manage access to resources with limited capacity.
+     *
+     * @returns A Promise that resolves when a token is acquired.
+     */
+    acquire(): Promise<void>;
+    /**
+     * Releases a token back into the semaphore, allowing another acquire call to proceed.
+     * If there are any pending calls to acquire(), one of them will be unblocked and allowed to proceed.
+     * This method should only be called by the holder of the acquired token to ensure proper functionality
+     * and avoid unexpected behavior.
+     */
+    release(): void;
+}
+//# sourceMappingURL=semaphore.d.ts.map

package/dest/queue/semaphore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semaphore.d.ts","sourceRoot":"","sources":["../../src/queue/semaphore.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkC;gBAE5C,IAAI,EAAE,MAAM;IAIxB;;;;;;OAMG;IACU,OAAO;IAIpB;;;;;OAKG;IACI,OAAO;CAGf"}

package/dest/queue/semaphore.js

@@ -0,0 +1,26 @@
+import { FifoMemoryQueue } from './fifo_memory_queue.js';
+/**
+ * Allows the acquiring of up to `size` tokens before calls to acquire block, waiting for a call to release().
+ */ export class Semaphore {
+    queue = new FifoMemoryQueue();
+    constructor(size){
+        new Array(size).fill(true).map(()=>this.queue.put(true));
+    }
+    /**
+   * Acquires a token from the Semaphore, allowing access to a limited resource.
+   * If no tokens are available, the call will block and wait until a token is released.
+   * Use in conjunction with the release() method to manage access to resources with limited capacity.
+   *
+   * @returns A Promise that resolves when a token is acquired.
+   */ async acquire() {
+        await this.queue.get();
+    }
+    /**
+   * Releases a token back into the semaphore, allowing another acquire call to proceed.
+   * If there are any pending calls to acquire(), one of them will be unblocked and allowed to proceed.
+   * This method should only be called by the holder of the acquired token to ensure proper functionality
+   * and avoid unexpected behavior.
+   */ release() {
+        this.queue.put(true);
+    }
+}

package/dest/queue/serial_queue.d.ts

@@ -0,0 +1,49 @@
+/**
+ * A more specialized fifo queue that enqueues functions to execute. Enqueued functions are executed in serial.
+ */
+export declare class SerialQueue {
+    private readonly queue;
+    private runningPromise;
+    private started;
+    /**
+     * Initializes the execution of enqueued functions in the serial queue.
+     * Functions are executed in the order they were added to the queue, with each function
+     * waiting for the completion of the previous one before starting its execution.
+     * This method should be called once to start processing the queue.
+     */
+    start(): void;
+    /**
+     * Returns the current number of enqueued functions in the serial queue.
+     * This provides a way to check the size of the queue and monitor its progress.
+     *
+     * @returns The length of the serial queue as a number.
+     */
+    length(): number;
+    /**
+     * Cancels the processing of the remaining functions in the serial queue and resolves the running promise.
+     * Any enqueued functions that have not yet been executed will be discarded. The queue can still accept new
+     * functions after cancellation, but the previously enqueued functions will not be re-processed.
+     *
+     * @returns The running promise which resolves when the current executing function (if any) completes.
+     */
+    cancel(): Promise<void>;
+    /**
+     * Signals the SerialQueue that it should finish processing its current task and stop accepting new tasks.
+     * The returned Promise resolves when all enqueued tasks have completed execution.
+     *
+     * @returns A Promise that resolves when the queue is completely emptied and no new tasks are allowed.
+     */
+    end(): Promise<void>;
+    /**
+     * Enqueues fn for execution on the serial queue.
+     * Returns the result of the function after execution.
+     * @param fn - The function to enqueue.
+     * @returns A resolution promise. Rejects if the function does, or if the function could not be enqueued.
+     */
+    put<T>(fn: () => T | Promise<T>): Promise<Awaited<T>>;
+    /**
+     * Awaiting this ensures the queue is empty before resuming.
+     */
+    syncPoint(): Promise<void>;
+}
+//# sourceMappingURL=serial_queue.d.ts.map

package/dest/queue/serial_queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serial_queue.d.ts","sourceRoot":"","sources":["../../src/queue/serial_queue.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA8C;IACpE,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,OAAO,CAAS;IAExB;;;;;OAKG;IACI,KAAK;IAQZ;;;;;OAKG;IACI,MAAM;IAIb;;;;;;OAMG;IACI,MAAM;IAKb;;;;;OAKG;IACI,GAAG;IAKV;;;;;OAKG;IACI,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAgB5D;;OAEG;IACU,SAAS;CAGvB"}

package/dest/queue/serial_queue.js

@@ -0,0 +1,72 @@
+import { FifoMemoryQueue } from './fifo_memory_queue.js';
+/**
+ * A more specialized fifo queue that enqueues functions to execute. Enqueued functions are executed in serial.
+ */ export class SerialQueue {
+    queue = new FifoMemoryQueue();
+    runningPromise;
+    started = false;
+    /**
+   * Initializes the execution of enqueued functions in the serial queue.
+   * Functions are executed in the order they were added to the queue, with each function
+   * waiting for the completion of the previous one before starting its execution.
+   * This method should be called once to start processing the queue.
+   */ start() {
+        if (this.started) {
+            return;
+        }
+        this.runningPromise = this.queue.process((fn)=>fn());
+        this.started = true;
+    }
+    /**
+   * Returns the current number of enqueued functions in the serial queue.
+   * This provides a way to check the size of the queue and monitor its progress.
+   *
+   * @returns The length of the serial queue as a number.
+   */ length() {
+        return this.queue.length();
+    }
+    /**
+   * Cancels the processing of the remaining functions in the serial queue and resolves the running promise.
+   * Any enqueued functions that have not yet been executed will be discarded. The queue can still accept new
+   * functions after cancellation, but the previously enqueued functions will not be re-processed.
+   *
+   * @returns The running promise which resolves when the current executing function (if any) completes.
+   */ cancel() {
+        this.queue.cancel();
+        return this.runningPromise;
+    }
+    /**
+   * Signals the SerialQueue that it should finish processing its current task and stop accepting new tasks.
+   * The returned Promise resolves when all enqueued tasks have completed execution.
+   *
+   * @returns A Promise that resolves when the queue is completely emptied and no new tasks are allowed.
+   */ end() {
+        this.queue.end();
+        return this.runningPromise;
+    }
+    /**
+   * Enqueues fn for execution on the serial queue.
+   * Returns the result of the function after execution.
+   * @param fn - The function to enqueue.
+   * @returns A resolution promise. Rejects if the function does, or if the function could not be enqueued.
+   */ put(fn) {
+        return new Promise((resolve, reject)=>{
+            const accepted = this.queue.put(async ()=>{
+                try {
+                    const res = await fn();
+                    resolve(res);
+                } catch (e) {
+                    reject(e);
+                }
+            });
+            if (!accepted) {
+                reject(new Error('Could not enqueue function'));
+            }
+        });
+    }
+    /**
+   * Awaiting this ensures the queue is empty before resuming.
+   */ async syncPoint() {
+        await this.put(async ()=>{});
+    }
+}

package/dest/retry/index.d.ts

@@ -0,0 +1,44 @@
+/** An error that indicates that the operation should not be retried. */
+export declare class NoRetryError extends Error {
+}
+/**
+ * Generates a backoff sequence for retrying operations with an increasing delay.
+ * The backoff sequence follows this pattern: 1, 1, 1, 2, 4, 8, 16, 32, 64, ...
+ * This generator can be used in combination with the `retry` function to perform
+ * retries with exponential backoff and capped at 64 seconds between attempts.
+ *
+ * @returns A generator that yields the next backoff value in seconds as an integer.
+ */
+export declare function backoffGenerator(): Generator<number, void, unknown>;
+/**
+ * Generates a backoff sequence based on the array of retry intervals to use with the `retry` function.
+ * @param retries - Intervals to retry (in seconds).
+ * @returns A generator sequence.
+ */
+export declare function makeBackoff(retries: number[]): Generator<number, void, unknown>;
+/**
+ * Retry a given asynchronous function with a specific backoff strategy, until it succeeds or backoff generator ends.
+ * It logs the error and retry interval in case an error is caught. The function can be named for better log output.
+ *
+ * @param fn - The asynchronous function to be retried.
+ * @param name - The optional name of the operation, used for logging purposes.
+ * @param backoff - The optional backoff generator providing the intervals in seconds between retries. Defaults to a predefined series.
+ * @param log - Logger to use for logging.
+ * @param failSilently - Do not log errors while retrying.
+ * @returns A Promise that resolves with the successful result of the provided function, or rejects if backoff generator ends.
+ * @throws If `NoRetryError` is thrown by the `fn`, it is rethrown.
+ */
+export declare function retry<Result>(fn: () => Promise<Result>, name?: string, backoff?: Generator<number, void, unknown>, log?: import("../log/pino-logger.js").Logger, failSilently?: boolean): Promise<Result>;
+/**
+ * Retry an asynchronous function until it returns a truthy value or the specified timeout is exceeded.
+ * The function is retried periodically with a fixed interval between attempts. The operation can be named for better error messages.
+ * Will never timeout if the value is 0.
+ *
+ * @param fn - The asynchronous function to be retried, which should return a truthy value upon success or undefined otherwise.
+ * @param name - The optional name of the operation, used for generating timeout error message.
+ * @param timeout - The optional maximum time, in seconds, to keep retrying before throwing a timeout error. Defaults to 0 (never timeout).
+ * @param interval - The optional interval, in seconds, between retry attempts. Defaults to 1 second.
+ * @returns A Promise that resolves with the successful (truthy) result of the provided function, or rejects if timeout is exceeded.
+ */
+export declare function retryUntil<T>(fn: () => Promise<T | undefined>, name?: string, timeout?: number, interval?: number): Promise<NonNullable<Awaited<T>>>;
+//# sourceMappingURL=index.d.ts.map

package/dest/retry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/retry/index.ts"],"names":[],"mappings":"AAKA,wEAAwE;AACxE,qBAAa,YAAa,SAAQ,KAAK;CAAG;AAE1C;;;;;;;GAOG;AACH,wBAAiB,gBAAgB,qCAMhC;AAED;;;;GAIG;AACH,wBAAiB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,oCAI7C;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,KAAK,CAAC,MAAM,EAChC,EAAE,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,EACzB,IAAI,SAAc,EAClB,OAAO,mCAAqB,EAC5B,GAAG,yCAAmC,EACtC,YAAY,UAAQ,mBAoBrB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,EAAE,IAAI,SAAK,EAAE,OAAO,SAAI,EAAE,QAAQ,SAAI,oCAczG"}

package/dest/retry/index.js

@@ -0,0 +1,93 @@
+import { TimeoutError } from '../error/index.js';
+import { createLogger } from '../log/index.js';
+import { sleep } from '../sleep/index.js';
+import { Timer } from '../timer/index.js';
+/** An error that indicates that the operation should not be retried. */ export class NoRetryError extends Error {
+}
+/**
+ * Generates a backoff sequence for retrying operations with an increasing delay.
+ * The backoff sequence follows this pattern: 1, 1, 1, 2, 4, 8, 16, 32, 64, ...
+ * This generator can be used in combination with the `retry` function to perform
+ * retries with exponential backoff and capped at 64 seconds between attempts.
+ *
+ * @returns A generator that yields the next backoff value in seconds as an integer.
+ */ export function* backoffGenerator() {
+    const v = [
+        1,
+        1,
+        1,
+        2,
+        4,
+        8,
+        16,
+        32,
+        64
+    ];
+    let i = 0;
+    while(true){
+        yield v[Math.min(i++, v.length - 1)];
+    }
+}
+/**
+ * Generates a backoff sequence based on the array of retry intervals to use with the `retry` function.
+ * @param retries - Intervals to retry (in seconds).
+ * @returns A generator sequence.
+ */ export function* makeBackoff(retries) {
+    for (const retry of retries){
+        yield retry;
+    }
+}
+/**
+ * Retry a given asynchronous function with a specific backoff strategy, until it succeeds or backoff generator ends.
+ * It logs the error and retry interval in case an error is caught. The function can be named for better log output.
+ *
+ * @param fn - The asynchronous function to be retried.
+ * @param name - The optional name of the operation, used for logging purposes.
+ * @param backoff - The optional backoff generator providing the intervals in seconds between retries. Defaults to a predefined series.
+ * @param log - Logger to use for logging.
+ * @param failSilently - Do not log errors while retrying.
+ * @returns A Promise that resolves with the successful result of the provided function, or rejects if backoff generator ends.
+ * @throws If `NoRetryError` is thrown by the `fn`, it is rethrown.
+ */ export async function retry(fn, name = 'Operation', backoff = backoffGenerator(), log = createLogger('foundation:retry'), failSilently = false) {
+    while(true){
+        try {
+            return await fn();
+        } catch (err) {
+            if (err instanceof NoRetryError) {
+                // A special error that indicates that the operation should not be retried. Rethrow it.
+                throw err;
+            }
+            const s = backoff.next().value;
+            if (s === undefined) {
+                throw err;
+            }
+            log.verbose(`${name} failed. Will retry in ${s}s...`);
+            !failSilently && log.error(`Error while retrying ${name}`, err);
+            await sleep(s * 1000);
+            continue;
+        }
+    }
+}
+/**
+ * Retry an asynchronous function until it returns a truthy value or the specified timeout is exceeded.
+ * The function is retried periodically with a fixed interval between attempts. The operation can be named for better error messages.
+ * Will never timeout if the value is 0.
+ *
+ * @param fn - The asynchronous function to be retried, which should return a truthy value upon success or undefined otherwise.
+ * @param name - The optional name of the operation, used for generating timeout error message.
+ * @param timeout - The optional maximum time, in seconds, to keep retrying before throwing a timeout error. Defaults to 0 (never timeout).
+ * @param interval - The optional interval, in seconds, between retry attempts. Defaults to 1 second.
+ * @returns A Promise that resolves with the successful (truthy) result of the provided function, or rejects if timeout is exceeded.
+ */ export async function retryUntil(fn, name = '', timeout = 0, interval = 1) {
+    const timer = new Timer();
+    while(true){
+        const result = await fn();
+        if (result) {
+            return result;
+        }
+        await sleep(interval * 1000);
+        if (timeout && timer.s() > timeout) {
+            throw new TimeoutError(name ? `Timeout awaiting ${name}` : 'Timeout');
+        }
+    }
+}

package/dest/running-promise/index.d.ts

@@ -0,0 +1,2 @@
+export * from '../promise/running-promise.js';
+//# sourceMappingURL=index.d.ts.map

package/dest/running-promise/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/running-promise/index.ts"],"names":[],"mappings":"AAAA,cAAc,+BAA+B,CAAC"}

package/dest/running-promise/index.js

@@ -0,0 +1 @@
+export * from '../promise/running-promise.js';

package/dest/schemas/api.d.ts

@@ -0,0 +1,21 @@
+import type { z } from 'zod';
+import type { ZodNullableOptional } from './utils.js';
+type ZodParameterTypeFor<T> = undefined extends T ? ZodNullableOptional<z.ZodType<T, z.ZodTypeDef, any>> : z.ZodType<T, z.ZodTypeDef, any>;
+type ZodReturnTypeFor<T> = z.ZodType<T, z.ZodTypeDef, any>;
+type ZodMapParameterTypes<T> = T extends [] ? [] : T extends [item: infer Head, ...infer Rest] ? [ZodParameterTypeFor<Head>, ...{
+    [K in keyof Rest]: ZodParameterTypeFor<Rest[K]>;
+}] : T extends [item?: infer Head, ...infer Rest] ? [ZodNullableOptional<ZodParameterTypeFor<Head>>, ...{
+    [K in keyof Rest]: ZodParameterTypeFor<Rest[K]>;
+}] : never;
+/** Maps all functions in an interface to their schema representation. */
+export type ApiSchemaFor<T> = {
+    [K in keyof T]: T[K] extends (...args: infer Args) => Promise<infer Ret> ? z.ZodFunction<z.ZodTuple<ZodMapParameterTypes<Args>, z.ZodUnknown>, ZodReturnTypeFor<Ret>> : never;
+};
+/** Generic Api schema not bounded to a specific implementation. */
+export type ApiSchema = {
+    [key: string]: z.ZodFunction<z.ZodTuple<any, any>, z.ZodTypeAny>;
+};
+/** Return whether an API schema defines a valid function schema for a given method name. */
+export declare function schemaHasMethod(schema: ApiSchema, methodName: string): boolean;
+export {};
+//# sourceMappingURL=api.d.ts.map

package/dest/schemas/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/schemas/api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAGtD,KAAK,mBAAmB,CAAC,CAAC,IAAI,SAAS,SAAS,CAAC,GAC7C,mBAAmB,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC,GACpD,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;AAEpC,KAAK,gBAAgB,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;AAS3D,KAAK,oBAAoB,CAAC,CAAC,IAAI,CAAC,SAAS,EAAE,GACvC,EAAE,GACF,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,GAC3C,CAAC,mBAAmB,CAAC,IAAI,CAAC,EAAE,GAAG;KAAG,CAAC,IAAI,MAAM,IAAI,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;CAAE,CAAC,GACnF,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,GAC5C,CAAC,mBAAmB,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC,EAAE,GAAG;KAAG,CAAC,IAAI,MAAM,IAAI,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;CAAE,CAAC,GACxG,KAAK,CAAC;AAEV,yEAAyE;AACzE,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI;KAC3B,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,IAAI,KAAK,OAAO,CAAC,MAAM,GAAG,CAAC,GACpE,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,oBAAoB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,UAAU,CAAC,EAAE,gBAAgB,CAAC,GAAG,CAAC,CAAC,GAC1F,KAAK;CACV,CAAC;AAEF,mEAAmE;AACnE,MAAM,MAAM,SAAS,GAAG;IACtB,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC;CAClE,CAAC;AAEF,4FAA4F;AAC5F,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,WAOpE"}

package/dest/schemas/api.js

@@ -0,0 +1,3 @@
+/** Return whether an API schema defines a valid function schema for a given method name. */ export function schemaHasMethod(schema, methodName) {
+    return typeof methodName === 'string' && Object.hasOwn(schema, methodName) && typeof schema[methodName].parameters === 'function' && typeof schema[methodName].returnType === 'function';
+}

package/dest/schemas/index.d.ts

@@ -0,0 +1,6 @@
+export * from './api.js';
+export * from './parse.js';
+export * from './utils.js';
+export * from './types.js';
+export * from './schemas.js';
+//# sourceMappingURL=index.d.ts.map

package/dest/schemas/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC"}

package/dest/schemas/index.js

@@ -0,0 +1,5 @@
+export * from './api.js';
+export * from './parse.js';
+export * from './utils.js';
+export * from './types.js';
+export * from './schemas.js';

package/dest/schemas/parse.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+/** Parses the given arguments using a tuple from the provided schemas. */
+export declare function parse<T extends [] | [z.ZodTypeAny, ...z.ZodTypeAny[]]>(args: IArguments, ...schemas: T): z.AssertArray<{ [k in keyof T]: T[k] extends z.ZodType<any, any, any> ? T[k]["_output"] : never; }>;
+/**
+ * Parses the given arguments against a tuple, allowing empty for optional items.
+ * @dev Zod doesn't like tuplues with optional items. See https://github.com/colinhacks/zod/discussions/949.
+ */
+export declare function parseWithOptionals<T extends z.AnyZodTuple>(args: any[], schema: T): Promise<T['_output']>;
+//# sourceMappingURL=parse.d.ts.map

package/dest/schemas/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/schemas/parse.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,0EAA0E;AAC1E,wBAAgB,KAAK,CAAC,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC,UAAU,EAAE,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,OAAO,EAAE,CAAC,uGAEtG;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAMzG"}