@tmlmobilidade/utils 20260722.1043.2 → 20260723.1350.16

package/dist/batching/batch-writer.d.ts

@@ -49,6 +49,7 @@ export declare class BatchWriter<T> {
     private batchTimeoutTimer;
     private idleTimeoutTimer;
     private sessionTimer;
+    private flushInProgress;
     constructor(params: BatchWriterParams<T>);
     /**
      * Flushes the current batch of data.
@@ -57,6 +58,15 @@ export declare class BatchWriter<T> {
      * @param callback Optional callback to execute after the flush is complete, receiving the flushed data as a parameter
      */
     flush(callback?: (data?: T[]) => Promise<void>): Promise<void>;
+    /**
+     * Timer-triggered flush that guarantees the buffer is emptied even when a
+     * flush was already in progress. If the guarded flush() coalesced into a
+     * running flush, data written during that flush would strand on an idle tail
+     * (timers are cleared at flush start and only re-armed by the next write()).
+     * Re-flush while data remains and no timer is pending.
+     */
+    private drain;
+    private runFlush;
     /**
      * Helper method to perform insert operations with retry logic for transient errors.
      * This method will attempt to insert the data using the provided insert function,

package/dist/batching/batch-writer.js

@@ -10,6 +10,10 @@ export class BatchWriter {
     batchTimeoutTimer = null;
     idleTimeoutTimer = null;
     sessionTimer = new Timer();
+    // ponytail: single in-flight guard, not a queue. Serializes overlapping
+    // flushes (timer-triggered vs batch-full) so inserts never run concurrently
+    // and callers applying backpressure await the same promise.
+    flushInProgress = null;
     constructor(params) {
         if (!params.title)
             throw new Error('BATCHWRITER: Title is required.');
@@ -26,6 +30,35 @@ export class BatchWriter {
      * @param callback Optional callback to execute after the flush is complete, receiving the flushed data as a parameter
      */
     async flush(callback) {
+        // If a flush is already running, await it instead of starting a
+        // concurrent insert. This is the backpressure seam: the change-stream
+        // handler awaits write() -> flush() and cannot outrun the insert.
+        if (this.flushInProgress) {
+            await this.flushInProgress;
+            return;
+        }
+        this.flushInProgress = this.runFlush(callback);
+        try {
+            await this.flushInProgress;
+        }
+        finally {
+            this.flushInProgress = null;
+        }
+    }
+    /**
+     * Timer-triggered flush that guarantees the buffer is emptied even when a
+     * flush was already in progress. If the guarded flush() coalesced into a
+     * running flush, data written during that flush would strand on an idle tail
+     * (timers are cleared at flush start and only re-armed by the next write()).
+     * Re-flush while data remains and no timer is pending.
+     */
+    async drain(callback) {
+        await this.flush(callback);
+        if (this.dataBucketAlwaysAvailable.length > 0 && !this.idleTimeoutTimer && !this.batchTimeoutTimer && !this.flushInProgress) {
+            await this.flush(callback);
+        }
+    }
+    async runFlush(callback) {
         try {
             //
             const flushTimer = new Timer();
@@ -148,7 +181,7 @@ export class BatchWriter {
         if (this.params.idle_timeout && this.params.idle_timeout > 0 && !this.idleTimeoutTimer) {
             this.idleTimeoutTimer = setTimeout(async () => {
                 console.info(`BATCHWRITER [${this.params.title}]: Idle timeout reached. Flushing data...`);
-                await this.flush(flushCallback);
+                await this.drain(flushCallback);
             }, this.params.idle_timeout);
         }
         //
@@ -157,7 +190,7 @@ export class BatchWriter {
         if (this.params.batch_timeout && this.params.batch_timeout > 0 && !this.batchTimeoutTimer) {
             this.batchTimeoutTimer = setTimeout(async () => {
                 console.info(`BATCHWRITER [${this.params.title}]: Batch timeout reached. Flushing data...`);
-                await this.flush(flushCallback);
+                await this.drain(flushCallback);
             }, this.params.batch_timeout);
         }
         //

package/dist/index.d.ts

@@ -9,5 +9,7 @@ export * from './numbers/index.js';
 export * from './objects/index.js';
 export * from './permissions.js';
 export * from './run-on-interval.js';
+export * from './run-with-concurrency.js';
 export * from './singleton-proxy.js';
 export * from './validate-query-params.js';
+export * from './with-retry.js';

package/dist/index.js

@@ -9,5 +9,7 @@ export * from './numbers/index.js';
 export * from './objects/index.js';
 export * from './permissions.js';
 export * from './run-on-interval.js';
+export * from './run-with-concurrency.js';
 export * from './singleton-proxy.js';
 export * from './validate-query-params.js';
+export * from './with-retry.js';

package/dist/run-with-concurrency.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Run an async function over all items in the array, with a specific concurrency limit.
+ *
+ * @param items - The array of items to process.
+ * @param concurrency - The maximum number of concurrent executions.
+ * @param fn - Async function to run for each item. Receives the item and its index.
+ * @returns A Promise resolving to an array of PromiseSettledResult objects, preserving input order.
+ *
+ * Each result is a { status, value } or { status, reason } object, as from Promise.allSettled().
+ * The pool will never run more than `concurrency` functions at once.
+ */
+export declare function runWithConcurrency<T, R>(items: T[], concurrency: number, fn: (item: T, index: number) => Promise<R>): Promise<PromiseSettledResult<R>[]>;

package/dist/run-with-concurrency.js

@@ -0,0 +1,30 @@
+/**
+ * Run an async function over all items in the array, with a specific concurrency limit.
+ *
+ * @param items - The array of items to process.
+ * @param concurrency - The maximum number of concurrent executions.
+ * @param fn - Async function to run for each item. Receives the item and its index.
+ * @returns A Promise resolving to an array of PromiseSettledResult objects, preserving input order.
+ *
+ * Each result is a { status, value } or { status, reason } object, as from Promise.allSettled().
+ * The pool will never run more than `concurrency` functions at once.
+ */
+export async function runWithConcurrency(items, concurrency, fn) {
+    if (items.length === 0)
+        return [];
+    const results = new Array(items.length);
+    let next = 0;
+    async function worker() {
+        while (next < items.length) {
+            const index = next++;
+            try {
+                results[index] = { status: 'fulfilled', value: await fn(items[index], index) };
+            }
+            catch (reason) {
+                results[index] = { reason, status: 'rejected' };
+            }
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, () => worker()));
+    return results;
+}

package/dist/with-retry.d.ts

@@ -0,0 +1,20 @@
+export interface RetryOptions {
+    baseDelayMs?: number;
+    maxAttempts?: number;
+    maxDelayMs?: number;
+}
+/**
+ * Executes an asynchronous function with retry logic.
+ *
+ * Retries the provided async function up to the specified number of attempts, waiting with exponential backoff between each attempt.
+ *
+ * @template T The type of the resolved value.
+ * @param fn - The asynchronous function to execute.
+ * @param options - Retry options.
+ *   @param options.baseDelayMs - Initial delay in milliseconds before the first retry (default: 100).
+ *   @param options.maxAttempts - Maximum number of attempts (default: 3).
+ *   @param options.maxDelayMs  - Maximum delay between retries in milliseconds (default: 2000).
+ * @returns A Promise resolving to the function's return value.
+ * @throws The last error thrown by the retried function after exhausting all attempts.
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;

package/dist/with-retry.js

@@ -0,0 +1,39 @@
+/* * */
+/* * */
+/**
+ * Executes an asynchronous function with retry logic.
+ *
+ * Retries the provided async function up to the specified number of attempts, waiting with exponential backoff between each attempt.
+ *
+ * @template T The type of the resolved value.
+ * @param fn - The asynchronous function to execute.
+ * @param options - Retry options.
+ *   @param options.baseDelayMs - Initial delay in milliseconds before the first retry (default: 100).
+ *   @param options.maxAttempts - Maximum number of attempts (default: 3).
+ *   @param options.maxDelayMs  - Maximum delay between retries in milliseconds (default: 2000).
+ * @returns A Promise resolving to the function's return value.
+ * @throws The last error thrown by the retried function after exhausting all attempts.
+ */
+export async function withRetry(fn, options = { baseDelayMs: 100, maxAttempts: 3, maxDelayMs: 2000 }) {
+    //
+    // Last error.
+    let lastError;
+    //
+    // Helper function to sleep for the given delay.
+    const sleep = (delay) => new Promise(resolve => setTimeout(resolve, delay));
+    //
+    // Main retry loop.
+    for (let attempt = 1; attempt <= options.maxAttempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt >= options.maxAttempts)
+                throw error;
+            const delay = Math.min(options.maxDelayMs, options.baseDelayMs * 2 ** (attempt - 1));
+            await sleep(delay);
+        }
+    }
+    throw lastError;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tmlmobilidade/utils",
-	"version": "20260722.1043.2",
+	"version": "20260723.1350.16",
 	"author": {
 		"email": "iso@tmlmobilidade.pt",
 		"name": "TML-ISO"