@api3/commons 0.3.0 → 0.4.1

package/README.md

@@ -49,6 +49,8 @@ To release a new version follow these steps:
    commit it.
 3. `pnpm publish --access public` - Publish the new version to NPM.
 4. `git push --follow-tags` - Push the tagged commit upstream.
+5. Create a new [release on GitHub](https://github.com/api3dao/commons/releases). Use the "Generate release notes"
+   feature to generate the release notes from the PR titles.
 
 ## Development notes
 

package/dist/logger/async-storage.d.ts

@@ -0,0 +1,5 @@
+/// <reference types="node" />
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { LogContext } from '.';
+export declare const getAsyncLocalStorage: () => AsyncLocalStorage<LogContext>;
+//# sourceMappingURL=async-storage.d.ts.map

package/dist/logger/async-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-storage.d.ts","sourceRoot":"","sources":["../../src/logger/async-storage.ts"],"names":[],"mappings":";AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,GAAG,CAAC;AAIpC,eAAO,MAAM,oBAAoB,qCAGhC,CAAC"}

package/dist/logger/async-storage.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAsyncLocalStorage = void 0;
+const node_async_hooks_1 = require("node:async_hooks");
+let asyncLocalStorage;
+const getAsyncLocalStorage = () => {
+    if (!asyncLocalStorage)
+        asyncLocalStorage = new node_async_hooks_1.AsyncLocalStorage();
+    return asyncLocalStorage;
+};
+exports.getAsyncLocalStorage = getAsyncLocalStorage;
+//# sourceMappingURL=async-storage.js.map

package/dist/logger/async-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-storage.js","sourceRoot":"","sources":["../../src/logger/async-storage.ts"],"names":[],"mappings":";;;AAAA,uDAAqD;AAIrD,IAAI,iBAAgD,CAAC;AAE9C,MAAM,oBAAoB,GAAG,GAAG,EAAE;IACvC,IAAI,CAAC,iBAAiB;QAAE,iBAAiB,GAAG,IAAI,oCAAiB,EAAc,CAAC;IAChF,OAAO,iBAAiB,CAAC;AAC3B,CAAC,CAAC;AAHW,QAAA,oBAAoB,wBAG/B"}

package/dist/logger/index.d.ts

@@ -1,3 +1,4 @@
+import winston from 'winston';
 export declare const logFormatOptions: readonly ["json", "pretty"];
 export type LogFormat = (typeof logFormatOptions)[number];
 export declare const logLevelOptions: readonly ["debug", "info", "warn", "error"];
@@ -8,8 +9,10 @@ export interface LogConfig {
     format: LogFormat;
     minLevel: LogLevel;
 }
+export declare const createBaseLogger: (config: LogConfig) => winston.Logger;
 export type LogContext = Record<string, any>;
 export interface Logger {
+    runWithContext: <T>(context: LogContext, fn: () => T) => T;
     debug: (message: string, context?: LogContext) => void;
     info: (message: string, context?: LogContext) => void;
     warn: (message: string, context?: LogContext) => void;
@@ -18,6 +21,7 @@ export interface Logger {
         name: string;
     }) => Logger;
 }
