@aztec/foundation 0.0.0-test.0

package/dest/noir/noir_package_config.js

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+const noirGitDependencySchema = z.object({
+    git: z.string(),
+    tag: z.string(),
+    directory: z.string().optional()
+});
+const noirLocalDependencySchema = z.object({
+    path: z.string()
+});
+const noirPackageConfigSchema = z.object({
+    package: z.object({
+        name: z.string().default(''),
+        type: z.enum([
+            'lib',
+            'contract',
+            'bin'
+        ]).default('bin'),
+        entry: z.string().optional(),
+        description: z.string().optional(),
+        authors: z.array(z.string()).optional(),
+        // eslint-disable-next-line camelcase
+        compiler_version: z.string().optional(),
+        backend: z.string().optional(),
+        license: z.string().optional()
+    }),
+    dependencies: z.record(z.union([
+        noirGitDependencySchema,
+        noirLocalDependencySchema
+    ])).default({})
+});
+/**
+ * Checks that an object is a package configuration.
+ * @param config - Config to check
+ */ export function parseNoirPackageConfig(config) {
+    return noirPackageConfigSchema.parse(config);
+}

package/dest/promise/index.d.ts

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

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

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

package/dest/promise/index.js

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

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

@@ -0,0 +1,47 @@
+import { type Logger } from '../log/pino-logger.js';
+declare const EXIT: unique symbol;
+export type ErrorHandler = (err: unknown) => typeof EXIT | void | Promise<typeof EXIT | void>;
+export declare function makeLoggingErrorHandler(logger: Logger, ...ignoredErrors: (new (...args: any[]) => Error)[]): ErrorHandler;
+/**
+ * RunningPromise is a utility class that helps manage the execution of an asynchronous function
+ * at a specified polling interval. It allows starting, stopping, and checking the status of the
+ * internally managed promise. The class also supports interrupting the polling process when stopped.
+ */
+export declare class RunningPromise {
+    private fn;
+    private logger;
+    private pollingIntervalMS;
+    private handleError;
+    private running;
+    private runningPromise;
+    private interruptibleSleep;
+    private requested;
+    static readonly EXIT: typeof EXIT;
+    constructor(fn: () => void | Promise<void>, logger?: Logger, pollingIntervalMS?: number, handleError?: ErrorHandler);
+    /**
+     * Starts the running promise.
+     */
+    start(): void;
+    /**
+     * Stops the running promise, resolves any pending interruptible sleep,
+     * and waits for the currently executing function to complete.
+     */
+    stop(): Promise<void>;
+    /**
+     * Checks if the running promise is currently active.
+     * @returns True if the promise is running.
+     */
+    isRunning(): boolean;
+    /**
+     * Triggers an immediate run of the function, bypassing the polling interval.
+     * If the function is currently running, it will be allowed to continue and then called again immediately.
+     */
+    trigger(): Promise<void>;
+    /**
+     * Updates the polling interval. The new interval will take effect after the next poll.
+     * @param pollingIntervalMS The polling interval in milliseconds.
+     */
+    setPollingIntervalMS(pollingIntervalMS: number): void;
+}
+export {};
+//# sourceMappingURL=running-promise.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"running-promise.d.ts","sourceRoot":"","sources":["../../src/promise/running-promise.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAgB,MAAM,uBAAuB,CAAC;AAIlE,QAAA,MAAM,IAAI,eAAoC,CAAC;AAE/C,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,IAAI,GAAG,IAAI,GAAG,OAAO,CAAC,OAAO,IAAI,GAAG,IAAI,CAAC,CAAC;AAE9F,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,GAAG,aAAa,EAAE,CAAC,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,KAAK,CAAC,EAAE,GAClD,YAAY,CAMd;AAED;;;;GAIG;AACH,qBAAa,cAAc;IASvB,OAAO,CAAC,EAAE;IACV,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,iBAAiB;IACzB,OAAO,CAAC,WAAW;IAXrB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,cAAc,CAAqB;IAC3C,OAAO,CAAC,kBAAkB,CAA4B;IACtD,OAAO,CAAC,SAAS,CAAqD;IAEtE,gBAAuB,IAAI,EAAE,OAAO,IAAI,CAAQ;gBAGtC,EAAE,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,EAC9B,MAAM,SAAkC,EACxC,iBAAiB,SAAQ,EACzB,WAAW,GAAE,YAA8C;IAGrE;;OAEG;IACI,KAAK;IAmCZ;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAU3B;;;OAGG;IACI,SAAS;IAIhB;;;OAGG;IACU,OAAO;IAcpB;;;OAGG;IACH,oBAAoB,CAAC,iBAAiB,EAAE,MAAM;CAG/C"}

