@api3/commons 0.11.0 → 0.13.0

package/README.md

@@ -25,6 +25,7 @@ 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)
+- [release-scripts](./src/release-scripts/README.md)
 - [run-in-loop](./src/run-in-loop/README.md)
 - [utils](./src/utils/README.md)
 

package/dist/node-index.d.ts

@@ -3,4 +3,5 @@ export * from './logger';
 export * from './processing';
 export * from './config-parsing';
 export * from './config-hash';
+export * from './release-scripts';
 //# sourceMappingURL=node-index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"node-index.d.ts","sourceRoot":"","sources":["../src/node-index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC"}
+{"version":3,"file":"node-index.d.ts","sourceRoot":"","sources":["../src/node-index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC"}

package/dist/node-index.js

@@ -19,4 +19,5 @@ __exportStar(require("./logger"), exports);
 __exportStar(require("./processing"), exports);
 __exportStar(require("./config-parsing"), exports);
 __exportStar(require("./config-hash"), exports);
+__exportStar(require("./release-scripts"), exports);
 //# sourceMappingURL=node-index.js.map

package/dist/node-index.js.map

@@ -1 +1 @@
-{"version":3,"file":"node-index.js","sourceRoot":"","sources":["../src/node-index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,oDAAkC;AAClC,2CAAyB;AACzB,+CAA6B;AAC7B,mDAAiC;AACjC,gDAA8B"}
+{"version":3,"file":"node-index.js","sourceRoot":"","sources":["../src/node-index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,oDAAkC;AAClC,2CAAyB;AACzB,+CAA6B;AAC7B,mDAAiC;AACjC,gDAA8B;AAC9B,oDAAkC"}

package/dist/release-scripts/index.d.ts

@@ -0,0 +1,2 @@
+export * from './tag-and-release';
+//# sourceMappingURL=index.d.ts.map

package/dist/release-scripts/index.d.ts.map

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

package/dist/release-scripts/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./tag-and-release"), exports);
+//# sourceMappingURL=index.js.map

package/dist/release-scripts/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/release-scripts/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,oDAAkC"}

package/dist/release-scripts/tag-and-release.d.ts

@@ -0,0 +1,2 @@
+export declare const tagAndRelease: (repo: string, branch?: string) => Promise<void>;
+//# sourceMappingURL=tag-and-release.d.ts.map

package/dist/release-scripts/tag-and-release.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-and-release.d.ts","sourceRoot":"","sources":["../../src/release-scripts/tag-and-release.ts"],"names":[],"mappings":"AA4DA,eAAO,MAAM,aAAa,SAAgB,MAAM,WAAU,MAAM,kBAgC/D,CAAC"}

package/dist/release-scripts/tag-and-release.js

@@ -0,0 +1,88 @@
+"use strict";
+// ########################################################################################
+// This script uses the version defined in the root package.json to determine if a
+// new Git tag and Github release should be created. The Github release notes are
+// generated automatically using the commit information
+//
+// The following secrets are required:
+//
+//  1. GH_ACCESS_TOKEN - A "fine-grained personal access token" generated through the
+//     Github UI. It seems like these tokens are scoped to a user, rather than an
+//     organisation.
+//
+//     The following minimum permissions are required:
+//       Read - access to metadata
+//       Read & write - access to actions and code
+// #######################################################################################
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tagAndRelease = void 0;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const promise_utils_1 = require("@api3/promise-utils");
+const rest_1 = require("@octokit/rest");
+const execSyncWithErrorHandling = (command) => {
+    // eslint-disable-next-line functional/no-try-statements
+    try {
+        return (0, node_child_process_1.execSync)(command).toString();
+    }
+    catch (error) {
+        console.info(error.message);
+        console.info('STDOUT', error.stdout.toString());
+        console.info('STDERR', error.stderr.toString());
+        process.exit(1);
+    }
+};
+const createGithubRelease = async (repo, tagName) => {
+    if (!process.env.GH_ACCESS_TOKEN) {
+        console.info(`GH_ACCESS_TOKEN not set. Skipping release creation`);
+        return null;
+    }
+    // Ensure the GH_ACCESS_TOKEN secret is set on Github and has the relevant permissions
+    const octokit = new rest_1.Octokit({ auth: process.env.GH_ACCESS_TOKEN });
+    const createRelease = async () => octokit.rest.repos.createRelease({
+        owner: 'api3dao',
+        repo,
+        tag_name: tagName, // eslint-disable-line camelcase
+        generate_release_notes: true, // eslint-disable-line camelcase
+    });
+    console.info(`Creating Github release...`);
+    const goRes = await (0, promise_utils_1.go)(createRelease, { totalTimeoutMs: 15_000 });
+    if (!goRes.success) {
+        // We don't want to fail CI if the release fails to create. This can be done manually through Github's UI
+        console.info(`Unable to create Github release`);
+        console.info(goRes.error.message);
+        return null;
+    }
+    return goRes.data;
+};
+const tagAndRelease = async (repo, branch = 'main') => {
+    console.info('Ensuring working directory is clean...');
+    const gitStatus = execSyncWithErrorHandling('git status --porcelain');
+    if (gitStatus !== '')
+        throw new Error('Working directory is not clean');
+    console.info(`Ensuring we are on the ${branch} branch...`);
+    const currentBranch = execSyncWithErrorHandling('git branch --show-current');
+    if (currentBranch !== `${branch}\n`)
+        throw new Error(`Not on the ${branch} branch`);
+    console.info('Ensuring we are up to date with the remote...');
+    execSyncWithErrorHandling('git fetch');
+    const gitDiff = execSyncWithErrorHandling(`git diff origin/${branch}`);
+    if (gitDiff !== '')
+        throw new Error('Not up to date with the remote');
+    const packageJson = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, '../../package.json'), 'utf8'));
+    const { version } = packageJson;
+    console.info(`Version set to ${version}...`);
+    const gitTag = execSyncWithErrorHandling(`git tag -l '*v${version}*'`);
+    if (gitTag !== '')
+        throw new Error(`git tag v${version} already exists`);
+    console.info('Creating new annotated git tag...');
+    execSyncWithErrorHandling(`git tag -a v${version} -m "v${version}"`);
+    console.info('Pushing git tag...');
+    // NOTE: in order to push, a valid access token is expected as GH_ACCESS_TOKEN
+    execSyncWithErrorHandling(`git push origin v${version} --no-verify`);
+    await createGithubRelease(repo, `v${version}`);
+    console.info(`Done!`);
+};
+exports.tagAndRelease = tagAndRelease;
+//# sourceMappingURL=tag-and-release.js.map

