@api3/commons 0.10.0 → 0.12.0

package/README.md

@@ -25,6 +25,8 @@ Read the documentation and sources of each module how to use it in the project.
 - [http](./src/http/README.md)
 - [logger](./src/logger/README.md)
 - [processing](./src/processing/README.md)
+- [run-in-loop](./src/run-in-loop/README.md)
+- [utils](./src/utils/README.md)
 
 ## Using the package in universal context
 

package/dist/run-in-loop/index.d.ts

@@ -0,0 +1,46 @@
+import { type Logger } from '../logger';
+export interface RunInLoopOptions {
+    /** An API3 logger instance required to execute the callback with context. */
+    logger: Logger;
+    /** Part of every message logged by the logger. */
+    logLabel?: Lowercase<string>;
+    /**
+     * Minimum time to wait between executions. E.g. value 500 means that the next execution will be started only after
+     * 500ms from the start of the previous one (even if the previous one ended after 150ms). Default is 0.
+     */
+    frequencyMs?: number;
+    /**
+     * Minimum time to wait between executions. E.g. value 50 means that next execution will start 50ms after the previous
+     * one ended. Default is 0.
+     */
+    minWaitTimeMs?: number;
+    /**
+     * Maximum time to wait between executions. E.g. value 100 means that the next execution will be started at most after
+     * 100ms from the end of the previous one. The maxWaitTime has higher precedence than minWaitTime and frequencyMs.
+     */
+    maxWaitTimeMs?: number;
+    /**
+     * Maximum time to wait for the execution to finish. If the execution exceeds this time a warning is logged.
+     */
+    softTimeoutMs?: number;
+    /**
+     * Maximum time to wait for the callback execution to finish. If the execution exceeds this time an error is logged and the
+     * execution is force-stopped.
+     */
+    hardTimeoutMs?: number;
+    /**
+     * If false, the execution will not run. This is useful for temporarily disabling the execution (e.g. change
+     * environment variable and redeploy). Note that, there is no way to stop the loop execution once started. Default is
+     * true.
+     */
+    enabled?: boolean;
+    /**
+     * The initial delay to to wait before executing the callback for the first time. Default is 0, which means the
+     * callback is executed immediately.
+     */
+    initialDelayMs?: number;
+}
+export declare const runInLoop: (fn: () => Promise<{
+    shouldContinueRunning: boolean;
+} | void>, options: RunInLoopOptions) => Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/run-in-loop/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/run-in-loop/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,WAAW,CAAC;AAGxC,MAAM,WAAW,gBAAgB;IAC/B,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,QAAQ,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IAC7B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,eAAO,MAAM,SAAS,OAChB,MAAM,OAAO,CAAC;IAAE,qBAAqB,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAAC,WACnD,gBAAgB,kBA4D1B,CAAC"}

