idea-aws 3.6.2 → 3.7.2

package/dist/src/dynamoDB.js

@@ -0,0 +1,308 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DynamoDB = void 0;
+const aws_sdk_1 = require("aws-sdk");
+const uuid_1 = require("uuid");
+const nanoid_1 = require("nanoid");
+const NanoID = (0, nanoid_1.customAlphabet)('0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz', 25);
+const shortid_1 = require("shortid");
+const idea_toolbox_1 = require("idea-toolbox");
+// declare libs as global vars to be reused in warm starts by the Lambda function
+let ideaWarmStart_ddb = null;
+/**
+ * A wrapper for AWS DynamoDB.
+ */
+class DynamoDB {
+    constructor() {
+        if (!ideaWarmStart_ddb)
+            ideaWarmStart_ddb = new aws_sdk_1.DynamoDB.DocumentClient();
+        this.dynamo = ideaWarmStart_ddb;
+    }
+    /**
+     * Convert a JSON object from dynamoDB format to simple JSON.
+     */
+    unmarshall(data, options) {
+        return aws_sdk_1.DynamoDB.Converter.unmarshall(data, options);
+    }
+    /**
+     * Returns an IUID: IDEA's Unique IDentifier, which is an id unique through all IDEA's projects.
+     * Note: there's no need of an authorization check for extrernal uses: the permissions depend
+     * from the context in which it's executed.
+     * @deprecated use IUNID instead (nano version)
+     * @param project project code
+     * @return the IUID
+     */
+    async IUID(project) {
+        const MAX_ATTEMPTS = 3;
+        if (!project)
+            throw new Error('Missing project');
+        return await this.identifiersGeneratorHelper(project, 'IUID', 0, MAX_ATTEMPTS);
+    }
+    /**
+     * Returns an IUNID: IDEA's Unique Nano IDentifier, which is an id unique through all IDEA's projects.
+     * Note: no need of an auth check for external uses: the permissions depend from the context in which it's executed.
+     * @param project project code
+     * @return the IUNID
+     */
+    async IUNID(project) {
+        const MAX_ATTEMPTS = 3;
+        if (!project)
+            throw new Error('Missing project');
+        return await this.identifiersGeneratorHelper(project, 'IUNID', 0, MAX_ATTEMPTS);
+    }
+    /**
+     * Returns an ISID: IDEA's Short IDentifier, which is a short, unique id through a single project.
+     * Note: there's no need of an authorization check for extrernal uses: the permissions depend
+     * from the context in which it's executed.
+     * @param project project code
+     * @return the ISID
+     */
+    async ISID(project) {
+        const MAX_ATTEMPTS = 3;
+        if (!project)
+            throw new Error('Missing project');
+        return await this.identifiersGeneratorHelper(project, 'ISID', 0, MAX_ATTEMPTS);
+    }
+    async identifiersGeneratorHelper(project, type, attempt, maxAttempts) {
+        if (attempt > maxAttempts)
+            throw new Error('Operation failed');
+        let id, result;
+        switch (type) {
+            case 'IUNID':
+                id = NanoID();
+                result = `${project}_${id}`;
+                break;
+            case 'IUID':
+                id = (0, uuid_1.v4)();
+                result = `${project}_${id}`;
+                break;
+            case 'ISID':
+                // avoid _ characters (to avoid concatenation problems with ids) -- it must be anyway 64 chars-long
+                (0, shortid_1.characters)('0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ-@');
+                id = (0, shortid_1.generate)();
+                result = id;
+                break;
+        }
+        try {
+            await this.put({
+                TableName: 'idea_'.concat(type),
+                Item: { project, id },
+                ConditionExpression: 'NOT (#p = :project AND #id = :id)',
+                ExpressionAttributeNames: { '#p': 'project', '#id': 'id' },
+                ExpressionAttributeValues: { ':project': project, ':id': id }
+            });
+            return result;
+        }
+        catch (err) {
+            // ID exists, try again
+            await this.identifiersGeneratorHelper(project, type, attempt + 1, maxAttempts);
+        }
+    }
+    /**
+     * Manage atomic counters (atomic autoincrement values) in IDEA's projects.
+     * They key of an atomic counter should be composed as the following: `DynamoDBTableName_uniqueKey`.
+     * @param key the key of the counter
+     */
+    async getAtomicCounterByKey(key) {
+        (0, idea_toolbox_1.logger)(`GET ATOMIC COUNTER FOR ${key}`);
+        const result = await this.update({
+            TableName: 'idea_atomicCounters',
+            Key: { key },
+            UpdateExpression: 'ADD atomicCounter :increment',
+            ExpressionAttributeValues: { ':increment': 1 },
+            ReturnValues: 'UPDATED_NEW'
+        });
+        if (!result?.Attributes?.atomicCounter)
+            throw new Error('Operation failed');
+        else
+            return result.Attributes.atomicCounter;
+    }
+    /**
+     * Get an item of a DynamoDB table.
+     */
+    async get(params) {
+        (0, idea_toolbox_1.logger)(`GET ${params.TableName}`);
+        const result = await this.dynamo.get(params).promise();
+        if (!result?.Item)
+            throw new Error('Not found');
+        return result.Item;
+    }
+    /**
+     * Put an item in a DynamoDB table.
+     */
+    async put(params) {
+        (0, idea_toolbox_1.logger)(`PUT ${params.TableName}`);
+        return await this.dynamo.put(params).promise();
+    }
+    /**
+     * Update an item of a DynamoDB table.
+     */
+    async update(params) {
+        (0, idea_toolbox_1.logger)(`UPDATE ${params.TableName}`);
+        return await this.dynamo.update(params).promise();
+    }
+    /**
+     * Delete an item of a DynamoDB table.
+     */
+    async delete(params) {
+        (0, idea_toolbox_1.logger)(`DELETE ${params.TableName}`);
+        return await this.dynamo.delete(params).promise();
+    }
+    /**
+     * Get group of items based on their keys from DynamoDb table, avoiding the limits of DynamoDB's BatchGetItem.
+     * @param ignoreErr if set, ignore the errors and continue the bulk op.
+     */
+    async batchGet(table, keys, ignoreErr) {
+        if (!keys.length) {
+            (0, idea_toolbox_1.logger)(`BATCH GET ${table}`, null, 'No elements to get');
+            return [];
+        }
+        await this.batchGetHelper(table, keys, [], Boolean(ignoreErr));
+    }
+    async batchGetHelper(table, keys, resultElements, ignoreErr, currentChunk = 0, chunkSize = 100) {
+        const batch = { RequestItems: {} };
+        batch.RequestItems[table] = { Keys: [] };
+        batch.RequestItems[table].Keys = keys.slice(currentChunk, currentChunk + chunkSize);
+        (0, idea_toolbox_1.logger)(`BATCH GET ${table}`, null, `${currentChunk} of ${keys.length}`);
+        let result;
+        try {
+            result = await this.dynamo.batchGet(batch).promise();
+        }
+        catch (err) {
+            if (!ignoreErr)
+                throw err;
+        }
+        if (result)
+            resultElements = resultElements.concat(result.Responses[table]);
+        // if there are still chunks to manage, go on recursively
+        if (currentChunk + chunkSize < keys.length)
+            await this.batchGetHelper(table, keys, resultElements, ignoreErr, currentChunk + chunkSize, chunkSize);
+        // no more chunks to manage: we're done
+        return resultElements;
+    }
+    /**
+     * Put an array of items in a DynamoDb table, avoiding the limits of DynamoDB's BatchWriteItem.
+     * In case of errors, it will retry with a random back-off mechanism until the timeout.
+     * Therefore, in case of timeout, there may be some elements written and some not.
+     */
+    async batchPut(table, items) {
+        if (!items.length)
+            return (0, idea_toolbox_1.logger)(`BATCH WRITE (PUT) ${table}`, null, 'No elements to write');
+        await this.batchWriteHelper(table, items, true);
+    }
+    /**
+     * Delete an array of items from a DynamoDb table, avoiding the limits of DynamoDB's BatchWriteItem.
+     * In case of errors, it will retry with a random back-off mechanism until the timeout.
+     * Therefore, in case of timeout, there may be some elements deleted and some not.
+     */
+    async batchDelete(table, keys) {
+        if (!keys.length)
+            return (0, idea_toolbox_1.logger)(`BATCH WRITE (DELETE) ${table}`, null, 'No elements to write');
+        await this.batchWriteHelper(table, keys, false);
+    }
+    async batchWriteHelper(table, itemsOrKeys, isPut, currentChunk = 0, chunkSize = 25) {
+        (0, idea_toolbox_1.logger)(`BATCH WRITE (${isPut ? 'PUT' : 'DELETE'}) ${table}`, null, `${currentChunk} of ${itemsOrKeys.length}`);
+        let requests;
+        if (isPut)
+            requests = itemsOrKeys.slice(currentChunk, currentChunk + chunkSize).map(i => ({ PutRequest: { Item: i } }));
+        // isDelete
+        else
+            requests = itemsOrKeys.slice(currentChunk, currentChunk + chunkSize).map(k => ({ DeleteRequest: { Key: k } }));
+        const batch = { RequestItems: { [table]: requests } };
+        await this.batchWriteChunkWithRetries(table, batch);
+        // if there are still chunks to manage, go on recursively
+        if (currentChunk + chunkSize < itemsOrKeys.length)
+            await this.batchWriteHelper(table, itemsOrKeys, isPut, currentChunk + chunkSize, chunkSize);
+    }
+    async batchWriteChunkWithRetries(table, params) {
+        const getRandomInt = (max) => Math.floor(Math.random() * max);
+        const wait = (seconds) => new Promise(x => setTimeout(() => x(), seconds * 1000));
+        let attempts = 0;
+        do {
+            const response = await this.dynamo.batchWrite(params).promise();
+            if (response.UnprocessedItems &&
+                response.UnprocessedItems[table] &&
+                response.UnprocessedItems[table].length > 0) {
+                params.RequestItems = response.UnprocessedItems;
+                attempts++;
+                const waitSeconds = getRandomInt(attempts * 5);
+                (0, idea_toolbox_1.logger)('BATCH WRITE THROTTLED', null, `Waiting ${waitSeconds} seconds to retry`);
+                await wait(waitSeconds);
+            }
+            else {
+                params.RequestItems = null;
+            }
+        } while (params.RequestItems);
+    }
+    /**
+     * Query a DynamoDb table, avoiding the limits of DynamoDB's Query.
+     * @param params the params to apply to DynamoDB's function
+     */
+    async query(params) {
+        (0, idea_toolbox_1.logger)(`Query ${params.TableName}`);
+        const result = await this.queryScanHelper(params, [], true);
+        (0, idea_toolbox_1.logger)(`\tResults query ${params.TableName}`, null, result?.length || 0);
+        return result;
+    }
+    /**
+     * Scan a DynamoDb table, avoiding the limits of DynamoDB's Query.
+     * @param params the params to apply to DynamoDB's function
+     */
+    async scan(params) {
+        (0, idea_toolbox_1.logger)(`Scan ${params.TableName}`);
+        const result = await this.queryScanHelper(params, [], false);
+        (0, idea_toolbox_1.logger)(`\tResults scan ${params.TableName}`, null, result?.length || 0);
+        return result;
+    }
+    async queryScanHelper(params, items, isQuery) {
+        let result;
+        if (isQuery)
+            result = await this.dynamo.query(params).promise();
+        else
+            result = await this.dynamo.scan(params).promise();
+        items = items.concat(result.Items);
+        if (result.LastEvaluatedKey) {
+            params.ExclusiveStartKey = result.LastEvaluatedKey;
+            await this.queryScanHelper(params, items, isQuery);
+        }
+        else
+            return items;
+    }
+    /**
+     * Query a DynamoDb table in the traditional way (no pagination or data mapping).
+     * @param params the params to apply to DynamoDB's function
+     */
+    async queryClassic(params) {
+        (0, idea_toolbox_1.logger)(`Query classic ${params.TableName}`);
+        const result = await this.dynamo.query(params).promise();
+        (0, idea_toolbox_1.logger)(`\tResults query classic ${params.TableName}`, null, result?.Items?.length || 0);
+        return result;
+    }
+    /**
+     * Scan a DynamoDb table in the traditional way (no pagination or data mapping).
+     * @param params the params to apply to DynamoDB's function
+     */
+    async scanClassic(params) {
+        (0, idea_toolbox_1.logger)(`Scan classic ${params.TableName}`);
+        const result = await this.dynamo.scan(params).promise();
+        (0, idea_toolbox_1.logger)(`\tResults scan classic ${params.TableName}`, null, result?.Items?.length || 0);
+        return result;
+    }
+    /**
+     * Execute a series of max 10 write operations in a single transaction.
+     * @param ops the operations to execute in the transaction
+     */
+    async transactWrites(ops) {
+        if (!ops.length)
+            return (0, idea_toolbox_1.logger)('TRANSACTION WRITES', null, 'No elements to write');
+        (0, idea_toolbox_1.logger)('TRANSACTION WRITES');
+        await this.dynamo.transactWrite({ TransactItems: ops.slice(0, 10) }).promise();
+    }
+    /**
+     * Creates a set of elements (DynamoDB format) inferring the type of set from the type of the first element.
+     */
+    createSet(array, options) {
+        return this.dynamo.createSet(array, options);
+    }
+}
+exports.DynamoDB = DynamoDB;