package/dest/promise/running-promise.js

@@ -0,0 +1,110 @@
+import { createLogger } from '../log/pino-logger.js';
+import { InterruptibleSleep } from '../sleep/index.js';
+import { promiseWithResolvers } from './utils.js';
+const EXIT = Symbol.for('RunningPromise.EXIT');
+export function makeLoggingErrorHandler(logger, ...ignoredErrors) {
+    return (err)=>{
+        if (err instanceof Error && !ignoredErrors.some((ErrorType)=>err instanceof ErrorType)) {
+            logger.error('Error in running promise', err);
+        }
+    };
+}
+/**
+ * RunningPromise is a utility class that helps manage the execution of an asynchronous function
+ * at a specified polling interval. It allows starting, stopping, and checking the status of the
+ * internally managed promise. The class also supports interrupting the polling process when stopped.
+ */ export class RunningPromise {
+    fn;
+    logger;
+    pollingIntervalMS;
+    handleError;
+    running;
+    runningPromise;
+    interruptibleSleep;
+    requested;
+    static EXIT = EXIT;
+    constructor(fn, logger = createLogger('running-promise'), pollingIntervalMS = 10000, handleError = makeLoggingErrorHandler(logger)){
+        this.fn = fn;
+        this.logger = logger;
+        this.pollingIntervalMS = pollingIntervalMS;
+        this.handleError = handleError;
+        this.running = false;
+        this.runningPromise = Promise.resolve();
+        this.interruptibleSleep = new InterruptibleSleep();
+        this.requested = undefined;
+    }
+    /**
+   * Starts the running promise.
+   */ start() {
+        if (this.running) {
+            this.logger.warn(`Attempted to start running promise that was already started`);
+            return;
+        }
+        this.running = true;
+        const poll = async ()=>{
+            while(this.running){
+                const hasRequested = this.requested !== undefined;
+                try {
+                    await this.fn();
+                } catch (err) {
+                    const code = await this.handleError(err);
+                    if (code === RunningPromise.EXIT) {
+                        this.logger.warn('Error handler has requested to exit', {
+                            err
+                        });
+                        this.running = false;
+                    }
+                }
+                // If an immediate run had been requested *before* the function started running, resolve the request.
+                if (hasRequested) {
+                    this.requested.resolve();
+                    this.requested = undefined;
+                }
+                // If no immediate run was requested, sleep for the polling interval.
+                if (this.requested === undefined && this.running) {
+                    await this.interruptibleSleep.sleep(this.pollingIntervalMS);
+                }
+            }
+        };
+        this.runningPromise = poll();
+    }
+    /**
+   * Stops the running promise, resolves any pending interruptible sleep,
+   * and waits for the currently executing function to complete.
+   */ async stop() {
+        if (!this.running) {
+            this.logger.warn(`Running promise was not started`);
+            return;
+        }
+        this.running = false;
+        this.interruptibleSleep.interrupt();
+        await this.runningPromise;
+    }
+    /**
+   * Checks if the running promise is currently active.
+   * @returns True if the promise is running.
+   */ isRunning() {
+        return this.running;
+    }
+    /**
+   * Triggers an immediate run of the function, bypassing the polling interval.
+   * If the function is currently running, it will be allowed to continue and then called again immediately.
+   */ async trigger() {
+        if (!this.running) {
+            return this.fn();
+        }
+        let requested = this.requested;
+        if (!requested) {
+            requested = promiseWithResolvers();
+            this.requested = requested;
+            this.interruptibleSleep.interrupt();
+        }
+        await requested.promise;
+    }
+    /**
+   * Updates the polling interval. The new interval will take effect after the next poll.
+   * @param pollingIntervalMS The polling interval in milliseconds.
+   */ setPollingIntervalMS(pollingIntervalMS) {
+        this.pollingIntervalMS = pollingIntervalMS;
+    }
+}

package/dest/promise/utils.d.ts

@@ -0,0 +1,12 @@
+export type PromiseWithResolvers<T> = {
+    promise: Promise<T>;
+    resolve: (value: T) => void;
+    reject: (reason?: any) => void;
+};
+/**
+ * A polyfill for the Promise.withResolvers proposed API.
+ * @see https://github.com/tc39/proposal-promise-with-resolvers
+ * @returns A promise with resolvers.
+ */
+export declare function promiseWithResolvers<T>(): PromiseWithResolvers<T>;
+//# sourceMappingURL=utils.d.ts.map