package/dist/release-scripts/tag-and-release.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-and-release.js","sourceRoot":"","sources":["../../src/release-scripts/tag-and-release.ts"],"names":[],"mappings":"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"}

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

@@ -40,5 +40,7 @@ export interface RunInLoopOptions {
      */
     initialDelayMs?: number;
 }
-export declare const runInLoop: (fn: () => Promise<void>, options: RunInLoopOptions) => Promise<never>;
+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

@@ -1 +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,OAAc,MAAM,OAAO,CAAC,IAAI,CAAC,WAAW,gBAAgB,mBAoDjF,CAAC"}
+{"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

@@ -18,7 +18,7 @@ const runInLoop = async (fn, options) => {
         const executionId = (0, utils_1.generateRandomBytes32)();
         if (enabled) {
             const context = logLabel ? { executionId, label: logLabel } : { executionId };
-            await logger.runWithContext(context, async () => {
+            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);
@@ -30,7 +30,12 @@ const runInLoop = async (fn, options) => {
                 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

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/run-in-loop/index.ts"],"names":[],"mappings":";;;AAAA,uDAAyC;AAGzC,oCAAwD;AA4CjD,MAAM,SAAS,GAAG,KAAK,EAAE,EAAuB,EAAE,OAAyB,EAAE,EAAE;IACpF,MAAM,EACJ,MAAM,EACN,QAAQ,EACR,WAAW,GAAG,CAAC,EACf,aAAa,GAAG,CAAC,EACjB,aAAa,EACb,aAAa,EACb,aAAa,EACb,OAAO,GAAG,IAAI,EACd,cAAc,GACf,GAAG,OAAO,CAAC;IAEZ,IAAI,aAAa,IAAI,aAAa,IAAI,aAAa,GAAG,aAAa,EAAE,CAAC;QACpE,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;IAC1E,CAAC;IACD,IAAI,aAAa,IAAI,aAAa,IAAI,aAAa,GAAG,aAAa,EAAE,CAAC;QACpE,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;IAC1E,CAAC;IAED,IAAI,cAAc;QAAE,MAAM,IAAA,aAAK,EAAC,cAAc,CAAC,CAAC;IAEhD,OAAO,IAAI,EAAE,CAAC;QACZ,MAAM,cAAc,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QACzC,MAAM,WAAW,GAAG,IAAA,6BAAqB,GAAE,CAAC;QAE5C,IAAI,OAAO,EAAE,CAAC;YACZ,MAAM,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC;YAC9E,MAAM,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE;gBAC9C,MAAM,KAAK,GAAG,MAAM,IAAA,kBAAE,EAAC,EAAE,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,8DAA8D;gBAClJ,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;oBACnB,MAAM,CAAC,KAAK,CAAC,4BAA4B,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;gBAC1D,CAAC;gBAED,MAAM,eAAe,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,cAAc,CAAC;gBAC3D,IAAI,eAAe,IAAI,aAAc,EAAE,CAAC;oBACtC,MAAM,CAAC,IAAI,CAAC,yCAAyC,EAAE,EAAE,eAAe,EAAE,CAAC,CAAC;gBAC9E,CAAC;qBAAM,CAAC;oBACN,MAAM,CAAC,IAAI,CAAC,oBAAoB,EAAE,EAAE,eAAe,EAAE,CAAC,CAAC;gBACzD,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,6GAA6G;YAC7G,0CAA0C;YAC1C,MAAM,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAC;QAC7C,CAAC;QAED,MAAM,iBAAiB,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,GAAG,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,cAAc,CAAC,EAAE,CAAC,CAAC,CAAC;QAC1F,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,iBAAiB,CAAC,CAAC;QAC5D,MAAM,cAAc,GAAG,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;QACpF,IAAI,cAAc,GAAG,CAAC;YAAE,MAAM,IAAA,aAAK,EAAC,cAAc,CAAC,CAAC;IACtD,CAAC;AACH,CAAC,CAAC;AApDW,QAAA,SAAS,aAoDpB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/run-in-loop/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@api3/commons",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "keywords": [],
   "license": "MIT",
   "engines": {
@@ -26,11 +26,13 @@
   "dependencies": {
     "@api3/ois": "^2.3.2",
     "@api3/promise-utils": "^0.4.0",
-    "axios": "^1.7.2",
+    "@octokit/rest": "^20.1.1",
+    "@octokit/types": "^13.5.0",
+    "axios": "^1.7.7",
     "dotenv": "^16.4.5",
     "ethers": "^5.7.2",
     "lodash": "^4.17.21",
-    "winston": "^3.13.1",
+    "winston": "^3.14.2",
     "winston-console-format": "^1.0.8",
     "zod": "^3.23.8"
   },
@@ -38,12 +40,13 @@
     "@api3/eslint-plugin-commons": "^2.0.1",
     "@types/jest": "^29.5.12",
     "@types/lodash": "^4.17.7",
-    "@types/node": "^20.14.13",
+    "@types/node": "^20.16.3",
     "eslint": "^8.57.0",
-    "husky": "^9.1.3",
+    "husky": "^9.1.5",
     "jest": "^29.7.0",
     "prettier": "^3.3.3",
-    "ts-jest": "^29.2.3",
+    "ts-jest": "^29.2.5",
+    "ts-node": "^10.9.2",
     "typescript": "^5.5.4"
   },
   "scripts": {
@@ -53,6 +56,7 @@
     "eslint:fix": "pnpm run eslint:check --fix",
     "prettier:check": "prettier --check \"./**/*.{js,ts,md,json}\"",
     "prettier:fix": "prettier --write \"./**/*.{js,ts,md,json}\"",
+    "release:tag": "ts-node scripts/tag-and-release.ts",
     "test": "jest",
     "tsc": "tsc --project ."
   }

package/src/node-index.ts

@@ -3,3 +3,4 @@ export * from './logger';
 export * from './processing';
 export * from './config-parsing';
 export * from './config-hash';
+export * from './release-scripts';

package/src/release-scripts/README.md

@@ -0,0 +1,85 @@
+# Release Scripts
+
+The following scripts are exposed for use:
+
+## tagAndRelease
+
+This script creates a Git tag and Github release for a given version. It is expected to be run as part of CI and only
+once for the given version defined in `package.json`.
+
+Git tags are created with the following naming scheme: `v1.2.3`. i.e. a `v` is prepended to the version defined in
+`package.json`.
+
+### Usage
+
+```ts
+// The following environment variable is expected. See the script itself for more details
+//
+//   GH_ACCESS_TOKEN - created through the Github UI with relevant permissions to the repo. See the tag-and-release source for more information
+
+import { tagAndRelease } from '@api3/commons';
+
+await tagAndRelease('my-repo-name'); // defaults to using the 'main' branch
+await tagAndRelease('my-repo-name', 'release-branch');
+```
+
+It is advised to create a script that imports and uses the `tagAndRelease` function, setup a script in `package.json`
+and then call that in CI.
+
+```ts
+// scripts/tag-and-release.ts
+import { tagAndRelease } from '@api3/commons';
+
+const main = async () => {
+  await tagAndRelease('my-repo-name');
+};
+
+main()
+  .then(() => process.exit(0))
+  .catch((error: unknown) => {
+    console.info(error);
+    process.exitCode = 1;
+  });
+
+// package.json
+{
+  "scripts": {
+    "release:tag": "ts-node scripts/tag-and-release.ts",
+  }
+}
+```
+
+It's also recommended to setup a step in CI that checks if the Git tag already exists before executing.
+
+```yml
+# NOTE: irrelevant names and steps have been omitted such cloning, installing dependencies etc.
+tag-and-release:
+  # Only tag and release on pushes to main (or the release branch)
+  if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+  steps:
+    - name: Clone repo
+    - name: Install pnpm
+    - name: Setup Node
+    - name: Install Dependencies
+    # Configure the Git user
+    - name: Configure Git credentials
+      run: |
+        git config --global user.name '${{ secrets.GH_USER_NAME }}'
+        git config --global user.email '${{ secrets.GH_USER_EMAIL }}'
+    # Get the version as defined in package.json
+    - name: Get package.json version
+      id: get-version
+      run: echo "version=$(cat package.json | jq -r '.version' | sed 's/^/v/')" >> $GITHUB_OUTPUT
+    # Check if a Git tag already exists with the pattern: `v{version}`
+    - name: Validate tag
+      id: validate-tag
+      run:
+        test "$(git tag -l '${{ steps.get-version.outputs.version }}' | awk '{print $NF}')" = "${{
+        steps.get-version.outputs.version }}" || echo "new-tag=true" >> $GITHUB_OUTPUT
+    # Run the tag-and-release script only if the tag does *not* already exist
+    - name: Tag and release on Github
+      if: ${{ steps.validate-tag.outputs.new-tag }}
+      run: pnpm run release:tag
+      env:
+        GH_ACCESS_TOKEN: ${{ secrets.GH_ACCESS_TOKEN }}
+```

package/src/release-scripts/index.ts

@@ -0,0 +1 @@
+export * from './tag-and-release';

package/src/release-scripts/tag-and-release.ts

@@ -0,0 +1,93 @@
+// ########################################################################################
+// This script uses the version defined in the root package.json to determine if a
+// new Git tag and Github release should be created. The Github release notes are
+// generated automatically using the commit information
+//
+// The following secrets are required:
+//
+//  1. GH_ACCESS_TOKEN - A "fine-grained personal access token" generated through the
+//     Github UI. It seems like these tokens are scoped to a user, rather than an
+//     organisation.
+//
+//     The following minimum permissions are required:
+//       Read - access to metadata
+//       Read & write - access to actions and code
+// #######################################################################################
+
+import { execSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { go } from '@api3/promise-utils';
+import { Octokit } from '@octokit/rest';
+
+const execSyncWithErrorHandling = (command: string) => {
+  // eslint-disable-next-line functional/no-try-statements
+  try {
+    return execSync(command).toString();
+  } catch (error: any) {
+    console.info(error.message);
+    console.info('STDOUT', error.stdout.toString());
+    console.info('STDERR', error.stderr.toString());
+    process.exit(1);
+  }
+};
+
+const createGithubRelease = async (repo: string, tagName: `v${string}`) => {
+  if (!process.env.GH_ACCESS_TOKEN) {
+    console.info(`GH_ACCESS_TOKEN not set. Skipping release creation`);
+    return null;
+  }
+  // Ensure the GH_ACCESS_TOKEN secret is set on Github and has the relevant permissions
+  const octokit = new Octokit({ auth: process.env.GH_ACCESS_TOKEN });
+  const createRelease = async () =>
+    octokit.rest.repos.createRelease({
+      owner: 'api3dao',
+      repo,
+      tag_name: tagName, // eslint-disable-line camelcase
+      generate_release_notes: true, // eslint-disable-line camelcase
+    });
+  console.info(`Creating Github release...`);
+  const goRes = await go(createRelease, { totalTimeoutMs: 15_000 });
+  if (!goRes.success) {
+    // We don't want to fail CI if the release fails to create. This can be done manually through Github's UI
+    console.info(`Unable to create Github release`);
+    console.info(goRes.error.message);
+    return null;
+  }
+  return goRes.data;
+};
+
+export const tagAndRelease = async (repo: string, branch: string = 'main') => {
+  console.info('Ensuring working directory is clean...');
+  const gitStatus = execSyncWithErrorHandling('git status --porcelain');
+  if (gitStatus !== '') throw new Error('Working directory is not clean');
+
+  console.info(`Ensuring we are on the ${branch} branch...`);
+  const currentBranch = execSyncWithErrorHandling('git branch --show-current');
+  if (currentBranch !== `${branch}\n`) throw new Error(`Not on the ${branch} branch`);
+
+  console.info('Ensuring we are up to date with the remote...');
+  execSyncWithErrorHandling('git fetch');
+
+  const gitDiff = execSyncWithErrorHandling(`git diff origin/${branch}`);
+  if (gitDiff !== '') throw new Error('Not up to date with the remote');
+
+  const packageJson = JSON.parse(readFileSync(join(__dirname, '../../package.json'), 'utf8')) as any;
+  const { version } = packageJson;
+  console.info(`Version set to ${version}...`);
+
+  const gitTag = execSyncWithErrorHandling(`git tag -l '*v${version}*'`);
+  if (gitTag !== '') throw new Error(`git tag v${version} already exists`);
+
+  console.info('Creating new annotated git tag...');
+  execSyncWithErrorHandling(`git tag -a v${version} -m "v${version}"`);
+
+  console.info('Pushing git tag...');
+  // NOTE: in order to push, a valid access token is expected as GH_ACCESS_TOKEN
+  execSyncWithErrorHandling(`git push origin v${version} --no-verify`);
+
+  await createGithubRelease(repo, `v${version}`);
+
+  console.info(`Done!`);
+};

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

@@ -45,7 +45,10 @@ export interface RunInLoopOptions {
   initialDelayMs?: number;
 }
 
-export const runInLoop = async (fn: () => Promise<void>, options: RunInLoopOptions) => {
+export const runInLoop = async (
+  fn: () => Promise<{ shouldContinueRunning: boolean } | void>,
+  options: RunInLoopOptions
+) => {
   const {
     logger,
     logLabel,
@@ -73,7 +76,7 @@ export const runInLoop = async (fn: () => Promise<void>, options: RunInLoopOptio
 
     if (enabled) {
       const context = logLabel ? { executionId, label: logLabel } : { executionId };
-      await logger.runWithContext(context, async () => {
+      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);
@@ -85,7 +88,14 @@ export const runInLoop = async (fn: () => Promise<void>, options: RunInLoopOptio
         } 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.