idea-aws 4.3.2 → 4.3.3

package/dist/index.d.ts

@@ -11,4 +11,4 @@ export * from './src/sns';
 export * from './src/ssm';
 export * from './src/translate';
 export * from './src/attachments';
-export * from './src/logger';
+export * from './src/lambdaLogger';

package/dist/index.js

@@ -27,4 +27,4 @@ __exportStar(require("./src/sns"), exports);
 __exportStar(require("./src/ssm"), exports);
 __exportStar(require("./src/translate"), exports);
 __exportStar(require("./src/attachments"), exports);
-__exportStar(require("./src/logger"), exports);
+__exportStar(require("./src/lambdaLogger"), exports);

package/dist/src/dynamoDB.d.ts

@@ -1,10 +1,12 @@
 import * as DDB from '@aws-sdk/lib-dynamodb';
 import * as DDBUtils from '@aws-sdk/util-dynamodb';
+import { LambdaLogger } from './lambdaLogger';
 /**
  * A wrapper for AWS DynamoDB.
  */
 export declare class DynamoDB {
     protected dynamo: DDB.DynamoDBDocument;
+    protected logger: LambdaLogger;
     constructor();
     /**
      * Convert a JSON object from DynamoDB format to simple JSON.

package/dist/src/dynamoDB.js

@@ -29,11 +29,13 @@ const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
 const DDBUtils = __importStar(require("@aws-sdk/util-dynamodb"));
 const nanoid_1 = require("nanoid");
 const NanoID = (0, nanoid_1.customAlphabet)('0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz', 25);
+const lambdaLogger_1 = require("./lambdaLogger");
 /**
  * A wrapper for AWS DynamoDB.
  */
 class DynamoDB {
     constructor() {
+        this.logger = new lambdaLogger_1.LambdaLogger();
         this.dynamo = DDB.DynamoDBDocument.from(new client_dynamodb_1.DynamoDB(), {
             marshallOptions: { convertEmptyValues: true, removeUndefinedValues: true, convertClassInstanceToMap: true }
         });
@@ -84,7 +86,7 @@ class DynamoDB {
      * @param key the key of the counter
      */
     async getAtomicCounterByKey(key) {
-        console.debug(`Get atomic counter for ${key}`);
+        this.logger.trace(`Get atomic counter for ${key}`);
         const { Attributes } = await this.update({
             TableName: 'idea_atomicCounters',
             Key: { key },
@@ -101,7 +103,7 @@ class DynamoDB {
      * @param params the params to apply to DynamoDB's function
      */
     async get(params) {
-        console.debug(`Get ${params.TableName}`);
+        this.logger.trace(`Get ${params.TableName}`);
         const { Item } = await this.dynamo.get(params);
         if (!Item)
             throw new Error('Not found');
@@ -112,7 +114,7 @@ class DynamoDB {
      * @param params the params to apply to DynamoDB's function
      */
     async put(params) {
-        console.debug(`Put ${params.TableName}`);
+        this.logger.trace(`Put ${params.TableName}`);
         return await this.dynamo.put(params);
     }
     /**
@@ -120,7 +122,7 @@ class DynamoDB {
      * @param params the params to apply to DynamoDB's function
      */
     async update(params) {
-        console.debug(`Update ${params.TableName}`);
+        this.logger.trace(`Update ${params.TableName}`);
         return await this.dynamo.update(params);
     }
     /**
@@ -128,7 +130,7 @@ class DynamoDB {
      * @param params the params to apply to DynamoDB's function
      */
     async delete(params) {
-        console.debug(`Delete ${params.TableName}`);
+        this.logger.trace(`Delete ${params.TableName}`);
         return await this.dynamo.delete(params);
     }
     /**
@@ -139,7 +141,7 @@ class DynamoDB {
      */
     async batchGet(table, keys, ignoreErr) {
         if (!keys.length) {
-            console.debug(`Batch get ${table}: no elements to get`);
+            this.logger.trace(`Batch get ${table}: no elements to get`);
             return [];
         }
         return await this.batchGetHelper(table, keys, [], Boolean(ignoreErr));
@@ -150,7 +152,7 @@ class DynamoDB {
                 [table]: { Keys: keys.slice(currentChunk, currentChunk + chunkSize) }
             }
         };
-        console.debug(`Batch get ${table}: ${currentChunk} of ${keys.length}`);
+        this.logger.trace(`Batch get ${table}: ${currentChunk} of ${keys.length}`);
         let result;
         try {
             result = await this.dynamo.batchGet(batch);
@@ -177,7 +179,7 @@ class DynamoDB {
      */
     async batchPut(table, items) {
         if (!items.length)
-            return console.debug(`Batch write (put) ${table}: no elements to write`);
+            return this.logger.trace(`Batch write (put) ${table}: no elements to write`);
         await this.batchWriteHelper(table, items, true);
     }
     /**
@@ -189,11 +191,11 @@ class DynamoDB {
      */
     async batchDelete(table, keys) {
         if (!keys.length)
-            return console.debug(`Batch write (delete) ${table}: no elements to write`);
+            return this.logger.trace(`Batch write (delete) ${table}: no elements to write`);
         await this.batchWriteHelper(table, keys, false);
     }
     async batchWriteHelper(table, itemsOrKeys, isPut, currentChunk = 0, chunkSize = 25) {
-        console.debug(`Batch write (${isPut ? 'put' : 'delete'}) ${table}: ${currentChunk} of ${itemsOrKeys.length}`);
+        this.logger.trace(`Batch write (${isPut ? 'put' : 'delete'}) ${table}: ${currentChunk} of ${itemsOrKeys.length}`);
         let requests;
         if (isPut)
             requests = itemsOrKeys.slice(currentChunk, currentChunk + chunkSize).map(i => ({ PutRequest: { Item: i } }));
@@ -218,7 +220,7 @@ class DynamoDB {
                 params.RequestItems = response.UnprocessedItems;
                 attempts++;
                 const waitSeconds = getRandomInt(attempts * 5);
-                console.debug(`Batch write throttled: waiting ${waitSeconds} seconds to retry`);
+                this.logger.trace(`Batch write throttled: waiting ${waitSeconds} seconds to retry`);
                 await wait(waitSeconds);
             }
             else {
@@ -231,9 +233,9 @@ class DynamoDB {
      * @param params the params to apply to DynamoDB's function
      */
     async query(params) {
-        console.debug(`Query ${params.TableName}`);
+        this.logger.trace(`Query ${params.TableName}`);
         const result = await this.queryScanHelper(params, [], true);
-        console.debug(`Results query ${params.TableName}: ${result.length ?? 0}`);
+        this.logger.trace(`Results query ${params.TableName}: ${result.length ?? 0}`);
         return result;
     }
     /**
@@ -241,9 +243,9 @@ class DynamoDB {
      * @param params the params to apply to DynamoDB's function
      */
     async scan(params) {
-        console.debug(`Scan ${params.TableName}`);
+        this.logger.trace(`Scan ${params.TableName}`);
         const result = await this.queryScanHelper(params, [], false);
-        console.debug(`Results scan ${params.TableName}: ${result.length ?? 0}`);
+        this.logger.trace(`Results scan ${params.TableName}: ${result.length ?? 0}`);
         return result;
     }
     async queryScanHelper(params, items, isQuery) {
@@ -265,9 +267,9 @@ class DynamoDB {
      * @param params the params to apply to DynamoDB's function
      */
     async queryClassic(params) {
-        console.debug(`Query classic ${params.TableName}`);
+        this.logger.trace(`Query classic ${params.TableName}`);
         const result = await this.dynamo.query(params);
-        console.debug(`Results query classic ${params.TableName}: ${result.Items.length ?? 0}`);
+        this.logger.trace(`Results query classic ${params.TableName}: ${result.Items.length ?? 0}`);
         return result;
     }
     /**
@@ -275,9 +277,9 @@ class DynamoDB {
      * @param params the params to apply to DynamoDB's function
      */
     async scanClassic(params) {
-        console.debug(`Scan classic ${params.TableName}`);
+        this.logger.trace(`Scan classic ${params.TableName}`);
         const result = await this.dynamo.scan(params);
-        console.debug(`Results scan classic ${params.TableName}: ${result.Items.length ?? 0}`);
+        this.logger.trace(`Results scan classic ${params.TableName}: ${result.Items.length ?? 0}`);
         return result;
     }
     /**
@@ -286,8 +288,8 @@ class DynamoDB {
      */
     async transactWrites(ops) {
         if (!ops.length)
-            return console.debug('Transaction writes: no elements to write');
-        console.debug('Transaction writes');
+            return this.logger.trace('Transaction writes: no elements to write');
+        this.logger.trace('Transaction writes');
         await this.dynamo.transactWrite({ TransactItems: ops });
     }
 }

package/dist/src/genericController.d.ts

@@ -1,12 +1,12 @@
 import 'source-map-support/register';
-import { Logger } from './logger';
+import { LambdaLogger } from './lambdaLogger';
 /**
  * An abstract class to inherit to manage some resources with an AWS Lambda function.
  */
 export declare abstract class GenericController {
     protected event: any;
     protected callback: any;
-    protected logger: Logger;
+    protected logger: LambdaLogger;
     /**
      * Initialize a new GenericController helper object.
      * @param event the event that invoked the AWS lambda function
@@ -21,4 +21,17 @@ export declare abstract class GenericController {
      * Default callback for the Lambda.
      */
     protected done(error: Error | any, res?: any): void;
+    /**
+     * Get the current log level for the current Lambda function's `logger`.
+     * Note: "FATAL" means that no log will be printed.
+     */
+    getLambdaLogLevel(): 'TRACE' | 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'FATAL';
+    /**
+     * Set the log level for the current Lambda function's `logger`.
+     */
+    setLambdaLogLevel(logLevel: 'TRACE' | 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'FATAL'): void;
+    /**
+     * Raise the log level of the current Lambda function's `logger` to "FATAL", hence avoiding printing any log.
+     */
+    silentLambdaLogs(): void;
 }

package/dist/src/genericController.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GenericController = void 0;
 require("source-map-support/register");
-const logger_1 = require("./logger");
+const lambdaLogger_1 = require("./lambdaLogger");
 /**
  * An abstract class to inherit to manage some resources with an AWS Lambda function.
  */
@@ -13,7 +13,7 @@ class GenericController {
      * @param callback the callback to resolve or reject the execution
      */
     constructor(event, callback) {
-        this.logger = new logger_1.Logger();
+        this.logger = new lambdaLogger_1.LambdaLogger();
         this.event = event;
         this.callback = callback;
     }
@@ -27,5 +27,24 @@ class GenericController {
             this.logger.info('END-SUCCESS');
         this.callback(error, res);
     }
+    /**
+     * Get the current log level for the current Lambda function's `logger`.
+     * Note: "FATAL" means that no log will be printed.
+     */
+    getLambdaLogLevel() {
+        return process.env.AWS_LAMBDA_LOG_LEVEL;
+    }
+    /**
+     * Set the log level for the current Lambda function's `logger`.
+     */
+    setLambdaLogLevel(logLevel) {
+        process.env.AWS_LAMBDA_LOG_LEVEL = logLevel;
+    }
+    /**
+     * Raise the log level of the current Lambda function's `logger` to "FATAL", hence avoiding printing any log.
+     */
+    silentLambdaLogs() {
+        process.env.AWS_LAMBDA_LOG_LEVEL = 'FATAL';
+    }
 }
 exports.GenericController = GenericController;

package/dist/src/lambdaLogger.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Manage structured logging in the context of a Lambda function.
+ * Note: the log level is controlled by each Lambda function's configuration.
+ */
+export declare class LambdaLogger {
+    shouldLog: (logLevel: 'TRACE' | 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'FATAL') => boolean;
+    trace: (summary: string, content?: object) => void;
+    debug: (summary: string, content?: object) => void;
+    info: (summary: string, content?: object) => void;
+    warn: (summary: string, error: Error | any, content?: object) => void;
+    error: (summary: string, error: Error | any, content?: object) => void;
+}
+export declare const LOG_LEVELS_PRIORITY: Record<string, number>;

package/dist/src/lambdaLogger.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOG_LEVELS_PRIORITY = exports.LambdaLogger = void 0;
+/**
+ * Manage structured logging in the context of a Lambda function.
+ * Note: the log level is controlled by each Lambda function's configuration.
+ */
+class LambdaLogger {
+    constructor() {
+        // note: this is needed as long as the Lambda functions don't become reactive to changes to `AWS_LAMBDA_LOG_LEVEL`
+        this.shouldLog = (logLevel) => exports.LOG_LEVELS_PRIORITY[logLevel] >= exports.LOG_LEVELS_PRIORITY[process.env.AWS_LAMBDA_LOG_LEVEL];
+        this.trace = (summary, content = {}) => {
+            if (this.shouldLog('TRACE'))
+                console.trace({ summary, ...content });
+        };
+        this.debug = (summary, content = {}) => {
+            if (this.shouldLog('DEBUG'))
+                console.debug({ summary, ...content });
+        };
+        this.info = (summary, content = {}) => {
+            if (this.shouldLog('INFO'))
+                console.info({ summary, ...content });
+        };
+        this.warn = (summary, error, content = {}) => {
+            if (this.shouldLog('WARN'))
+                console.warn({ summary, ...content, error });
+        };
+        this.error = (summary, error, content = {}) => {
+            if (this.shouldLog('ERROR'))
+                console.error({ summary, ...content, error });
+        };
+    }
+}
+exports.LambdaLogger = LambdaLogger;
+// levels here are identical to bunyan practices (https://github.com/trentm/node-bunyan#levels)
+exports.LOG_LEVELS_PRIORITY = {
+    TRACE: 10,
+    DEBUG: 20,
+    INFO: 30,
+    WARN: 40,
+    ERROR: 50,
+    FATAL: 60
+};

package/dist/src/resourceController.js

@@ -217,17 +217,22 @@ class ResourceController extends genericController_1.GenericController {
         if (err instanceof RCError)
             return err;
         const error = err;
-        error.intercepted = interceptedInContext;
+        error.unhandled = interceptedInContext;
         error.internalMessage = error.message;
         error.message = replaceWithMessage;
         return error;
     }
     done(error, rawResult, statusCode = this.returnStatusCode ?? (error ? 400 : 200)) {
         const result = error ? { message: error.message } : rawResult ?? {};
-        if (error)
-            this.logger.error('END-FAILED', error, { statusCode, event: this.getEventSummary() });
+        const finalLogContent = { statusCode, event: this.getEventSummary() };
+        if (error) {
+            if (error.unhandled)
+                this.logger.error('END-FAILED', error, finalLogContent);
+            else
+                this.logger.warn('END-FAILED', error, finalLogContent);
+        }
         else
-            this.logger.info('END-SUCCESS', { statusCode, event: this.getEventSummary() });
+            this.logger.info('END-SUCCESS', finalLogContent);
         this.logger.debug('END-DETAIL', { result: Array.isArray(result) ? { array: result.length } : result });
         if (this.logRequestsWithKey)
             this.storeLog(!error);

package/dist/src/s3.d.ts

@@ -1,11 +1,13 @@
 import * as AWSS3 from '@aws-sdk/client-s3';
 import { BodyDataTypes } from '@aws-sdk/lib-storage';
 import { SignedURL } from 'idea-toolbox';
+import { LambdaLogger } from './lambdaLogger';
 /**
  * A wrapper for AWS Simple Storage Service.
  */
 export declare class S3 {
     protected s3: AWSS3.S3Client;
+    protected logger: LambdaLogger;
     protected DEFAULT_DOWNLOAD_BUCKET_PREFIX: string;
     protected DEFAULT_DOWNLOAD_BUCKET: string;
     protected DEFAULT_DOWNLOAD_BUCKET_SEC_TO_EXP: number;

package/dist/src/s3.js

@@ -28,11 +28,13 @@ const AWSS3 = __importStar(require("@aws-sdk/client-s3"));
 const lib_storage_1 = require("@aws-sdk/lib-storage");
 const s3_request_presigner_1 = require("@aws-sdk/s3-request-presigner");
 const idea_toolbox_1 = require("idea-toolbox");
+const lambdaLogger_1 = require("./lambdaLogger");
 /**
  * A wrapper for AWS Simple Storage Service.
  */
 class S3 {
     constructor() {
+        this.logger = new lambdaLogger_1.LambdaLogger();
         this.DEFAULT_DOWNLOAD_BUCKET_PREFIX = 'common';
         this.DEFAULT_DOWNLOAD_BUCKET = 'idea-downloads';
         this.DEFAULT_DOWNLOAD_BUCKET_SEC_TO_EXP = 180;
@@ -81,7 +83,7 @@ class S3 {
      * Make a copy of an object of the bucket.
      */
     async copyObject(options) {
-        console.debug(`S3 copy object: ${options.key}`);
+        this.logger.trace(`S3 copy object: ${options.key}`);
         const command = new AWSS3.CopyObjectCommand({
             CopySource: options.copySource,
             Bucket: options.bucket,
@@ -93,7 +95,7 @@ class S3 {
      * Get an object from a S3 bucket.
      */
     async getObject(options) {
-        console.debug(`S3 get object: ${options.key}`);
+        this.logger.trace(`S3 get object: ${options.key}`);
         const params = { Bucket: options.bucket, Key: options.key };
         if (options.filename)
             params.ResponseContentDisposition = `attachment; filename ="${(0, exports.cleanFilename)(options.filename)}"`;
@@ -127,14 +129,14 @@ class S3 {
             params.Metadata = options.metadata;
         if (options.filename)
             params.ContentDisposition = `attachment; filename ="${(0, exports.cleanFilename)(options.filename)}"`;
-        console.debug(`S3 put object: ${options.key}`);
+        this.logger.trace(`S3 put object: ${options.key}`);
         return await this.s3.send(new AWSS3.PutObjectCommand(params));
     }
     /**
      * Delete an object from an S3 bucket.
      */
     async deleteObject(options) {
-        console.debug(`S3 delete object: ${options.key}`);
+        this.logger.trace(`S3 delete object: ${options.key}`);
         const deleteCommand = new AWSS3.DeleteObjectCommand({ Bucket: options.bucket, Key: options.key });
         return await this.s3.send(deleteCommand);
     }
@@ -142,7 +144,7 @@ class S3 {
      * List the objects of an S3 bucket.
      */
     async listObjects(options) {
-        console.debug(`S3 list object: ${options.prefix}`);
+        this.logger.trace(`S3 list object: ${options.prefix}`);
         const command = new AWSS3.ListObjectsCommand({ Bucket: options.bucket, Prefix: options.prefix });
         return await this.s3.send(command);
     }

package/dist/src/ses.d.ts

@@ -2,11 +2,13 @@
 import * as AWSSES from '@aws-sdk/client-sesv2';
 import { SentMessageInfo as NodemailerSentMessageInfo } from 'nodemailer';
 import { Headers } from 'nodemailer/lib/mailer';
+import { LambdaLogger } from './lambdaLogger';
 /**
  * A wrapper for AWS Simple Email Service.
  */
 export declare class SES {
     protected ses: AWSSES.SESv2Client;
+    protected logger: LambdaLogger;
     constructor(options?: {
         region?: string;
     });

package/dist/src/ses.js

@@ -28,11 +28,13 @@ const client_ses_1 = require("@aws-sdk/client-ses");
 const AWSSES = __importStar(require("@aws-sdk/client-sesv2"));
 const nodemailer_1 = require("nodemailer");
 const dynamoDB_1 = require("./dynamoDB");
+const lambdaLogger_1 = require("./lambdaLogger");
 /**
  * A wrapper for AWS Simple Email Service.
  */
 class SES {
     constructor(options = {}) {
+        this.logger = new lambdaLogger_1.LambdaLogger();
         this.ses = new AWSSES.SESv2Client({ region: options.region });
     }
     //
@@ -104,7 +106,7 @@ class SES {
             ses = this.ses;
         else
             ses = new AWSSES.SESv2Client({ region: sesParams.region });
-        console.debug('SES send templated email');
+        this.logger.trace('SES send templated email');
         return await ses.send(command);
     }
     /**
@@ -144,7 +146,7 @@ class SES {
             ses = this.ses;
         else
             ses = new AWSSES.SESv2Client({ region: sesParams.region });
-        console.debug('SES send email');
+        this.logger.trace('SES send email');
         return await ses.send(command);
     }
     async sendEmailWithNodemailer(emailData, sesParams) {
@@ -165,7 +167,7 @@ class SES {
         mailOptions.attachments = emailData.attachments;
         // note: Nodemailer doesn't support SESv2 as of August 2023
         const ses = new client_ses_1.SESClient({ region: sesParams.region });
-        console.debug('SES send email (Nodemailer)');
+        this.logger.trace('SES send email (Nodemailer)');
         // note: this is a workaround to make Nodemailer works with AWS SDK 3;
         // see: https://github.com/nodemailer/nodemailer/issues/1430
         return await (0, nodemailer_1.createTransport)({ SES: { ses, aws: { SendRawEmailCommand: client_ses_1.SendRawEmailCommand } } }).sendMail(mailOptions);

package/dist/src/sns.d.ts

@@ -1,10 +1,12 @@
 import * as AWSSNS from '@aws-sdk/client-sns';
 import { PushNotificationsPlatforms } from 'idea-toolbox';
+import { LambdaLogger } from './lambdaLogger';
 /**
  * A wrapper for AWS Simple Notification Service.
  */
 export declare class SNS {
     protected client: AWSSNS.SNSClient;
+    protected logger: LambdaLogger;
     constructor(options?: {
         region?: string;
     });

package/dist/src/sns.js

@@ -26,11 +26,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SNS = void 0;
 const AWSSNS = __importStar(require("@aws-sdk/client-sns"));
 const idea_toolbox_1 = require("idea-toolbox");
+const lambdaLogger_1 = require("./lambdaLogger");
 /**
  * A wrapper for AWS Simple Notification Service.
  */
 class SNS {
     constructor(options = {}) {
+        this.logger = new lambdaLogger_1.LambdaLogger();
         this.client = new AWSSNS.SNSClient({ region: options.region });
     }
     /**
@@ -52,7 +54,7 @@ class SNS {
             default:
                 throw new Error('Unsupported platform');
         }
-        console.debug('SNS add platform endpoint');
+        this.logger.trace('SNS add platform endpoint');
         const command = new AWSSNS.CreatePlatformEndpointCommand({ PlatformApplicationArn: platformARN, Token: token });
         const { EndpointArn } = await this.client.send(command);
         return EndpointArn;
@@ -80,7 +82,7 @@ class SNS {
                 default:
                     throw new Error('Unsupported platform');
             }
-        console.debug('SNS publish in topic');
+        this.logger.trace('SNS publish in topic');
         const command = new AWSSNS.PublishCommand({
             MessageStructure: 'json',
             Message: JSON.stringify(structuredMessage),

package/index.ts

@@ -13,4 +13,4 @@ export * from './src/ssm';
 export * from './src/translate';
 export * from './src/attachments';
 
-export * from './src/logger';
+export * from './src/lambdaLogger';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "idea-aws",
-  "version": "4.3.2",
+  "version": "4.3.3",
   "description": "AWS wrappers to use in IDEA's back-ends",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",