package/dest/promise/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/promise/utils.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,oBAAoB,CAAC,CAAC,IAAI;IACpC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACpB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IAC5B,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,GAAG,KAAK,IAAI,CAAC;CAChC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,KAAK,oBAAoB,CAAC,CAAC,CAAC,CAiBjE"}

package/dest/promise/utils.js

@@ -0,0 +1,20 @@
+/**
+ * A polyfill for the Promise.withResolvers proposed API.
+ * @see https://github.com/tc39/proposal-promise-with-resolvers
+ * @returns A promise with resolvers.
+ */ export function promiseWithResolvers() {
+    // use ! operator to avoid TS error
+    let resolve;
+    let reject;
+    // the ES spec guarantees that the promise executor is called synchronously
+    // so the resolve and reject functions will be defined
+    const promise = new Promise((res, rej)=>{
+        resolve = res;
+        reject = rej;
+    });
+    return {
+        promise,
+        resolve,
+        reject
+    };
+}

package/dest/queue/base_memory_queue.d.ts

@@ -0,0 +1,65 @@
+export declare abstract class BaseMemoryQueue<T> {
+    private log;
+    private waiting;
+    private flushing;
+    constructor(log?: import("../log/pino-logger.js").Logger);
+    protected abstract get items(): {
+        length: number;
+        get(): T | undefined;
+        put(item: T): void;
+        clear: () => void;
+    };
+    /**
+     * Returns the current number of items in the queue.
+     * The length represents the size of the queue at the time of invocation and may change as new items are added or consumed.
+     *
+     * @returns The number of items in the queue.
+     */
+    length(): number;
+    /**
+     * Returns next item within the queue, or undefined if the queue is empty. Does not block.
+     * @returns The next item in the queue.
+     */
+    getImmediate(): T | undefined;
+    /**
+     * Returns next item within the queue, or blocks until an item has been put into the queue.
+     *
+     * If given a timeout, the promise will reject if no item is received after `timeoutSec` seconds.
+     * If the timeout is undefined (default), this call will block until an item is available or the queue is closed.
+     * If the timeout is 0 and there are no items available then the queue will immediately reject with a TimeoutError.
+     *
+     * If the queue is flushing, `null` is returned.
+     * @param timeoutSec - The timeout in seconds.
+     * @returns A result promise.
+     */
+    get(timeoutSec?: number): Promise<T | null>;
+    /**
+     * Put an item onto back of the queue.
+     * @param item - The item to enqueue.
+     * @returns A boolean indicating whether the item was successfully added to the queue.
+     */
+    put(item: T): boolean;
+    /**
+     * Once ended, no further items are added to queue. Consumers will consume remaining items within the queue.
+     * The queue is not reusable after calling `end()`.
+     * Any consumers waiting for an item receive null.
+     */
+    end(): void;
+    /**
+     * Once cancelled, all items are discarded from the queue, and no further items are added to the queue.
+     * The queue is not reusable after calling `cancel()`.
+     * Any consumers waiting for an item receive null.
+     */
+    cancel(): void;
+    /**
+     * Process items from the queue using a provided handler function.
+     * The function iterates over items in the queue, invoking the handler for each item until the queue is empty and flushing.
+     * If the handler throws an error, it will be caught and logged as 'Queue handler exception:', but the iteration will continue.
+     * The process function returns a promise that resolves when there are no more items in the queue and the queue is flushing.
+     *
+     * @param handler - A function that takes an item of type T and returns a Promise<void> after processing the item.
+     * @returns A Promise<void> that resolves when the queue is finished processing.
+     */
+    process(handler: (item: T) => Promise<void>): Promise<void>;
+}
+//# sourceMappingURL=base_memory_queue.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"base_memory_queue.d.ts","sourceRoot":"","sources":["../../src/queue/base_memory_queue.ts"],"names":[],"mappings":"AAGA,8BAAsB,eAAe,CAAC,CAAC;IAIzB,OAAO,CAAC,GAAG;IAHvB,OAAO,CAAC,OAAO,CAAoC;IACnD,OAAO,CAAC,QAAQ,CAAS;gBAEL,GAAG,yCAAyC;IAEhE,SAAS,CAAC,QAAQ,KAAK,KAAK,IAAI;QAC9B,MAAM,EAAE,MAAM,CAAC;QACf,GAAG,IAAI,CAAC,GAAG,SAAS,CAAC;QACrB,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;QACnB,KAAK,EAAE,MAAM,IAAI,CAAC;KACnB,CAAC;IAEF;;;;;OAKG;IACI,MAAM;IAIb;;;OAGG;IACI,YAAY,IAAI,CAAC,GAAG,SAAS;IAIpC;;;;;;;;;;OAUG;IACI,GAAG,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IA+BlD;;;;OAIG;IACI,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO;IAa5B;;;;OAIG;IACI,GAAG;IAKV;;;;OAIG;IACI,MAAM;IAMb;;;;;;;;OAQG;IACU,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC;CAazD"}