+export declare const wrapper: (logger: winston.Logger) => Logger;
 export declare const validateLogConfig: (config: unknown) => LogConfig;
 export declare const createLogger: (config: LogConfig) => Logger;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/logger/index.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,gBAAgB,6BAA8B,CAAC;AAE5D,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1D,eAAO,MAAM,eAAe,6CAA8C,CAAC;AAE3E,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAExD,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,SAAS,CAAC;IAClB,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAwDD,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAE7C,MAAM,WAAW,MAAM;IACrB,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,KAAK,IAAI,CAAC;IACvD,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,KAAK,IAAI,CAAC;IACtD,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,KAAK,IAAI,CAAC;IACtD,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,KAAK,IAAI,CAAC,GACtD,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,UAAU,KAAK,IAAI,CAAC,CAAC;IAClE,KAAK,EAAE,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,MAAM,CAAC;CAC9C;AAsBD,eAAO,MAAM,iBAAiB,WAAY,OAAO,KAAG,SAuBnD,CAAC;AAEF,eAAO,MAAM,YAAY,WAAY,SAAS,WAG7C,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/logger/index.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAK9B,eAAO,MAAM,gBAAgB,6BAA8B,CAAC;AAE5D,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1D,eAAO,MAAM,eAAe,6CAA8C,CAAC;AAE3E,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAExD,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,SAAS,CAAC;IAClB,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAqCD,eAAO,MAAM,gBAAgB,WAAY,SAAS,mBAiBjD,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAE7C,MAAM,WAAW,MAAM;IACrB,cAAc,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;IAC3D,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,KAAK,IAAI,CAAC;IACvD,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,KAAK,IAAI,CAAC;IACtD,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,KAAK,IAAI,CAAC;IAKtD,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,KAAK,IAAI,CAAC,GACtD,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,UAAU,KAAK,IAAI,CAAC,CAAC;IAClE,KAAK,EAAE,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,MAAM,CAAC;CAC9C;AAID,eAAO,MAAM,OAAO,WAAY,cAAc,KAAG,MAyChD,CAAC;AAEF,eAAO,MAAM,iBAAiB,WAAY,OAAO,KAAG,SAuBnD,CAAC;AAEF,eAAO,MAAM,YAAY,WAAY,SAAS,WAG7C,CAAC"}

package/dist/logger/index.js

@@ -3,9 +3,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createLogger = exports.validateLogConfig = exports.logLevelOptions = exports.logFormatOptions = void 0;
+exports.createLogger = exports.validateLogConfig = exports.wrapper = exports.createBaseLogger = exports.logLevelOptions = exports.logFormatOptions = void 0;
 const winston_1 = __importDefault(require("winston"));
 const winston_console_format_1 = require("winston-console-format");
+const async_storage_1 = require("./async-storage");
 exports.logFormatOptions = ['json', 'pretty'];
 exports.logLevelOptions = ['debug', 'info', 'warn', 'error'];
 const createConsoleTransport = (config) => {
@@ -50,26 +51,52 @@ const createBaseLogger = (config) => {
         transports: [createConsoleTransport(config)],
     });
 };