package/dist/run-in-loop/index.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runInLoop = void 0;
+const promise_utils_1 = require("@api3/promise-utils");
+const utils_1 = require("../utils");
+const runInLoop = async (fn, options) => {
+    const { logger, logLabel, frequencyMs = 0, minWaitTimeMs = 0, maxWaitTimeMs, softTimeoutMs, hardTimeoutMs, enabled = true, initialDelayMs, } = options;
+    if (softTimeoutMs && hardTimeoutMs && hardTimeoutMs < softTimeoutMs) {
+        throw new Error('hardTimeoutMs must not be smaller than softTimeoutMs');
+    }
+    if (minWaitTimeMs && maxWaitTimeMs && maxWaitTimeMs < minWaitTimeMs) {
+        throw new Error('maxWaitTimeMs must not be smaller than minWaitTimeMs');
+    }
+    if (initialDelayMs)
+        await (0, utils_1.sleep)(initialDelayMs);
+    while (true) {
+        const executionStart = performance.now();
+        const executionId = (0, utils_1.generateRandomBytes32)();
+        if (enabled) {
+            const context = logLabel ? { executionId, label: logLabel } : { executionId };
+            const shouldContinueRunning = await logger.runWithContext(context, async () => {
+                const goRes = await (0, promise_utils_1.go)(fn, hardTimeoutMs ? { totalTimeoutMs: hardTimeoutMs } : {}); // NOTE: This is a safety net to prevent the loop from hanging
+                if (!goRes.success) {
+                    logger.error(`Unexpected runInLoop error`, goRes.error);
+                }
+                const executionTimeMs = performance.now() - executionStart;
+                if (executionTimeMs >= softTimeoutMs) {
+                    logger.warn(`Execution took longer than the interval`, { executionTimeMs });
+                }
+                else {
+                    logger.info(`Execution finished`, { executionTimeMs });
+                }
+                return goRes.data?.shouldContinueRunning === false ? false : true;
+            });
+            // Stop loop execution if the callback return value indicates it should stop
+            if (!shouldContinueRunning) {
+                break;
+            }
+        }
+        else {
+            // If the bot is disabled, we still want to run the loop to prevent the process from hanging. We also want to
+            // sleep according to the wait time logic.
+            logger.info('Loop execution is disabled.');
+        }
+        const remainingWaitTime = Math.max(frequencyMs - (performance.now() - executionStart), 0);
+        const waitTime = Math.max(minWaitTimeMs, remainingWaitTime);
+        const actualWaitTime = maxWaitTimeMs ? Math.min(waitTime, maxWaitTimeMs) : waitTime;
+        if (actualWaitTime > 0)
+            await (0, utils_1.sleep)(actualWaitTime);
+    }
+};
+exports.runInLoop = runInLoop;
+//# sourceMappingURL=index.js.map

package/dist/run-in-loop/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/run-in-loop/index.ts"],"names":[],"mappings":"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"}

package/dist/universal-index.d.ts

@@ -1,3 +1,5 @@
 export * from './blockchain-utilities';
 export * from './http';
+export * from './run-in-loop';
+export * from './utils';
 //# sourceMappingURL=universal-index.d.ts.map

package/dist/universal-index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"universal-index.d.ts","sourceRoot":"","sources":["../src/universal-index.ts"],"names":[],"mappings":"AACA,cAAc,wBAAwB,CAAC;AACvC,cAAc,QAAQ,CAAC"}
+{"version":3,"file":"universal-index.d.ts","sourceRoot":"","sources":["../src/universal-index.ts"],"names":[],"mappings":"AACA,cAAc,wBAAwB,CAAC;AACvC,cAAc,QAAQ,CAAC;AACvB,cAAc,eAAe,CAAC;AAC9B,cAAc,SAAS,CAAC"}

package/dist/universal-index.js

@@ -17,4 +17,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 // NOTE: Only export modules which work in both Node.js and browser environments.
 __exportStar(require("./blockchain-utilities"), exports);
 __exportStar(require("./http"), exports);
+__exportStar(require("./run-in-loop"), exports);
+__exportStar(require("./utils"), exports);
 //# sourceMappingURL=universal-index.js.map

package/dist/universal-index.js.map

