@digitraffic/common 2023.3.27-1 → 2023.4.4-1

package/README.md

@@ -15,7 +15,7 @@ In package.json dependencies:
 In code:
 
 ```
-import {DigitrafficStack, StackConfiguration} from "@digitraffic/common/aws/infra/stack/stack";
+import {DigitrafficStack, StackConfiguration} from "@digitraffic/common/dist/aws/infra/stack/stack";
 ```
 
 ### DigitrafficStack

package/dist/aws/infra/api/handler-factory.d.ts

@@ -1,7 +1,7 @@
 import { DtLogger } from "../../runtime/dt-logger";
 import { LambdaResponse } from "../../types/lambda-response";
-export declare type LoggingHandler = (method: () => Promise<LambdaResponse>, logger: DtLogger) => Promise<LambdaResponse>;
-export declare type ErrorHandler = (error: unknown, logger: DtLogger) => LambdaResponse;
+export type LoggingHandler = (method: () => Promise<LambdaResponse>, logger: DtLogger) => Promise<LambdaResponse>;
+export type ErrorHandler = (error: unknown, logger: DtLogger) => LambdaResponse;
 /**
  * Factory class for creating lambda-handler functions.  You can set functionality to handle logging and error-handling,
  * with the defaults:

package/dist/aws/infra/api/integration.d.ts

@@ -1,7 +1,7 @@
 import { IntegrationResponse, LambdaIntegration } from "aws-cdk-lib/aws-apigateway";
 import { IFunction } from "aws-cdk-lib/aws-lambda";
 import { MediaType } from "../../types/mediatypes";
-declare type ParameterType = "path" | "querystring" | "context";
+type ParameterType = "path" | "querystring" | "context";
 interface ApiParameter {
     type: ParameterType;
     name: string;

package/dist/aws/infra/canaries/canary-parameters.d.ts

@@ -1,6 +1,6 @@
 import { Schedule } from "@aws-cdk/aws-synthetics-alpha";
 /** Optional env parameters for canary */