+exports.createBaseLogger = createBaseLogger;
 // Winston by default merges content of `context` among the rest of the fields for the JSON format.
 // That's causing an override of fields `name` and `message` if they are present.
 const wrapper = (logger) => {
     return {
-        debug: (message, context) => logger.debug(message, context ? { context } : undefined),
-        info: (message, context) => logger.info(message, context ? { context } : undefined),
-        warn: (message, context) => logger.warn(message, context ? { context } : undefined),
+        debug: (message, localContext) => {
+            const globalContext = (0, async_storage_1.getAsyncLocalStorage)().getStore();
+            const fullContext = globalContext || localContext ? { ...globalContext, ...localContext } : undefined;
+            logger.debug(message, fullContext);
+        },
+        info: (message, localContext) => {
+            const globalContext = (0, async_storage_1.getAsyncLocalStorage)().getStore();
+            const fullContext = globalContext || localContext ? { ...globalContext, ...localContext } : undefined;
+            logger.info(message, fullContext);
+        },
+        warn: (message, localContext) => {
+            const globalContext = (0, async_storage_1.getAsyncLocalStorage)().getStore();
+            const fullContext = globalContext || localContext ? { ...globalContext, ...localContext } : undefined;
+            logger.warn(message, fullContext);
+        },
         // We need to handle both overloads of the `error` function
-        error: (message, errorOrContext, context) => {
+        error: (message, errorOrLocalContext, localContext) => {
+            const globalContext = (0, async_storage_1.getAsyncLocalStorage)().getStore();
             // eslint-disable-next-line lodash/prefer-lodash-typecheck
-            if (errorOrContext instanceof Error) {
-                logger.error(message, errorOrContext, context ? { context } : undefined);
+            if (errorOrLocalContext instanceof Error) {
+                const fullContext = globalContext || localContext ? { ...globalContext, ...localContext } : undefined;
+                logger.error(message, errorOrLocalContext, fullContext);
             }
             else {
-                logger.error(message, errorOrContext ? { context: errorOrContext } : undefined);
+                const fullContext = globalContext || errorOrLocalContext ? { ...globalContext, ...errorOrLocalContext } : undefined;
+                logger.error(message, fullContext);
             }
         },
-        child: (options) => wrapper(logger.child(options)),
+        child: (options) => (0, exports.wrapper)(logger.child(options)),
+        runWithContext: (context, fn) => {
+            const asyncStorage = (0, async_storage_1.getAsyncLocalStorage)();
+            const oldContext = asyncStorage.getStore() ?? {};
+            // From https://nodejs.org/api/async_context.html#asynclocalstoragerunstore-callback-args
+            //
+            // If the callback function throws an error, the error is thrown by run() too. The stacktrace is not impacted by
+            // this call and the context is exited.
+            return asyncStorage.run({ ...oldContext, ...context }, fn);
+        },
     };
 };
+exports.wrapper = wrapper;
 const validateLogConfig = (config) => {
     // eslint-disable-next-line lodash/prefer-lodash-typecheck
     if (typeof config !== 'object' || config === null) {
@@ -95,7 +122,7 @@ const validateLogConfig = (config) => {
 exports.validateLogConfig = validateLogConfig;
 const createLogger = (config) => {
     // Ensure that the logger configuration is valid.
-    return wrapper(createBaseLogger((0, exports.validateLogConfig)(config)));
+    return (0, exports.wrapper)((0, exports.createBaseLogger)((0, exports.validateLogConfig)(config)));
 };
 exports.createLogger = createLogger;
 //# sourceMappingURL=index.js.map

package/dist/logger/index.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@api3/commons",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "keywords": [],
   "license": "MIT",
   "engines": {

package/src/logger/async-storage.ts

@@ -0,0 +1,10 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+import type { LogContext } from '.';
+
+let asyncLocalStorage: AsyncLocalStorage<LogContext>;
+
+export const getAsyncLocalStorage = () => {
+  if (!asyncLocalStorage) asyncLocalStorage = new AsyncLocalStorage<LogContext>();
+  return asyncLocalStorage;
+};

package/src/logger/index.test.ts

@@ -0,0 +1,127 @@
+import { noop } from 'lodash';
+
+import { type LogConfig, createBaseLogger, wrapper } from '.';
+
+const createTestLogger = (
+  logConfig: LogConfig = { enabled: true, minLevel: 'debug', format: 'json', colorize: false }
+) => {
+  const baseLogger = createBaseLogger(logConfig);
+  const logger = wrapper(baseLogger);
+  jest.spyOn(baseLogger, 'debug').mockImplementation(noop as any);
+  jest.spyOn(baseLogger, 'info').mockImplementation(noop as any);
+  jest.spyOn(baseLogger, 'warn').mockImplementation(noop as any);
+  jest.spyOn(baseLogger, 'error').mockImplementation(noop as any);
+  jest.spyOn(baseLogger, 'child').mockImplementation(noop as any);
+
+  return { baseLogger, logger };
+};
+
+describe('log context', () => {
+  it('works with sync functions', () => {
+    const { baseLogger, logger } = createTestLogger();
+
+    logger.runWithContext({ requestId: 'parent' }, () => {
+      logger.debug('parent start');
+      logger.runWithContext({ requestId: 'child' }, () => {
+        logger.debug('child');
+      });
+
+      logger.debug('parent end');
+    });
+
+    expect(baseLogger.debug).toHaveBeenCalledWith('parent start', { requestId: 'parent' });
+    expect(baseLogger.debug).toHaveBeenCalledWith('child', { requestId: 'child' });
+    expect(baseLogger.debug).toHaveBeenCalledWith('parent end', { requestId: 'parent' });
+  });
+
+  it('works with async functions', async () => {
+    const { baseLogger, logger } = createTestLogger();
+
+    await logger.runWithContext({ requestId: 'parent' }, async () => {
+      logger.debug('parent start');
+      await logger.runWithContext({ requestId: 'child' }, async () => {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        logger.debug('child');
+      });
+
+      logger.debug('parent end');
+    });
+
+    expect(baseLogger.debug).toHaveBeenCalledTimes(3);
+    expect(baseLogger.debug).toHaveBeenCalledWith('parent start', { requestId: 'parent' });
+    expect(baseLogger.debug).toHaveBeenCalledWith('child', { requestId: 'child' });
+    expect(baseLogger.debug).toHaveBeenCalledWith('parent end', { requestId: 'parent' });
+  });
+
+  it('works with deeply nested functions', async () => {
+    const { baseLogger, logger } = createTestLogger();
+
+    await logger.runWithContext({ parent: true }, async () => {
+      logger.debug('parent start');
+
+      await logger.runWithContext({ A: true }, async () => {
+        logger.debug('A start');
+
+        await logger.runWithContext({ B: true }, async () => {
+          setTimeout(() => logger.debug('C'), 25);
+          setTimeout(() => logger.debug('D'), 50);
+          setTimeout(() => logger.debug('E'), 75);
+
+          await new Promise((resolve) => setTimeout(resolve, 100));
+          logger.debug('B end');
+        });
+
+        logger.debug('A end');
+      });
+
+      logger.debug('parent end');
+    });
+
+    expect(baseLogger.debug).toHaveBeenCalledTimes(8);
+    expect(baseLogger.debug).toHaveBeenCalledWith('parent start', { parent: true });
+    expect(baseLogger.debug).toHaveBeenCalledWith('A start', { parent: true, A: true });
+    expect(baseLogger.debug).toHaveBeenCalledWith('C', { parent: true, A: true, B: true });
+    expect(baseLogger.debug).toHaveBeenCalledWith('D', { parent: true, A: true, B: true });
+    expect(baseLogger.debug).toHaveBeenCalledWith('E', { parent: true, A: true, B: true });
+    expect(baseLogger.debug).toHaveBeenCalledWith('B end', { parent: true, A: true, B: true });
+    expect(baseLogger.debug).toHaveBeenCalledWith('A end', { parent: true, A: true });
+    expect(baseLogger.debug).toHaveBeenCalledWith('parent end', { parent: true });
+  });
+
+  it('throws if the sync callback function throws', () => {
+    const { logger } = createTestLogger();
+
+    expect(() =>
+      logger.runWithContext({}, () => {
+        throw new Error('some-error');
+      })
+    ).toThrow('some-error');
+  });
+
+  it('returns rejected promise if the async callback function rejects', async () => {
+    const { logger } = createTestLogger();
+
+    await expect(async () =>
+      // eslint-disable-next-line @typescript-eslint/require-await
+      logger.runWithContext({}, async () => {
+        throw new Error('some-error');
+      })
+    ).rejects.toThrow('some-error');
+  });
+
+  it('can log using all variants of logger.error', () => {
+    const { baseLogger, logger } = createTestLogger();
+
+    logger.error('only message');
+    logger.error('message and context', { requestId: 'parent' });
+    logger.error('message and error', new Error('some-error'));
+    logger.error('message, error and context', new Error('some-error'), { requestId: 'parent' });
+
+    expect(baseLogger.error).toHaveBeenNthCalledWith(1, 'only message', undefined);
+    expect(baseLogger.error).toHaveBeenNthCalledWith(2, 'message and context', { requestId: 'parent' });
+    expect(baseLogger.error).toHaveBeenNthCalledWith(3, 'message and error', new Error('some-error'), undefined);
+    expect(baseLogger.error).toHaveBeenNthCalledWith(4, 'message, error and context', new Error('some-error'), {
+      requestId: 'parent',
+    });
+  });
+});

package/src/logger/index.ts

@@ -1,6 +1,8 @@
 import winston from 'winston';
 import { consoleFormat } from 'winston-console-format';
 
+import { getAsyncLocalStorage } from './async-storage';
+
 export const logFormatOptions = ['json', 'pretty'] as const;
 
 export type LogFormat = (typeof logFormatOptions)[number];
@@ -51,7 +53,7 @@ const createConsoleTransport = (config: LogConfig) => {
   }
 };
 
-const createBaseLogger = (config: LogConfig) => {
+export const createBaseLogger = (config: LogConfig) => {
   const { enabled, minLevel } = config;
 
   return winston.createLogger({
@@ -73,9 +75,14 @@ const createBaseLogger = (config: LogConfig) => {
 export type LogContext = Record<string, any>;
 
 export interface Logger {
+  runWithContext: <T>(context: LogContext, fn: () => T) => T;
   debug: (message: string, context?: LogContext) => void;
   info: (message: string, context?: LogContext) => void;
   warn: (message: string, context?: LogContext) => void;
+  // We need to handle both overloads of the `error` function. It may a bit surprising that the variants are joined with
+  // "&" instead of "|", but it forces TypeScript to be more deliberate when resolving overloads. For functions, this
+  // means the implementation must handle all overloads, and TypeScript will look for the correct overload based on the
+  // arguments provided.
   error: ((message: string, context?: LogContext) => void) &
     ((message: string, error: Error, context?: LogContext) => void);
   child: (options: { name: string }) => Logger;
@@ -83,21 +90,46 @@ export interface Logger {
 
 // Winston by default merges content of `context` among the rest of the fields for the JSON format.
 // That's causing an override of fields `name` and `message` if they are present.
-const wrapper = (logger: Logger): Logger => {
+export const wrapper = (logger: winston.Logger): Logger => {
   return {
-    debug: (message, context) => logger.debug(message, context ? { context } : undefined),
-    info: (message, context) => logger.info(message, context ? { context } : undefined),
-    warn: (message, context) => logger.warn(message, context ? { context } : undefined),
+    debug: (message, localContext) => {
+      const globalContext = getAsyncLocalStorage().getStore();
+      const fullContext = globalContext || localContext ? { ...globalContext, ...localContext } : undefined;
+      logger.debug(message, fullContext);
+    },
+    info: (message, localContext) => {
+      const globalContext = getAsyncLocalStorage().getStore();
+      const fullContext = globalContext || localContext ? { ...globalContext, ...localContext } : undefined;
+      logger.info(message, fullContext);
+    },
+    warn: (message, localContext) => {
+      const globalContext = getAsyncLocalStorage().getStore();
+      const fullContext = globalContext || localContext ? { ...globalContext, ...localContext } : undefined;
+      logger.warn(message, fullContext);
+    },
     // We need to handle both overloads of the `error` function
-    error: (message, errorOrContext, context) => {
+    error: (message, errorOrLocalContext: Error | LogContext, localContext?: LogContext) => {
+      const globalContext = getAsyncLocalStorage().getStore();
       // eslint-disable-next-line lodash/prefer-lodash-typecheck
-      if (errorOrContext instanceof Error) {
-        logger.error(message, errorOrContext, context ? { context } : undefined);
+      if (errorOrLocalContext instanceof Error) {
+        const fullContext = globalContext || localContext ? { ...globalContext, ...localContext } : undefined;
+        logger.error(message, errorOrLocalContext, fullContext);
       } else {
-        logger.error(message, errorOrContext ? { context: errorOrContext } : undefined);
+        const fullContext =
+          globalContext || errorOrLocalContext ? { ...globalContext, ...errorOrLocalContext } : undefined;
+        logger.error(message, fullContext);
       }
     },
     child: (options) => wrapper(logger.child(options)),
+    runWithContext: (context, fn) => {
+      const asyncStorage = getAsyncLocalStorage();
+      const oldContext = asyncStorage.getStore() ?? {};
+      // From https://nodejs.org/api/async_context.html#asynclocalstoragerunstore-callback-args
+      //
+      // If the callback function throws an error, the error is thrown by run() too. The stacktrace is not impacted by
+      // this call and the context is exited.
+      return asyncStorage.run({ ...oldContext, ...context }, fn);
+    },
   } as Logger;
 };