@@ -1 +1 @@
-{"version":3,"file":"universal-index.js","sourceRoot":"","sources":["../src/universal-index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,iFAAiF;AACjF,yDAAuC;AACvC,yCAAuB"}
+{"version":3,"file":"universal-index.js","sourceRoot":"","sources":["../src/universal-index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,iFAAiF;AACjF,yDAAuC;AACvC,yCAAuB;AACvB,gDAA8B;AAC9B,0CAAwB"}

package/dist/utils/index.d.ts

@@ -0,0 +1,3 @@
+export declare const sleep: (ms: number) => Promise<unknown>;
+export declare const generateRandomBytes32: () => string;
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,KAAK,OAAc,MAAM,qBAAsD,CAAC;AAE7F,eAAO,MAAM,qBAAqB,cAEjC,CAAC"}

package/dist/utils/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateRandomBytes32 = exports.sleep = void 0;
+const ethers_1 = require("ethers");
+const sleep = async (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+exports.sleep = sleep;
+const generateRandomBytes32 = () => {
+    return ethers_1.ethers.utils.hexlify(ethers_1.ethers.utils.randomBytes(32));
+};
+exports.generateRandomBytes32 = generateRandomBytes32;
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":";;;AAAA,mCAAgC;AAEzB,MAAM,KAAK,GAAG,KAAK,EAAE,EAAU,EAAE,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAAhF,QAAA,KAAK,SAA2E;AAEtF,MAAM,qBAAqB,GAAG,GAAG,EAAE;IACxC,OAAO,eAAM,CAAC,KAAK,CAAC,OAAO,CAAC,eAAM,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC;AAC5D,CAAC,CAAC;AAFW,QAAA,qBAAqB,yBAEhC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@api3/commons",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "keywords": [],
   "license": "MIT",
   "engines": {
@@ -26,25 +26,25 @@
   "dependencies": {
     "@api3/ois": "^2.3.2",
     "@api3/promise-utils": "^0.4.0",
-    "axios": "^1.7.2",
+    "axios": "^1.7.3",
     "dotenv": "^16.4.5",
     "ethers": "^5.7.2",
     "lodash": "^4.17.21",
-    "winston": "^3.13.0",
+    "winston": "^3.13.1",
     "winston-console-format": "^1.0.8",
     "zod": "^3.23.8"
   },
   "devDependencies": {
-    "@api3/eslint-plugin-commons": "^1.0.1",
+    "@api3/eslint-plugin-commons": "^2.0.1",
     "@types/jest": "^29.5.12",
-    "@types/lodash": "^4.17.5",
-    "@types/node": "^20.14.8",
+    "@types/lodash": "^4.17.7",
+    "@types/node": "^20.14.14",
     "eslint": "^8.57.0",
-    "husky": "^9.0.11",
+    "husky": "^9.1.4",
     "jest": "^29.7.0",
-    "prettier": "^3.3.2",
-    "ts-jest": "^29.1.5",
-    "typescript": "^5.5.2"
+    "prettier": "^3.3.3",
+    "ts-jest": "^29.2.4",
+    "typescript": "^5.5.4"
   },
   "scripts": {
     "build": "tsc --project tsconfig.build.json",

package/src/run-in-loop/README.md

@@ -0,0 +1,3 @@
+# Run in loop
+
+A helper function to call a callback at a given frequency indefinitely.

package/src/run-in-loop/index.test.ts

@@ -0,0 +1,23 @@
+import { createLogger } from '../logger';
+
+import { runInLoop } from './index';
+
+describe(runInLoop.name, () => {
+  const logger = createLogger({
+    colorize: true,
+    enabled: true,
+    minLevel: 'info',
+    format: 'json',
+  });
+
+  it('stops the loop after getting the stop signal', async () => {
+    const fn = async () => ({ shouldContinueRunning: false });
+    const fnSpy = jest
+      .spyOn({ fn }, 'fn')
+      .mockImplementationOnce(async () => ({ shouldContinueRunning: true }))
+      .mockImplementationOnce(async () => ({ shouldContinueRunning: true }))
+      .mockImplementationOnce(async () => ({ shouldContinueRunning: false }));
+    await runInLoop(fnSpy as any, { logger });
+    expect(fnSpy).toHaveBeenCalledTimes(3);
+  });
+});

package/src/run-in-loop/index.ts

@@ -0,0 +1,110 @@
+import { go } from '@api3/promise-utils';
+
+import { type Logger } from '../logger';
+import { generateRandomBytes32, sleep } from '../utils';
+
+export interface RunInLoopOptions {
+  /** An API3 logger instance required to execute the callback with context. */
+  logger: Logger;
+  /** Part of every message logged by the logger. */
+  logLabel?: Lowercase<string>;
+  /**
+   * Minimum time to wait between executions. E.g. value 500 means that the next execution will be started only after
+   * 500ms from the start of the previous one (even if the previous one ended after 150ms). Default is 0.
+   */
+  frequencyMs?: number;
+  /**
+   * Minimum time to wait between executions. E.g. value 50 means that next execution will start 50ms after the previous
+   * one ended. Default is 0.
+   */
+  minWaitTimeMs?: number;
+  /**
+   * Maximum time to wait between executions. E.g. value 100 means that the next execution will be started at most after
+   * 100ms from the end of the previous one. The maxWaitTime has higher precedence than minWaitTime and frequencyMs.
+   */
+  maxWaitTimeMs?: number;
+  /**
+   * Maximum time to wait for the execution to finish. If the execution exceeds this time a warning is logged.
+   */
+  softTimeoutMs?: number;
+  /**
+   * Maximum time to wait for the callback execution to finish. If the execution exceeds this time an error is logged and the
+   * execution is force-stopped.
+   */
+  hardTimeoutMs?: number;
+  /**
+   * If false, the execution will not run. This is useful for temporarily disabling the execution (e.g. change
+   * environment variable and redeploy). Note that, there is no way to stop the loop execution once started. Default is
+   * true.
+   */
+  enabled?: boolean;
+  /**
+   * The initial delay to to wait before executing the callback for the first time. Default is 0, which means the
+   * callback is executed immediately.
+   */
+  initialDelayMs?: number;
+}
+
+export const runInLoop = async (
+  fn: () => Promise<{ shouldContinueRunning: boolean } | void>,
+  options: RunInLoopOptions
+) => {
+  const {
+    logger,
+    logLabel,
+    frequencyMs = 0,
+    minWaitTimeMs = 0,
+    maxWaitTimeMs,
+    softTimeoutMs,
+    hardTimeoutMs,
+    enabled = true,
+    initialDelayMs,
+  } = options;
+
+  if (softTimeoutMs && hardTimeoutMs && hardTimeoutMs < softTimeoutMs) {
+    throw new Error('hardTimeoutMs must not be smaller than softTimeoutMs');
+  }
+  if (minWaitTimeMs && maxWaitTimeMs && maxWaitTimeMs < minWaitTimeMs) {
+    throw new Error('maxWaitTimeMs must not be smaller than minWaitTimeMs');
+  }
+
+  if (initialDelayMs) await sleep(initialDelayMs);
+
+  while (true) {
+    const executionStart = performance.now();
+    const executionId = generateRandomBytes32();
+
+    if (enabled) {
+      const context = logLabel ? { executionId, label: logLabel } : { executionId };
+      const shouldContinueRunning = await logger.runWithContext(context, async () => {
+        const goRes = await go(fn, hardTimeoutMs ? { totalTimeoutMs: hardTimeoutMs } : {}); // NOTE: This is a safety net to prevent the loop from hanging
+        if (!goRes.success) {
+          logger.error(`Unexpected runInLoop error`, goRes.error);
+        }
+
+        const executionTimeMs = performance.now() - executionStart;
+        if (executionTimeMs >= softTimeoutMs!) {
+          logger.warn(`Execution took longer than the interval`, { executionTimeMs });
+        } else {
+          logger.info(`Execution finished`, { executionTimeMs });
+        }
+
+        return goRes.data?.shouldContinueRunning === false ? false : true;
+      });
+
+      // Stop loop execution if the callback return value indicates it should stop
+      if (!shouldContinueRunning) {
+        break;
+      }
+    } else {
+      // If the bot is disabled, we still want to run the loop to prevent the process from hanging. We also want to
+      // sleep according to the wait time logic.
+      logger.info('Loop execution is disabled.');
+    }
+
+    const remainingWaitTime = Math.max(frequencyMs - (performance.now() - executionStart), 0);
+    const waitTime = Math.max(minWaitTimeMs, remainingWaitTime);
+    const actualWaitTime = maxWaitTimeMs ? Math.min(waitTime, maxWaitTimeMs) : waitTime;
+    if (actualWaitTime > 0) await sleep(actualWaitTime);
+  }
+};

package/src/universal-index.ts

@@ -1,3 +1,5 @@
 // NOTE: Only export modules which work in both Node.js and browser environments.
 export * from './blockchain-utilities';
 export * from './http';
+export * from './run-in-loop';
+export * from './utils';

package/src/utils/README.md

@@ -0,0 +1,3 @@
+# Utils
+
+A set of helpers common for API3 applications.

package/src/utils/index.ts

@@ -0,0 +1,7 @@
+import { ethers } from 'ethers';
+
+export const sleep = async (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export const generateRandomBytes32 = () => {
+  return ethers.utils.hexlify(ethers.utils.randomBytes(32));
+};