package/dist/src/genericController.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GenericController = void 0;
+const idea_toolbox_1 = require("idea-toolbox");
+const dynamoDB_1 = require("./dynamoDB");
+const cognito_1 = require("./cognito");
+const s3_1 = require("./s3");
+const ses_1 = require("./ses");
+const sns_1 = require("./sns");
+const translate_1 = require("./translate");
+const comprehend_1 = require("./comprehend");
+const attachments_1 = require("./attachments");
+/**
+ * An abstract class to inherit to manage some resources with an AWS Lambda function.
+ */
+class GenericController {
+    /**
+     * Initialize a new GenericController helper object.
+     * @param event the event that invoked the AWS lambda function
+     * @param callback the callback to resolve or reject the execution
+     */
+    constructor(event, callback, options) {
+        options = options || {};
+        this.event = event;
+        this.callback = callback;
+        this.tables = options.tables || {};
+        // set the logs to print objects deeper
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        require('util').inspect.defaultOptions.depth = null;
+    }
+    /**
+     * Default callback for the Lambda.
+     */
+    done(err, res) {
+        (0, idea_toolbox_1.logger)(err ? 'DONE WITH ERRORS' : 'DONE', err, res, true);
+        this.callback(err, res);
+    }
+    ///
+    /// AWS SERVICES
+    ///
+    get dynamoDB() {
+        if (!this._dynamoDB)
+            this._dynamoDB = new dynamoDB_1.DynamoDB();
+        return this._dynamoDB;
+    }
+    set dynamoDB(dynamoDB) {
+        this._dynamoDB = dynamoDB;
+    }
+    get cognito() {
+        if (!this._cognito)
+            this._cognito = new cognito_1.Cognito();
+        return this._cognito;
+    }
+    set cognito(cognito) {
+        this._cognito = cognito;
+    }
+    get s3() {
+        if (!this._s3)
+            this._s3 = new s3_1.S3();
+        return this._s3;
+    }
+    set s3(s3) {
+        this._s3 = s3;
+    }
+    get ses() {
+        if (!this._ses)
+            this._ses = new ses_1.SES();
+        return this._ses;
+    }
+    set ses(ses) {
+        this._ses = ses;
+    }
+    get sns() {
+        if (!this._sns)
+            this._sns = new sns_1.SNS();
+        return this._sns;
+    }
+    set sns(sns) {
+        this._sns = sns;
+    }
+    get translate() {
+        if (!this._translate)
+            this._translate = new translate_1.Translate();
+        return this._translate;
+    }
+    set translate(translate) {
+        this._translate = translate;
+    }
+    get comprehend() {
+        if (!this._comprehend)
+            this._comprehend = new comprehend_1.Comprehend();
+        return this._comprehend;
+    }
+    set comprehend(comprehend) {
+        this._comprehend = comprehend;
+    }
+    ///
+    /// HELPERS
+    ///
+    /**
+     * Manage attachments (through SignedURLs).
+     */
+    get attachments() {
+        if (!this._attachments)
+            this._attachments = new attachments_1.Attachments();
+        return this._attachments;
+    }
+    set attachments(attachments) {
+        this._attachments = attachments;
+    }
+}
+exports.GenericController = GenericController;