package/dest/queue/base_memory_queue.js

@@ -0,0 +1,116 @@
+import { TimeoutError } from '../error/index.js';
+import { createLogger } from '../log/index.js';
+export class BaseMemoryQueue {
+    log;
+    waiting;
+    flushing;
+    constructor(log = createLogger('foundation:memory_fifo')){
+        this.log = log;
+        this.waiting = [];
+        this.flushing = false;
+    }
+    /**
+   * Returns the current number of items in the queue.
+   * The length represents the size of the queue at the time of invocation and may change as new items are added or consumed.
+   *
+   * @returns The number of items in the queue.
+   */ length() {
+        return this.items.length;
+    }
+    /**
+   * Returns next item within the queue, or undefined if the queue is empty. Does not block.
+   * @returns The next item in the queue.
+   */ getImmediate() {
+        return this.items.get();
+    }
+    /**
+   * Returns next item within the queue, or blocks until an item has been put into the queue.
+   *
+   * If given a timeout, the promise will reject if no item is received after `timeoutSec` seconds.
+   * If the timeout is undefined (default), this call will block until an item is available or the queue is closed.
+   * If the timeout is 0 and there are no items available then the queue will immediately reject with a TimeoutError.
+   *
+   * If the queue is flushing, `null` is returned.
+   * @param timeoutSec - The timeout in seconds.
+   * @returns A result promise.
+   */ get(timeoutSec) {
+        if (this.items.length) {
+            return Promise.resolve(this.items.get());
+        }
+        if (this.items.length === 0 && this.flushing) {
+            return Promise.resolve(null);
+        }
+        // if the caller doesn't want to wait for an item to be available
+        // immediately reject with a Timeout error
+        if (timeoutSec === 0) {
+            return Promise.reject(new TimeoutError('Timeout getting item from queue.'));
+        }
+        return new Promise((resolve, reject)=>{
+            this.waiting.push(resolve);
+            if (timeoutSec) {
+                setTimeout(()=>{
+                    const index = this.waiting.findIndex((r)=>r === resolve);
+                    if (index > -1) {
+                        this.waiting.splice(index, 1);
+                        const err = new TimeoutError('Timeout getting item from queue.');
+                        reject(err);
+                    }
+                }, timeoutSec * 1000);
+            }
+        });
+    }
+    /**
+   * Put an item onto back of the queue.
+   * @param item - The item to enqueue.
+   * @returns A boolean indicating whether the item was successfully added to the queue.
+   */ put(item) {
+        if (this.flushing) {
+            this.log.warn('Discarding item because queue is flushing');
+            return false;
+        } else if (this.waiting.length) {
+            this.waiting.shift()(item);
+            return true;
+        } else {
+            this.items.put(item);
+            return true;
+        }
+    }
+    /**
+   * Once ended, no further items are added to queue. Consumers will consume remaining items within the queue.
+   * The queue is not reusable after calling `end()`.
+   * Any consumers waiting for an item receive null.
+   */ end() {
+        this.flushing = true;
+        this.waiting.forEach((resolve)=>resolve(null));
+    }
+    /**
+   * Once cancelled, all items are discarded from the queue, and no further items are added to the queue.
+   * The queue is not reusable after calling `cancel()`.
+   * Any consumers waiting for an item receive null.
+   */ cancel() {
+        this.flushing = true;
+        this.items.clear();
+        this.waiting.forEach((resolve)=>resolve(null));
+    }
+    /**
+   * Process items from the queue using a provided handler function.
+   * The function iterates over items in the queue, invoking the handler for each item until the queue is empty and flushing.
+   * If the handler throws an error, it will be caught and logged as 'Queue handler exception:', but the iteration will continue.
+   * The process function returns a promise that resolves when there are no more items in the queue and the queue is flushing.
+   *
+   * @param handler - A function that takes an item of type T and returns a Promise<void> after processing the item.
+   * @returns A Promise<void> that resolves when the queue is finished processing.
+   */ async process(handler) {
+        try {
+            while(true){
+                const item = await this.get();
+                if (item === null) {
+                    break;
+                }
+                await handler(item);
+            }
+        } catch (err) {
+            this.log.error('Queue handler exception', err);
+        }
+    }
+}