-declare type CanaryEnv = Record<string, string>;
+type CanaryEnv = Record<string, string>;
 export interface CanaryParameters {
     readonly name: string;
     readonly schedule?: Schedule;

package/dist/aws/infra/canaries/url-checker.d.ts

@@ -3,8 +3,8 @@ import { IncomingMessage } from "http";
 import { MediaType } from "../../types/mediatypes";
 import { FeatureCollection } from "geojson";
 export declare const API_KEY_HEADER = "x-api-key";
-declare type CheckerFunction = (Res: IncomingMessage) => Promise<void>;
-declare type JsonCheckerFunction<T> = (json: T, body: string, message: IncomingMessage) => Promise<void>;
+type CheckerFunction = (Res: IncomingMessage) => Promise<void>;
+type JsonCheckerFunction<T> = (json: T, body: string, message: IncomingMessage) => Promise<void>;
 export declare class UrlChecker {
     private readonly requestOptions;
     constructor(hostname: string, apiKey?: string);

package/dist/aws/infra/stack/lambda-configs.d.ts

@@ -3,8 +3,8 @@ import { IVpc, SubnetSelection } from "aws-cdk-lib/aws-ec2";
 import { Role } from "aws-cdk-lib/aws-iam";
 import { DigitrafficStack } from "./stack";
 import { MonitoredFunctionAlarmProps } from "./monitoredfunction";
-export declare type LambdaEnvironment = Record<string, string>;
-export declare type DBLambdaEnvironment = LambdaEnvironment & {
+export type LambdaEnvironment = Record<string, string>;
+export type DBLambdaEnvironment = LambdaEnvironment & {
     SECRET_ID?: string;
     DB_APPLICATION: string;
 };
@@ -27,7 +27,7 @@ export interface FunctionParameters {
     architecture?: Architecture;
     singleLambda?: boolean;
 }
-export declare type MonitoredFunctionParameters = FunctionParameters & {
+export type MonitoredFunctionParameters = FunctionParameters & {
     readonly durationAlarmProps?: MonitoredFunctionAlarmProps;
     readonly durationWarningProps?: MonitoredFunctionAlarmProps;
     readonly errorAlarmProps?: MonitoredFunctionAlarmProps;

package/dist/aws/infra/stack/monitoredfunction.js

@@ -11,6 +11,39 @@ const subscription_1 = require("../stack/subscription");
  * Creates a Lambda function that monitors default CloudWatch Lambda metrics with CloudWatch Alarms.
  */
 class MonitoredFunction extends aws_lambda_1.Function {
+    /**
+     * Create new MonitoredFunction.  Use topics from given DigitrafficStack.
+     *
+     * @param stack DigitrafficStack
+     * @param id Lambda construct Id
+     * @param functionProps Lambda function properties
+     * @param props Monitored function properties
+     */
+    static create(stack, id, functionProps, props) {
+        if (props === MonitoredFunction.DISABLE_ALARMS &&
+            stack.configuration.production) {
+            throw new Error(
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            `Function ${functionProps.functionName} has DISABLE_ALARMS.  Remove before installing to production or define your own properties!`);
+        }
+        return new MonitoredFunction(stack, id, functionProps, stack.alarmTopic, stack.warningTopic, stack.configuration.production, stack.configuration.trafficType, props);
+    }
+    /**
+     * Create new MonitoredFunction.  Use topics from given DigitrafficStack.  Generate names from given name and configuration shortName.
+     *
+     * For example, shortName FOO and given name update-things will create function FOO-UpdateThings and use code from lambda/update-things/update-things.ts method handler.
+     *
+     * @param stack DigitrafficStack
+     * @param name param-case name
+     * @param environment Lambda environment
+     * @param functionParameters Lambda function parameters
+     */
+    static createV2(stack, name, environment, functionParameters) {
+        const functionName = functionParameters?.functionName ??
+            `${stack.configuration.shortName}-${(0, change_case_1.pascalCase)(name)}`;
+        const functionProps = (0, lambda_configs_1.databaseFunctionProps)(stack, environment, functionName, name, functionParameters);
+        return MonitoredFunction.create(stack, functionName, functionProps, functionParameters);
+    }
     /**
      * @param scope Stack
      * @param id Lambda construct Id
@@ -48,39 +81,6 @@ class MonitoredFunction extends aws_lambda_1.Function {
             this.createAlarm(scope, this.metricThrottles(), "Throttles", "Throttles alarm", "Has throttled", trafficType, this.getAlarmActionForEnv(alarmSnsAction, warningSnsAction, production), 0, 1, 1, aws_cloudwatch_1.ComparisonOperator.GREATER_THAN_THRESHOLD, props?.throttleAlarmProps);
         }
     }
-    /**
-     * Create new MonitoredFunction.  Use topics from given DigitrafficStack.
-     *
-     * @param stack DigitrafficStack
-     * @param id Lambda construct Id
-     * @param functionProps Lambda function properties
-     * @param props Monitored function properties
-     */
-    static create(stack, id, functionProps, props) {
-        if (props === MonitoredFunction.DISABLE_ALARMS &&
-            stack.configuration.production) {
-            throw new Error(
-            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-            `Function ${functionProps.functionName} has DISABLE_ALARMS.  Remove before installing to production or define your own properties!`);
-        }
-        return new MonitoredFunction(stack, id, functionProps, stack.alarmTopic, stack.warningTopic, stack.configuration.production, stack.configuration.trafficType, props);
-    }
-    /**
-     * Create new MonitoredFunction.  Use topics from given DigitrafficStack.  Generate names from given name and configuration shortName.
-     *
-     * For example, shortName FOO and given name update-things will create function FOO-UpdateThings and use code from lambda/update-things/update-things.ts method handler.
-     *
-     * @param stack DigitrafficStack
-     * @param name param-case name
-     * @param environment Lambda environment
-     * @param functionParameters Lambda function parameters
-     */
-    static createV2(stack, name, environment, functionParameters) {
-        const functionName = functionParameters?.functionName ??
-            `${stack.configuration.shortName}-${(0, change_case_1.pascalCase)(name)}`;
-        const functionProps = (0, lambda_configs_1.databaseFunctionProps)(stack, environment, functionName, name, functionParameters);
-        return MonitoredFunction.create(stack, functionName, functionProps, functionParameters);
-    }
     createAlarm(stack, metric, alarmId, alarmName, alarmDescription, trafficType, alarmSnsAction, threshold, evaluationPeriods, datapointsToAlarm, comparisonOperator, alarmProps) {
         metric
             .createAlarm(stack, `${this.node.id}-${alarmId}`, {

package/dist/aws/runtime/dt-logger.d.ts

@@ -1,34 +1,60 @@
 /// <reference types="node" />
 import { Writable } from "stream";
-declare type LOG_LEVEL = "DEBUG" | "INFO" | "WARN" | "ERROR";
+/** Logging level */
+export type LOG_LEVEL = "DEBUG" | "INFO" | "WARN" | "ERROR";
+/**
+ * Configuration object for configuring the Digitraffic logging utility
+ * @see {@link DtLogger}
+ */
 export interface LoggerConfiguration {
+    /** Name of the lambda */
     lambdaName?: string;
+    /** The file name where the logging occurs */
     fileName?: string;
+    /** The lambda runtime environment */
     runTime?: string;
+    /** Custom end point to write the logs to */
     writeStream?: Writable;
 }
-export interface LoggableType {
-    /** name of method logging the message */
+/**
+ * CustomParams allows to add keys prefixed with `custom` keyword to be added to an
+ * object.
+ */
+export interface CustomParams {
+    /** do not log your apikey! */
+    customApikey?: never;
+    /** do not log your apikey! */
+    customApiKey?: never;
+    [key: `custom${Capitalize<string>}Count`]: number;
+    [key: `custom${Capitalize<string>}`]: string | number | boolean | Date | null | undefined;
+}
+/**
+ * Digitraffic logging object.
+ *
+ * `method` property is the only required propetry. {@link CustomParams} can be added by
+ * prefixin the property with keyword `custom`. The prefix is removed before writing to
+ * logging end point.
+ *
+ * @see {@link CustomParams}
+ */
+export interface LoggableType extends CustomParams {
+    /** Name of the method logging the message */
     method: `${string}.${string}`;
-    /** message to log, optional */
+    /** Message to log, optional */
     message?: string;
-    /** type of message, optional */
+    /** Type of message, optional */
     type?: string;
-    /** stack trace, optional */
-    stack?: string;
-    /** amount of time some operation took in milliseconds, optional */
+    /** Stack trace, optional */
+    stack?: string | undefined;
+    /** Amount of time some operation took in milliseconds, optional */
     tookMs?: number;
-    /** count of something, optional */
-    count?: number;
-    /** do not log your apikey! */
-    apikey?: never;
-    /** do not log your apikey! */
-    apiKey?: never;
-    /** any other loggable key */
-    [key: string]: string | number | boolean | Date | undefined;
+    /** Pass error object, which will be stringified before logging */
+    error?: unknown;
 }
 /**
- * Helper class for json-logging.  Logged line will include
+ * Helper class for json-logging.
+ *
+ * Logged line will include:
  * * log-level
  * * lambdaName (taken from process environment)
  * * runtime (taken from process environment)
@@ -36,48 +62,55 @@ export interface LoggableType {
  */
 export declare class DtLogger {
     readonly lambdaName?: string;
-    readonly fileName?: string;
     readonly runtime?: string;
     readonly writeStream: Writable;
+    /**
+     * Create a new Logger instance.
+     * @constructor
+     * @param {LoggerConfiguration?} [config] - Accepts configuration options @see {@link LoggerConfiguration}
+     */
     constructor(config?: LoggerConfiguration);
     /**
      * Log given message with level DEBUG.  This will not be forwarded to centralized logging system!.
      *
      * @param message anything
-     * @see log
+     * @see {@link LoggableType}
+     * @see {@link DtLogger.log}
      */
     debug(message: unknown): void;
     /**
      * Log given message with level INFO
      *
      * @param message Json-object to log
-     * @see log
+     * @see {@link LoggableType}
+     * @see {@link DtLogger.log}
      */
     info(message: LoggableType): void;
     /**
      * Log given message with level WARN
      *
      * @param message Json-object to log
-     * @see log
+     * @see {@link LoggableType}
+     * @see {@link DtLogger.log}
      */
     warn(message: LoggableType): void;
     /**
      * Log given message with level INFO
      *
      * @param message Json-object to log
-     * @see log
+     * @see {@link LoggableType}
+     * @see {@link DtLogger.log}
      */
     error(message: LoggableType): void;
     /**
-     * Log message with given log level.  If message is a json object, it will be logged as it is and if it is a string it will be wrapped into json-element with key "message".
+     * Log message with given log level.
+     *
      * Some metadata is also added to the message:
      * * runtime     - can be configured with constructor or inferred from environment
      * * lambdaName  - can be configured with constructor or inferred from environment
-     * * fileName    - can be configured with constructor
      *
-     * @param level "DEBUG", "INFO" or "ERROR"
-     * @param message Either a string or json-object
+     * @param message Json-object to log
+     * @see {@link LoggableType}
      */
-    log(level: LOG_LEVEL, message: LoggableType): void;
+    private log;
 }
-export {};

package/dist/aws/runtime/dt-logger.js

@@ -1,18 +1,28 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DtLogger = void 0;
+const lodash_1 = __importDefault(require("lodash"));
 /**
- * Helper class for json-logging.  Logged line will include
+ * Helper class for json-logging.
+ *
+ * Logged line will include:
  * * log-level
  * * lambdaName (taken from process environment)
  * * runtime (taken from process environment)
  * * the actual message (as json or as string)
  */
 class DtLogger {
+    /**
+     * Create a new Logger instance.
+     * @constructor
+     * @param {LoggerConfiguration?} [config] - Accepts configuration options @see {@link LoggerConfiguration}
+     */
     constructor(config) {
         this.lambdaName =
             config?.lambdaName ?? process.env.AWS_LAMBDA_FUNCTION_NAME;
-        this.fileName = config?.fileName;
         this.runtime = config?.runTime ?? process.env.AWS_EXECUTION_ENV;
         this.writeStream = config?.writeStream ?? process.stdout;
     }
@@ -20,13 +30,13 @@ class DtLogger {
      * Log given message with level DEBUG.  This will not be forwarded to centralized logging system!.
      *
      * @param message anything
-     * @see log
+     * @see {@link LoggableType}
+     * @see {@link DtLogger.log}
      */
     debug(message) {
         const logMessage = {
             message,
             level: "DEBUG",
-            fileName: this.fileName,
             lambdaName: this.lambdaName,
             runtime: this.runtime,
         };
@@ -36,44 +46,54 @@ class DtLogger {
      * Log given message with level INFO
      *
      * @param message Json-object to log
-     * @see log
+     * @see {@link LoggableType}
+     * @see {@link DtLogger.log}
      */
     info(message) {
-        this.log("INFO", message);
+        this.log({ ...message, level: "INFO" });
     }
     /**
      * Log given message with level WARN
      *
      * @param message Json-object to log
-     * @see log
+     * @see {@link LoggableType}
+     * @see {@link DtLogger.log}
      */
     warn(message) {
-        this.log("WARN", message);
+        this.log({ ...message, level: "WARN" });
     }
     /**
      * Log given message with level INFO
      *
      * @param message Json-object to log
-     * @see log
+     * @see {@link LoggableType}
+     * @see {@link DtLogger.log}
      */
     error(message) {
-        this.log("ERROR", message);
+        this.log({
+            ...message,
+            level: "ERROR",
+        });
     }
     /**
-     * Log message with given log level.  If message is a json object, it will be logged as it is and if it is a string it will be wrapped into json-element with key "message".
+     * Log message with given log level.
+     *
      * Some metadata is also added to the message:
      * * runtime     - can be configured with constructor or inferred from environment
      * * lambdaName  - can be configured with constructor or inferred from environment
-     * * fileName    - can be configured with constructor
      *
-     * @param level "DEBUG", "INFO" or "ERROR"
-     * @param message Either a string or json-object
+     * @param message Json-object to log
+     * @see {@link LoggableType}
      */
-    log(level, message) {
+    log(message) {
+        const error = message.error
+            ? typeof message.error === "string"
+                ? message.error
+                : JSON.stringify(message.error)
+            : undefined;
         const logMessage = {
-            ...message,
-            level,
-            fileName: message.fileName ?? this.fileName,
+            ...removePrefix("custom", message),
+            error,
             lambdaName: this.lambdaName,
             runtime: this.runtime,
         };
@@ -81,4 +101,7 @@ class DtLogger {
     }
 }
 exports.DtLogger = DtLogger;
+function removePrefix(prefix, loggable) {
+    return lodash_1.default.mapKeys(loggable, (_index, key) => key.startsWith(prefix) ? lodash_1.default.lowerFirst(key.replace(prefix, "")) : key);
+}
 //# sourceMappingURL=dt-logger.js.map

package/dist/aws/runtime/secrets/dbsecret.d.ts

@@ -11,6 +11,6 @@ export declare enum RdsSecretKey {
     host = "host",
     ro_host = "ro_host"
 }
-export declare type RdsProxySecret = Record<RdsProxySecretKey, string>;
-export declare type RdsSecret = Record<RdsSecretKey, string>;
+export type RdsProxySecret = Record<RdsProxySecretKey, string>;
+export type RdsSecret = Record<RdsSecretKey, string>;
 export declare function checkExpectedSecretKeys<Secret extends GenericSecret>(keys: string[], secret: Secret): void;

package/dist/aws/runtime/secrets/secret.d.ts

@@ -1,2 +1,2 @@
-export declare type GenericSecret = Record<string, string>;
+export type GenericSecret = Record<string, string>;
 export declare function getSecret<Secret>(secretId: string, prefix?: string): Promise<Secret>;

package/dist/database/database.d.ts

@@ -6,8 +6,8 @@ export declare enum DatabaseEnvironmentKeys {
     DB_RO_URI = "DB_RO_URI",
     DB_APPLICATION = "DB_APPLICATION"
 }
-export declare type DTDatabase = IDatabase<unknown>;
-export declare type DTTransaction = ITask<unknown>;
+export type DTDatabase = IDatabase<unknown>;
+export type DTTransaction = ITask<unknown>;
 /**
  * Creates a non-pooling database connection primarily used by Lambdas.
  *

package/dist/test/asserter.d.ts

@@ -1,7 +1,7 @@
 /**
  * A simple asserter-class for writing canaries without dependency to testing-libraries.
  */
-declare type AssertedValue = string | number;
+type AssertedValue = string | number;
 export declare abstract class Asserter {
     static assertEquals(value: AssertedValue, expected: AssertedValue): void;
     static assertTrue(value: boolean): void;

package/dist/test/httpserver.d.ts

@@ -14,4 +14,4 @@ export declare class TestHttpServer {
     close(): void;
     private debuglog;
 }
-export declare type ListenProperties = Record<string, (url?: string, data?: string) => string>;
+export type ListenProperties = Record<string, (url?: string, data?: string) => string>;

package/dist/types/either.d.ts

@@ -6,4 +6,4 @@ export interface EitherError {
     result: "error";
     message: string;
 }
-export declare type Either<T> = EitherOk<T> | EitherError;
+export type Either<T> = EitherOk<T> | EitherError;

package/dist/types/nullable.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Adds `null` as an accepted type to all properties in given type.
+ */
+export type Nullable<Obj> = {
+    [Key in keyof Obj]: Obj[Key] | null;
+};
+type RequiredKeys<Obj> = {
+    [Key in keyof Obj]-?: object extends {
+        [K in Key]: Obj[Key];
+    } ? never : Key;
+}[keyof Obj];
+type OptionalKeys<Obj> = {
+    [Key in keyof Obj]-?: object extends {
+        [K in Key]: Obj[Key];
+    } ? Key : never;
+}[keyof Obj];
+type RequiredProperties<Obj> = Pick<Obj, RequiredKeys<Obj>>;
+type OptionalProperties<Obj> = Pick<Obj, OptionalKeys<Obj>>;
+/**
+ * Adds `null` as an accepted type to all optional properties in given type. Required properties remain unchanged.
+ */
+export type NullableOptional<Obj> = RequiredProperties<Obj> & Nullable<OptionalProperties<Obj>>;
+export {};

package/dist/types/nullable.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=nullable.js.map

package/dist/types/urn.d.ts

@@ -1 +1 @@
-export declare type URN<Namespace extends string, NamespaceSpecificString extends string = ""> = `urn:${Namespace}:${NamespaceSpecificString}`;
+export type URN<Namespace extends string, NamespaceSpecificString extends string = ""> = `urn:${Namespace}:${NamespaceSpecificString}`;

package/dist/utils/logging.d.ts

@@ -1,4 +1,31 @@
-import { AxiosError } from "axios";
 import { DtLogger } from "../aws/runtime/dt-logger";
-export declare function logException(logger: DtLogger, error: Error | string, includeStack?: boolean): void;
-export declare function logException(logger: DtLogger, error: AxiosError): void;
+/**
+ * Curried version of logException.
+ *
+ * @example <caption>Using default configuration</caption>
+ * Promise.reject(x).catch(createExceptionLogger())
+ *
+ * @example <caption>Providing external logger and requiring stack</caption>
+ * import {logger} from "@digitraffic/common/dist/aws/runtime/dt-logger-default"
+ * Promise.reject(x).catch(createExceptionLogger(logger, true))
+ *
+ * @param [logger=undefined] - DtLogger to use. If not given, will create a new instance of DtLogger
+ * @param [includeStack=false] - Define if the stack trace should be logged.
+ * @param error - The error instance to be logged.
+ * @returns Logs the error without rethrowing.
+ * @see {@link logException}
+ */
+export declare function createExceptionLogger(logger?: DtLogger | undefined, includeStack?: boolean): (error: unknown) => void;
+/**
+ * Log given exception with level ERROR to given logger.
+ *
+ * Supports AxiosError, Error and string
+ *
+ * @param logger - DtLogger to use
+ * @param error - AxiosError, Error or string to log
+ * @param [includeStack=true] - Include stack in the message, default false
+ * @returns Logs the error without rethrowing
+ * @see {@link DtLogger.log}
+ * @see {@link createExceptionLogger} for a curried setup
+ */
+export declare function logException(logger: DtLogger, error: unknown, includeStack?: boolean): void;

package/dist/utils/logging.js

@@ -1,28 +1,64 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.logException = void 0;
+exports.logException = exports.createExceptionLogger = void 0;
 const axios_1 = require("axios");
+const dt_logger_1 = require("../aws/runtime/dt-logger");
 const utils_1 = require("./utils");
 const functionName = (0, utils_1.getEnvVariableOrElse)("AWS_LAMBDA_FUNCTION_NAME", "test");
+/**
+ * Curried version of logException.
+ *
+ * @example <caption>Using default configuration</caption>
+ * Promise.reject(x).catch(createExceptionLogger())
+ *
+ * @example <caption>Providing external logger and requiring stack</caption>
+ * import {logger} from "@digitraffic/common/dist/aws/runtime/dt-logger-default"
+ * Promise.reject(x).catch(createExceptionLogger(logger, true))
+ *
+ * @param [logger=undefined] - DtLogger to use. If not given, will create a new instance of DtLogger
+ * @param [includeStack=false] - Define if the stack trace should be logged.
+ * @param error - The error instance to be logged.
+ * @returns Logs the error without rethrowing.
+ * @see {@link logException}
+ */
+function createExceptionLogger(logger = undefined, includeStack = false) {
+    let thatLogger;
+    if (logger) {
+        thatLogger = logger;
+    }
+    else {
+        thatLogger = new dt_logger_1.DtLogger();
+    }
+    return (error) => {
+        logException(thatLogger, error, includeStack);
+    };
+}
+exports.createExceptionLogger = createExceptionLogger;
 /**
  * Log given exception with level ERROR to given logger.
  *
  * Supports AxiosError, Error and string
  *
- * @param logger DtLogger to use
- * @param error AxiosError, Error or string to log
- * @param includeStack Include stack in the message, default false
- * @see log
+ * @param logger - DtLogger to use
+ * @param error - AxiosError, Error or string to log
+ * @param [includeStack=true] - Include stack in the message, default false
+ * @returns Logs the error without rethrowing
+ * @see {@link DtLogger.log}
+ * @see {@link createExceptionLogger} for a curried setup
  */
 function logException(logger, error, includeStack = false) {
-    const message = error instanceof Error ? error.message : error;
+    const message = error instanceof Error
+        ? error.message
+        : typeof error === "string"
+            ? error
+            : JSON.stringify(error);
     const stack = error instanceof Error && includeStack ? error.stack : undefined;
-    const code = error instanceof axios_1.AxiosError ? error.code : undefined;
+    const customCode = error instanceof axios_1.AxiosError ? error.code : undefined;
     logger.error({
         type: "Error",
         method: `${functionName}.logException`,
         message,
-        code,
+        customCode,
         stack,
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digitraffic/common",
-  "version": "2023.3.27-1",
+  "version": "2023.4.4-1",
   "description": "",
   "repository": {
     "type": "git",
@@ -35,19 +35,20 @@
     "@types/aws-lambda": "^8.10.114",
     "@types/geojson": "^7946.0.10",
     "@types/jest": "^29.5.0",
+    "@types/lodash": "^4.14.192",
     "@types/node": "^18.15.10",
     "@types/ramda": "^0.28.23",
     "@types/sinon": "^10.0.13",
-    "@typescript-eslint/eslint-plugin": "^5.56.0",
+    "@typescript-eslint/eslint-plugin": "~5.56.0",
     "@typescript-eslint/parser": "^5.56.0",
-    "aws-cdk-lib": "2.70.0",
+    "aws-cdk-lib": "^2.70.0",
     "aws-sdk": "^2.1343.0",
     "axios": "^1.3.4",
     "change-case": "^4.1.2",
     "constructs": "^10.1.292",
     "eslint": "~8.36.0",
     "eslint-config-prettier": "^8.8.0",
-    "eslint-plugin-deprecation": "1.3.3",
+    "eslint-plugin-deprecation": "~1.3.3",
     "geojson-validation": "^1.0.2",
     "husky": "^8.0.3",
     "jest": "^29.5.0",
@@ -62,7 +63,7 @@
     "rimraf": "^4.1.0",
     "sinon": "^15.0.3",
     "ts-jest": "^29.0.5",
-    "typescript": "~4.8.4"
+    "typescript": "~4.9.5"
   },
   "externals": [
     "aws-sdk",
@@ -71,12 +72,16 @@
   "lint-staged": {
     "*.{js,ts,css,md,yml,yaml,json}": "prettier --write"
   },
+  "dependencies": {
+    "lodash": "^4.17.21"
+  },
   "scripts": {
     "build": "tsc",
     "lint": "eslint --cache .",
     "eslint-report": "eslint . --format html",
     "ci:eslint-report": "eslint . --format html -o report.html",
     "clean": "rimraf dist output",
-    "test": "jest --detectOpenHandles --forceExit --coverage --coverageDirectory=output/coverage/jest"
+    "test": "jest --detectOpenHandles --forceExit --coverage --coverageDirectory=output/coverage/jest",
+    "test:watch": "jest --detectOpenHandles --forceExit --coverage --coverageDirectory=output/coverage/jest --watch"
   }
 }

package/src/aws/runtime/dt-logger.ts

@@ -1,37 +1,76 @@
 import { Writable } from "stream";
+import _ from "lodash";
 
-type LOG_LEVEL = "DEBUG" | "INFO" | "WARN" | "ERROR";
+/** Logging level */
+export type LOG_LEVEL = "DEBUG" | "INFO" | "WARN" | "ERROR";
 
+/**
+ * Configuration object for configuring the Digitraffic logging utility
+ * @see {@link DtLogger}
+ */
 export interface LoggerConfiguration {
+    /** Name of the lambda */
     lambdaName?: string;
+    /** The file name where the logging occurs */
     fileName?: string;
+    /** The lambda runtime environment */
     runTime?: string;
+    /** Custom end point to write the logs to */
     writeStream?: Writable;
 }
 
-export interface LoggableType {
-    /** name of method logging the message */
+interface LoggableTypeInternal extends LoggableType {
+    level: LOG_LEVEL;
+}
+
+/**
+ * CustomParams allows to add keys prefixed with `custom` keyword to be added to an
+ * object.
+ */
+export interface CustomParams {
+    /** do not log your apikey! */
+    customApikey?: never;
+    /** do not log your apikey! */
+    customApiKey?: never;
+    [key: `custom${Capitalize<string>}Count`]: number;
+
+    [key: `custom${Capitalize<string>}`]:
+        | string
+        | number
+        | boolean
+        | Date
+        | null
+        | undefined;
+}
+
+/**
+ * Digitraffic logging object.
+ *
+ * `method` property is the only required propetry. {@link CustomParams} can be added by
+ * prefixin the property with keyword `custom`. The prefix is removed before writing to
+ * logging end point.
+ *
+ * @see {@link CustomParams}
+ */
+export interface LoggableType extends CustomParams {
+    /** Name of the method logging the message */
     method: `${string}.${string}`;
-    /** message to log, optional */
+    /** Message to log, optional */
     message?: string;
-    /** type of message, optional */
+    /** Type of message, optional */
     type?: string;
-    /** stack trace, optional */
-    stack?: string;
-    /** amount of time some operation took in milliseconds, optional */
+    /** Stack trace, optional */
+    stack?: string | undefined;
+    /** Amount of time some operation took in milliseconds, optional */
     tookMs?: number;
-    /** count of something, optional */
-    count?: number;
-    /** do not log your apikey! */
-    apikey?: never;
-    /** do not log your apikey! */
-    apiKey?: never;
-    /** any other loggable key */
-    [key: string]: string | number | boolean | Date | undefined;
+    /** Pass error object, which will be stringified before logging */
+    error?: unknown;
 }
 
 /**
- * Helper class for json-logging.  Logged line will include
+ * Helper class for json-logging.
+ *
+ * Logged line will include:
  * * log-level
  * * lambdaName (taken from process environment)
  * * runtime (taken from process environment)
@@ -39,15 +78,18 @@ export interface LoggableType {
  */
 export class DtLogger {
     readonly lambdaName?: string;
-    readonly fileName?: string;
     readonly runtime?: string;
 
     readonly writeStream: Writable;
 
+    /**
+     * Create a new Logger instance.
+     * @constructor
+     * @param {LoggerConfiguration?} [config] - Accepts configuration options @see {@link LoggerConfiguration}
+     */
     constructor(config?: LoggerConfiguration) {
         this.lambdaName =
             config?.lambdaName ?? process.env.AWS_LAMBDA_FUNCTION_NAME;
-        this.fileName = config?.fileName;
         this.runtime = config?.runTime ?? process.env.AWS_EXECUTION_ENV;
         this.writeStream = config?.writeStream ?? process.stdout;
     }
@@ -56,13 +98,13 @@ export class DtLogger {
      * Log given message with level DEBUG.  This will not be forwarded to centralized logging system!.
      *
      * @param message anything
-     * @see log
+     * @see {@link LoggableType}
+     * @see {@link DtLogger.log}
      */
     debug(message: unknown): void {
         const logMessage = {
             message,
             level: "DEBUG",
-            fileName: this.fileName,
             lambdaName: this.lambdaName,
             runtime: this.runtime,
         };
@@ -74,46 +116,57 @@ export class DtLogger {
      * Log given message with level INFO
      *
      * @param message Json-object to log
-     * @see log
+     * @see {@link LoggableType}
+     * @see {@link DtLogger.log}
      */
     info(message: LoggableType): void {
-        this.log("INFO", message);
+        this.log({ ...message, level: "INFO" });
     }
 
     /**
      * Log given message with level WARN
      *
      * @param message Json-object to log
-     * @see log
+     * @see {@link LoggableType}
+     * @see {@link DtLogger.log}
      */
     warn(message: LoggableType): void {
-        this.log("WARN", message);
+        this.log({ ...message, level: "WARN" });
     }
     /**
      * Log given message with level INFO
      *
      * @param message Json-object to log
-     * @see log
+     * @see {@link LoggableType}
+     * @see {@link DtLogger.log}
      */
     error(message: LoggableType): void {
-        this.log("ERROR", message);
+        this.log({
+            ...message,
+            level: "ERROR",
+        });
     }
 
     /**
-     * Log message with given log level.  If message is a json object, it will be logged as it is and if it is a string it will be wrapped into json-element with key "message".
+     * Log message with given log level.
+     *
      * Some metadata is also added to the message:
      * * runtime     - can be configured with constructor or inferred from environment
      * * lambdaName  - can be configured with constructor or inferred from environment
-     * * fileName    - can be configured with constructor
      *
-     * @param level "DEBUG", "INFO" or "ERROR"
-     * @param message Either a string or json-object
+     * @param message Json-object to log
+     * @see {@link LoggableType}
      */
-    log(level: LOG_LEVEL, message: LoggableType): void {
+    private log(message: LoggableTypeInternal): void {
+        const error = message.error
+            ? typeof message.error === "string"
+                ? message.error
+                : JSON.stringify(message.error)
+            : undefined;
+
         const logMessage = {
-            ...message,
-            level,
-            fileName: message.fileName ?? this.fileName,
+            ...removePrefix("custom", message),
+            error,
             lambdaName: this.lambdaName,
             runtime: this.runtime,
         };
@@ -121,3 +174,9 @@ export class DtLogger {
         this.writeStream.write(JSON.stringify(logMessage) + "\n");
     }
 }
+
+function removePrefix(prefix: string, loggable: LoggableType) {
+    return _.mapKeys(loggable, (_index, key: string) =>
+        key.startsWith(prefix) ? _.lowerFirst(key.replace(prefix, "")) : key
+    );
+}

package/src/types/nullable.ts

@@ -0,0 +1,19 @@
+/**
+ * Adds `null` as an accepted type to all properties in given type.
+ */
+export type Nullable<Obj> = { [Key in keyof Obj]: Obj[Key] | null };
+
+type RequiredKeys<Obj> = {
+    [Key in keyof Obj]-?: object extends { [K in Key]: Obj[Key] } ? never : Key;
+}[keyof Obj];
+type OptionalKeys<Obj> = {
+    [Key in keyof Obj]-?: object extends { [K in Key]: Obj[Key] } ? Key : never;
+}[keyof Obj];
+type RequiredProperties<Obj> = Pick<Obj, RequiredKeys<Obj>>;
+type OptionalProperties<Obj> = Pick<Obj, OptionalKeys<Obj>>;
+
+/**
+ * Adds `null` as an accepted type to all optional properties in given type. Required properties remain unchanged.
+ */
+export type NullableOptional<Obj> = RequiredProperties<Obj> &
+    Nullable<OptionalProperties<Obj>>;

package/src/utils/logging.ts

@@ -4,38 +4,72 @@ import { getEnvVariableOrElse } from "./utils";
 
 const functionName = getEnvVariableOrElse("AWS_LAMBDA_FUNCTION_NAME", "test");
 
-export function logException(
-    logger: DtLogger,
-    error: Error | string,
-    includeStack?: boolean
-): void;
-export function logException(logger: DtLogger, error: AxiosError): void;
+/**
+ * Curried version of logException.
+ *
+ * @example <caption>Using default configuration</caption>
+ * Promise.reject(x).catch(createExceptionLogger())
+ *
+ * @example <caption>Providing external logger and requiring stack</caption>
+ * import {logger} from "@digitraffic/common/dist/aws/runtime/dt-logger-default"
+ * Promise.reject(x).catch(createExceptionLogger(logger, true))
+ *
+ * @param [logger=undefined] - DtLogger to use. If not given, will create a new instance of DtLogger
+ * @param [includeStack=false] - Define if the stack trace should be logged.
+ * @param error - The error instance to be logged.
+ * @returns Logs the error without rethrowing.
+ * @see {@link logException}
+ */
+export function createExceptionLogger(
+    logger: DtLogger | undefined = undefined,
+    includeStack = false
+) {
+    let thatLogger: DtLogger;
+    if (logger) {
+        thatLogger = logger;
+    } else {
+        thatLogger = new DtLogger();
+    }
+
+    return (error: unknown) => {
+        logException(thatLogger, error, includeStack);
+    };
+}
 
 /**
  * Log given exception with level ERROR to given logger.
  *
  * Supports AxiosError, Error and string
  *
- * @param logger DtLogger to use
- * @param error AxiosError, Error or string to log
- * @param includeStack Include stack in the message, default false
- * @see log
+ * @param logger - DtLogger to use
+ * @param error - AxiosError, Error or string to log
+ * @param [includeStack=true] - Include stack in the message, default false
+ * @returns Logs the error without rethrowing
+ * @see {@link DtLogger.log}
+ * @see {@link createExceptionLogger} for a curried setup
  */
 export function logException(
     logger: DtLogger,
-    error: Error | string | AxiosError,
+    error: unknown,
     includeStack = false
 ) {
-    const message = error instanceof Error ? error.message : error;
+    const message =
+        error instanceof Error
+            ? error.message
+            : typeof error === "string"
+            ? error
+            : JSON.stringify(error);
+
     const stack =
         error instanceof Error && includeStack ? error.stack : undefined;
-    const code = error instanceof AxiosError ? error.code : undefined;
+
+    const customCode = error instanceof AxiosError ? error.code : undefined;
 
     logger.error({
         type: "Error",
         method: `${functionName}.logException`,
         message,
-        code,
+        customCode,
         stack,
     });
 }