package/dist/{resourceController.d.ts → src/resourceController.d.ts}

@@ -1,3 +1,4 @@
+import { CognitoUser } from 'idea-toolbox';
 import { GenericController, GenericControllerOptions } from './genericController';
 /**
  * An abstract class to inherit to manage API requests (AWS API Gateway) in an AWS Lambda function.
@@ -6,6 +7,7 @@ export declare abstract class ResourceController extends GenericController {
     protected authorization: string;
     protected claims: any;
     protected principalId: string;
+    protected user: CognitoUser;
     protected stage: string;
     protected httpMethod: string;
     body: any;
@@ -19,8 +21,8 @@ export declare abstract class ResourceController extends GenericController {
     protected translations: any;
     protected templateMatcher: RegExp;
     constructor(event: any, callback: any, options?: ResourceControllerOptions);
-    handleRequest: () => void;
-    protected done(err: Error | null, res?: any): void;
+    handleRequest: () => Promise<void>;
+    protected done(err: Error | null, res?: any, statusCode?: number): void;
     /**
      * To @override
      */
@@ -83,16 +85,17 @@ export declare abstract class ResourceController extends GenericController {
     sharedResourceExists(path: string): boolean;
     /**
      * Load a shared resource in the back-end (translation, template, etc.).
-     * @param encoding default: `utf-8`
      */
-    loadSharedResource(path: string, encoding?: string): string;
+    loadSharedResource(path: string): string;
     /**
      * Simulate an internal API request, invoking directly the lambda and therefore saving resources.
      * @return the body of the response
+     * @deprecated don't run a Lambda from another Lambda (bad practice)
      */
     invokeInternalAPIRequest(params: InternalAPIRequestParams): Promise<any>;
     /**
      * Whether the current request comes from an internal API request, i.e. it was invoked by another controller.
+     * @deprecated don't run a Lambda from another Lambda (bad practice)
      */
     comesFromInternalRequest(): boolean;
     /**
@@ -134,6 +137,7 @@ export interface ResourceControllerOptions extends GenericControllerOptions {
 }
 /**
  * The parameters needed to invoke an internal API request.
+ * @deprecated don't run a Lambda from another Lambda (bad practice)
  */
 export interface InternalAPIRequestParams {
     /**