package/dest/queue/batch_queue.d.ts

@@ -0,0 +1,47 @@
+/**
+ * A queue that groups items into batches based on a group key.
+ *
+ * The batching algorithm is greedy, meaning that as long as consecutive items have the same group key then they will
+ * be batvched together. As soon as an item with a different group key is encountered, the old batch is flushed to the
+ * queue and a new batch is started.
+ *
+ * A batch can also be flushed to the queue if:
+ * - it reaches the selected batch size limit
+ * - or the batch duration limit is hit (in milliseconds)
+ *
+ * This ensures that batches don't grow too big and that they are flushed at a minimum rate of 1 batch every interval.
+ *
+ * The consumer side of this queue will process batches as quickly as possible.
+ */
+export declare class BatchQueue<T, K extends string | number> {
+    private processBatch;
+    private maxBatchSize;
+    private maxBatchDuration;
+    private log;
+    private container;
+    private currentBatch?;
+    private runningPromise?;
+    constructor(processBatch: (items: Array<T>, key: K) => void | Promise<void>, maxBatchSize: number, maxBatchDuration: number, log?: import("../log/pino-logger.js").Logger);
+    /**
+     * Put an item in the queue. It will be routed based on the given key
+     * @param item - The item to add
+     * @param key - The group key for this item
+     * @returns A promise that resolves or rejects when the batch this item is part of is processed
+     */
+    put(item: T, key: K): Promise<void>;
+    /**
+     * Immediately flushes the current batch, starting a new one
+     */
+    flushCurrentBatch: () => void;
+    /**
+     * Starts the queue.
+     */
+    start(): void;
+    /**
+     * Stops the queue. Any items in the queue will continue to be processed but new items won't be accepted anymore
+     * @returns A promise that resolves when the queue is drained completely
+     */
+    stop(): Promise<void>;
+    private execProcessor;
+}
+//# sourceMappingURL=batch_queue.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"batch_queue.d.ts","sourceRoot":"","sources":["../../src/queue/batch_queue.ts"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;GAcG;AACH,qBAAa,UAAU,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM;IAMhD,OAAO,CAAC,YAAY;IACpB,OAAO,CAAC,YAAY;IACpB,OAAO,CAAC,gBAAgB;IACxB,OAAO,CAAC,GAAG;IARb,OAAO,CAAC,SAAS,CAAsC;IACvD,OAAO,CAAC,YAAY,CAAC,CAAc;IACnC,OAAO,CAAC,cAAc,CAAC,CAAgB;gBAG7B,YAAY,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,EAC/D,YAAY,EAAE,MAAM,EACpB,gBAAgB,EAAE,MAAM,EACxB,GAAG,yCAAyC;IAGtD;;;;;OAKG;IACI,GAAG,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IA4B1C;;OAEG;IACI,iBAAiB,QAAO,IAAI,CAOjC;IAEF;;OAEG;IACI,KAAK;IAQZ;;;OAGG;IACI,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAY5B,OAAO,CAAC,aAAa,CAOnB;CACH"}

package/dest/queue/batch_queue.js

@@ -0,0 +1,105 @@
+import { createLogger } from '../log/pino-logger.js';
+import { promiseWithResolvers } from '../promise/utils.js';
+import { FifoMemoryQueue } from './fifo_memory_queue.js';
+/**
+ * A queue that groups items into batches based on a group key.
+ *
+ * The batching algorithm is greedy, meaning that as long as consecutive items have the same group key then they will
+ * be batvched together. As soon as an item with a different group key is encountered, the old batch is flushed to the
+ * queue and a new batch is started.
+ *
+ * A batch can also be flushed to the queue if:
+ * - it reaches the selected batch size limit
+ * - or the batch duration limit is hit (in milliseconds)
+ *
+ * This ensures that batches don't grow too big and that they are flushed at a minimum rate of 1 batch every interval.
+ *
+ * The consumer side of this queue will process batches as quickly as possible.
+ */ export class BatchQueue {
+    processBatch;
+    maxBatchSize;
+    maxBatchDuration;
+    log;
+    container;
+    currentBatch;
+    runningPromise;
+    constructor(processBatch, maxBatchSize, maxBatchDuration, log = createLogger('foundation:batch_queue')){
+        this.processBatch = processBatch;
+        this.maxBatchSize = maxBatchSize;
+        this.maxBatchDuration = maxBatchDuration;
+        this.log = log;
+        this.container = new FifoMemoryQueue();
+        this.flushCurrentBatch = ()=>{
+            if (this.currentBatch) {
+                this.log.trace('Flushing batch', {
+                    size: this.currentBatch.items.length,
+                    key: this.currentBatch.key
+                });
+                clearTimeout(this.currentBatch.enqueueTimeout);
+                this.container.put(this.currentBatch);
+                this.currentBatch = undefined;
+            }
+        };
+        this.execProcessor = async (batch)=>{
+            try {
+                await this.processBatch(batch.items, batch.key);
+                batch.deferred.resolve();
+            } catch (err) {
+                batch.deferred.reject(err);
+            }
+        };
+    }
+    /**
+   * Put an item in the queue. It will be routed based on the given key
+   * @param item - The item to add
+   * @param key - The group key for this item
+   * @returns A promise that resolves or rejects when the batch this item is part of is processed
+   */ put(item, key) {
+        if (!this.runningPromise) {
+            return Promise.reject(new Error('BatchQueue is not started'));
+        }
+        let currentBatch = this.currentBatch;
+        if (!currentBatch || currentBatch.key !== key || currentBatch.items.length >= this.maxBatchSize) {
+            this.flushCurrentBatch();
+            this.log.trace('Creating new batch', {
+                key
+            });
+            currentBatch = {
+                items: [],
+                key,
+                deferred: promiseWithResolvers(),
+                enqueueTimeout: setTimeout(this.flushCurrentBatch, this.maxBatchDuration)
+            };
+            this.currentBatch = currentBatch;
+        }
+        currentBatch.items.push(item);
+        if (currentBatch.items.length >= this.maxBatchSize) {
+            this.flushCurrentBatch();
+        }
+        return currentBatch.deferred.promise;
+    }
+    /**
+   * Immediately flushes the current batch, starting a new one
+   */ flushCurrentBatch;
+    /**
+   * Starts the queue.
+   */ start() {
+        if (this.runningPromise) {
+            return;
+        }
+        this.runningPromise = this.container.process(this.execProcessor);
+    }
+    /**
+   * Stops the queue. Any items in the queue will continue to be processed but new items won't be accepted anymore
+   * @returns A promise that resolves when the queue is drained completely
+   */ stop() {
+        const runningPromise = this.runningPromise;
+        this.runningPromise = undefined;
+        if (!runningPromise) {
+            return Promise.resolve();
+        }
+        this.container.end();
+        return runningPromise;
+    }
+    execProcessor;
+}

package/dest/queue/bounded_serial_queue.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Leverages the unbounded SerialQueue and Semaphore to create a SerialQueue that will block when putting an item
+ * if the queue size = maxQueueSize.
+ */
+export declare class BoundedSerialQueue {
+    private log;
+    private readonly queue;
+    private semaphore;
+    constructor(maxQueueSize: number, log?: import("../log/pino-logger.js").Logger);
+    /**
+     * 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(): void;
+    /**
+     * 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(): number;
+    /**
+     * 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(): Promise<void>;
+    /**
+     * 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(): Promise<void>;
+    /**
+     * 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.
+     */
+    put(fn: () => Promise<void>): Promise<void>;
+    /**
+     * 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.
+     */
+    exec<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Awaiting this ensures the queue is empty before resuming.
+     */
+    syncPoint(): Promise<void>;
+}
+//# sourceMappingURL=bounded_serial_queue.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bounded_serial_queue.d.ts","sourceRoot":"","sources":["../../src/queue/bounded_serial_queue.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,qBAAa,kBAAkB;IAIK,OAAO,CAAC,GAAG;IAH7C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,SAAS,CAAY;gBAEjB,YAAY,EAAE,MAAM,EAAU,GAAG,yCAAkD;IAI/F;;;OAGG;IACI,KAAK;IAIZ;;;;;OAKG;IACI,MAAM;IAIb;;;;;OAKG;IACI,MAAM;IAIb;;;;;;;OAOG;IACI,GAAG;IAIV;;;;;OAKG;IACU,GAAG,CAAC,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAexD;;;;OAIG;IACU,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAWtD;;OAEG;IACU,SAAS;CAGvB"}