@moicky/dynamodb 1.1.0 → 1.1.2

package/dist/index.js

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

package/dist/lib/client.d.ts

@@ -1,4 +1,3 @@
 import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
-import "dotenv/config";
 export declare const client: DynamoDBClient;
 export declare const TableName: string;

package/dist/lib/client.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TableName = exports.client = void 0;
+const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
+exports.client = new client_dynamodb_1.DynamoDBClient({
+    region: process.env.AWS_REGION || "eu-central-1",
+});
+exports.TableName = process.env.DYNAMODB_TABLE;
+if (!exports.TableName) {
+    throw new Error("Missing DYNAMODB_TABLE environment variable");
+}

package/dist/lib/helpers.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAttributesFromExpression = exports.getAttributeNames = exports.getAttributeValues = exports.splitEvery = exports.stripKey = void 0;
+const util_dynamodb_1 = require("@aws-sdk/util-dynamodb");
+// ----- Configuration -----
+// Since dynamo only accepts key atrtributes which are described in table schema
+// we remove any other attributes from the item if they are present and passed as
+// key parameter to any of the functions below (getItem, updateItem, deleteItem...)
+function stripKey(key) {
+    return (0, util_dynamodb_1.marshall)({ PK: key.PK, SK: key.SK });
+}
+exports.stripKey = stripKey;
+function splitEvery(items, limit = 25) {
+    const batches = [];
+    for (let i = 0; i < items.length; i += limit) {
+        batches.push(items.slice(i, i + limit));
+    }
+    return batches;
+}
+exports.splitEvery = splitEvery;
+function getAttributeValues(key, attributesToGet) {
+    return (0, util_dynamodb_1.marshall)((attributesToGet || Object.keys(key)).reduce((acc, keyName) => {
+        acc[`:${keyName}`] = key[keyName];
+        return acc;
+    }, {}));
+}
+exports.getAttributeValues = getAttributeValues;
+function getAttributeNames(key, attributesToGet) {
+    return (attributesToGet || Object.keys(key)).reduce((acc, keyName) => {
+        acc[`#${keyName}`] = keyName;
+        return acc;
+    }, {});
+}
+exports.getAttributeNames = getAttributeNames;
+function getAttributesFromExpression(expression, prefix = "#") {
+    return (expression
+        .match(new RegExp(`${prefix}\\w+`, "g"))
+        ?.map((attr) => attr.slice(1)) || []);
+}
+exports.getAttributesFromExpression = getAttributesFromExpression;

package/dist/operations/delete.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deleteItems = exports.deleteItem = void 0;
+const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
+const client_1 = require("../lib/client");
+const helpers_1 = require("../lib/helpers");
+async function deleteItem(key, args = {}) {
+    return client_1.client.send(new client_dynamodb_1.DeleteItemCommand({
+        TableName: client_1.TableName,
+        Key: (0, helpers_1.stripKey)(key),
+        ...args,
+    }));
+}
+exports.deleteItem = deleteItem;
+async function deleteItems(keys, args = {}, retry = 0) {
+    const uniqueKeys = Object.values(keys.reduce((acc, key) => {
+        const strippedKey = (0, helpers_1.stripKey)(key);
+        const keyString = JSON.stringify(strippedKey);
+        if (!acc[keyString]) {
+            acc[keyString] = strippedKey;
+        }
+        return acc;
+    }, {}));
+    return new Promise(async (resolve, reject) => {
+        const batches = (0, helpers_1.splitEvery)(uniqueKeys);
+        if (retry > 3)
+            return;
+        for (const batch of batches) {
+            await client_1.client
+                .send(new client_dynamodb_1.BatchWriteItemCommand({
+                RequestItems: {
+                    [client_1.TableName]: batch.map((Key) => ({
+                        DeleteRequest: {
+                            Key,
+                        },
+                    })),
+                },
+                ...args,
+            }))
+                .then((res) => {
+                if (res?.UnprocessedItems?.[client_1.TableName]?.length) {
+                    if (retry + 1 > 3)
+                        return reject(res);
+                    return deleteItems(res.UnprocessedItems[client_1.TableName], args, retry + 1);
+                }
+            })
+                .catch(reject);
+        }
+        resolve();
+    });
+}
+exports.deleteItems = deleteItems;

package/dist/operations/get.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAllItems = exports.getItems = exports.getItem = void 0;
+const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
+const util_dynamodb_1 = require("@aws-sdk/util-dynamodb");
+const client_1 = require("../lib/client");
+const helpers_1 = require("../lib/helpers");
+async function getItem(key, args = {}) {
+    return client_1.client
+        .send(new client_dynamodb_1.GetItemCommand({
+        TableName: client_1.TableName,
+        Key: (0, helpers_1.stripKey)(key),
+        ...args,
+    }))
+        .then((res) => res?.Item && (0, util_dynamodb_1.unmarshall)(res.Item));
+}
+exports.getItem = getItem;
+async function getItems(keys, args = {}, retry = 0) {
+    // creates batches of 100 items each and performs batchGet on every batch.
+    // also retries up to 3 times if there are unprocessed items (due to size limit of 16MB)
+    // returns items in same order as keys (not sorted by default when using batchGet)
+    if (retry > 3)
+        return [];
+    const batchReadLimit = 100;
+    // duplicate key entries would cause an error, so we remove them
+    const uniqueKeys = Object.values(keys.reduce((acc, key) => {
+        const strippedKey = (0, helpers_1.stripKey)(key);
+        const keyString = JSON.stringify(strippedKey);
+        if (!acc[keyString]) {
+            acc[keyString] = strippedKey;
+        }
+        return acc;
+    }, {}));
+    const batches = (0, helpers_1.splitEvery)(uniqueKeys, batchReadLimit);
+    const results = [];
+    if (retry > 2) {
+        return results;
+    }
+    await Promise.all(batches.map(async (batch) => {
+        await client_1.client
+            .send(new client_dynamodb_1.BatchGetItemCommand({
+            RequestItems: {
+                [client_1.TableName]: {
+                    Keys: batch,
+                    ...args,
+                },
+            },
+        }))
+            .then((res) => {
+            const unprocessed = res?.UnprocessedKeys?.[client_1.TableName];
+            const allItemsFromBatch = res?.Responses?.[client_1.TableName] || [];
+            if (unprocessed) {
+                return getItems(unprocessed.Keys, args, retry + 1).then((items) => allItemsFromBatch.concat(items));
+            }
+            return allItemsFromBatch.map((item) => item && (0, util_dynamodb_1.unmarshall)(item));
+        })
+            .then((items) => results.push(...items));
+    }));
+    const resultItems = results
+        .filter((i) => i)
+        .reduce((acc, item) => {
+        const keyString = JSON.stringify((0, helpers_1.stripKey)(item));
+        acc[keyString] = item;
+        return acc;
+    }, {});
+    return keys.map((key) => resultItems[JSON.stringify((0, helpers_1.stripKey)(key))] || undefined);
+}
+exports.getItems = getItems;
+async function getAllItems(args = {}) {
+    return client_1.client
+        .send(new client_dynamodb_1.ScanCommand({
+        TableName: client_1.TableName,
+        ...args,
+    }))
+        .then((res) => res.Items.map((item) => item && (0, util_dynamodb_1.unmarshall)(item)));
+}
+exports.getAllItems = getAllItems;

package/dist/operations/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./delete"), exports);
+__exportStar(require("./get"), exports);
+__exportStar(require("./misc"), exports);
+__exportStar(require("./put"), exports);
+__exportStar(require("./query"), exports);
+__exportStar(require("./update"), exports);

package/dist/operations/misc.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getNewId = exports.itemExists = void 0;
+const get_1 = require("./get");
+const query_1 = require("./query");
+async function itemExists(key, args = {}) {
+    const item = await (0, get_1.getItem)(key, args);
+    return item !== undefined && item !== null;
+}
+exports.itemExists = itemExists;
+async function getNewId({ PK, SK, length = 8, }) {
+    // Assumes that you are using SK as the incrementing ID
+    if (!PK) {
+        throw new Error("Cannot generate new ID: PK");
+    }
+    let lastId = "0";
+    if (!SK) {
+        const lastItem = (await (0, query_1.queryItems)("#PK = :PK", { PK }, { Limit: 1, ScanIndexForward: false }))?.[0];
+        const parts = lastItem?.["SK"]?.split("/") || [];
+        lastId = parts?.[parts.length - 1] || "0";
+    }
+    else {
+        const formattedSK = SK + (!SK.endsWith("/") ? "/" : "");
+        const lastItem = (await (0, query_1.queryItems)("#PK = :PK and begins_with(#SK, :SK)", { PK, SK: formattedSK }, { Limit: 1, ScanIndexForward: false }))?.[0];
+        const parts = lastItem?.["SK"]?.split("/") || [];
+        lastId = parts?.[formattedSK.split("/").length - 1] || "0";
+    }
+    const newId = parseInt(lastId) + 1 + "";
+    const withPadding = newId.padStart(length || 0, "0");
+    return SK
+        ? `${SK}${!SK.endsWith("/") ? "/" : ""}${withPadding}`
+        : withPadding;
+}
+exports.getNewId = getNewId;

package/dist/operations/put.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.putItems = exports.putItem = void 0;
+const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
+const util_dynamodb_1 = require("@aws-sdk/util-dynamodb");
+const client_1 = require("../lib/client");
+const helpers_1 = require("../lib/helpers");
+async function putItem(data, args = {}) {
+    if (!Object.keys(data).includes("createdAt")) {
+        data.createdAt = Date.now();
+    }
+    return client_1.client.send(new client_dynamodb_1.PutItemCommand({
+        TableName: client_1.TableName,
+        Item: (0, util_dynamodb_1.marshall)(data),
+        ...args,
+    }));
+}
+exports.putItem = putItem;
+async function putItems(items, args = {}) {
+    return new Promise(async (resolve, reject) => {
+        const batches = (0, helpers_1.splitEvery)(items);
+        const now = Date.now();
+        for (const batch of batches) {
+            batch.forEach((item) => {
+                if (!Object.keys(item).includes("createdAt")) {
+                    item.createdAt = now;
+                }
+            });
+            await client_1.client
+                .send(new client_dynamodb_1.BatchWriteItemCommand({
+                RequestItems: {
+                    [client_1.TableName]: batch.map((item) => ({
+                        PutRequest: {
+                            Item: (0, util_dynamodb_1.marshall)(item),
+                        },
+                    })),
+                },
+                ...args,
+            }))
+                .catch(reject);
+        }
+        resolve();
+    });
+}
+exports.putItems = putItems;

package/dist/operations/query.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.queryAllItems = exports.queryItems = exports.query = void 0;
+const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
+const util_dynamodb_1 = require("@aws-sdk/util-dynamodb");
+const client_1 = require("../lib/client");
+const helpers_1 = require("../lib/helpers");
+async function query(keyCondition, key, args = {}) {
+    return client_1.client.send(new client_dynamodb_1.QueryCommand({
+        TableName: client_1.TableName,
+        KeyConditionExpression: keyCondition,
+        ExpressionAttributeValues: (0, helpers_1.getAttributeValues)(key, [
+            ...(0, helpers_1.getAttributesFromExpression)(keyCondition, ":"),
+            ...(0, helpers_1.getAttributesFromExpression)(args?.FilterExpression || "", ":"),
+        ]),
+        ExpressionAttributeNames: (0, helpers_1.getAttributeNames)(key, [
+            ...(0, helpers_1.getAttributesFromExpression)(keyCondition),
+            ...(0, helpers_1.getAttributesFromExpression)(args?.FilterExpression || ""),
+        ]),
+        ...args,
+    }));
+}
+exports.query = query;
+async function queryItems(keyCondition, key, args = {}) {
+    return query(keyCondition, key, args).then((res) => (res?.Items || []).map((item) => item && (0, util_dynamodb_1.unmarshall)(item)));
+}
+exports.queryItems = queryItems;
+async function queryAllItems(keyCondition, key, args = {}) {
+    let data = await query(keyCondition, key, args);
+    while (data.LastEvaluatedKey) {
+        if (data.LastEvaluatedKey) {
+            let helper = await query(keyCondition, key, {
+                ...args,
+                ExclusiveStartKey: data.LastEvaluatedKey,
+            });
+            if (helper?.Items && data?.Items) {
+                data.Items.push(...helper.Items);
+            }
+            data && (data.LastEvaluatedKey = helper.LastEvaluatedKey);
+        }
+    }
+    return (data?.Items || []).map((item) => item && (0, util_dynamodb_1.unmarshall)(item));
+}
+exports.queryAllItems = queryAllItems;

package/dist/operations/update.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.removeAttributes = exports.updateItem = void 0;
+const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
+const client_1 = require("../lib/client");
+const helpers_1 = require("../lib/helpers");
+async function updateItem(key, data, args = {}) {
+    if (!Object.keys(data).includes("updatedAt")) {
+        data.updatedAt = Date.now();
+    }
+    const UpdateExpression = "SET " +
+        Object.keys(data)
+            .map((key) => `#${key} = :${key}`)
+            .join(", ");
+    return client_1.client.send(new client_dynamodb_1.UpdateItemCommand({
+        TableName: client_1.TableName,
+        Key: (0, helpers_1.stripKey)(key),
+        UpdateExpression,
+        ExpressionAttributeValues: (0, helpers_1.getAttributeValues)(data),
+        ExpressionAttributeNames: (0, helpers_1.getAttributeNames)(data),
+        ...args,
+    }));
+}
+exports.updateItem = updateItem;
+async function removeAttributes(key, attributes) {
+    const UpdateExpression = "REMOVE " + attributes.map((att) => `#${att}`).join(", ");
+    return client_1.client.send(new client_dynamodb_1.UpdateItemCommand({
+        TableName: client_1.TableName,
+        Key: (0, helpers_1.stripKey)(key),
+        UpdateExpression,
+        ExpressionAttributeNames: (0, helpers_1.getAttributeNames)(attributes.reduce((acc, att) => {
+            acc[att] = att;
+            return acc;
+        }, {})),
+    }));
+}
+exports.removeAttributes = removeAttributes;

package/package.json

@@ -1,10 +1,9 @@
 {
   "name": "@moicky/dynamodb",
-  "version": "1.1.0",
-  "description": "Contains a collection of convenience functions for working with AWS DynamoDB",
-  "main": "dist/built/commonjs/index.js",
-  "module": "dist/built/esnext/index.js",
+  "version": "1.1.2",
+  "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "description": "Contains a collection of convenience functions for working with AWS DynamoDB",
   "homepage": "https://github.com/Moicky/dynamodb#readme",
   "author": {
     "name": "Moicky",
@@ -19,22 +18,20 @@
   },
   "license": "ISC",
   "scripts": {
-    "watch": "webpack --watch --mode=development",
-    "build": "webpack --mode=production",
+    "build": "tsc",
+    "watch": "tsc -w",
     "test": "jest --runInBand"
   },
   "dependencies": {
     "@aws-sdk/client-dynamodb": "^3.338.0",
-    "@aws-sdk/util-dynamodb": "^3.338.0",
-    "aws-crt": "^1.15.16"
+    "@aws-sdk/util-dynamodb": "^3.338.0"
   },
   "devDependencies": {
     "@types/jest": "^29.5.1",
-    "jest": "^29.5.0",
-    "aws-sdk": "^2.1383.0",
+    "@types/node": "^20.2.4",
     "dotenv": "^16.0.3",
-    "ts-loader": "^9.4.3",
-    "webpack-cli": "^5.1.1"
+    "typescript": "^5.0.4",
+    "jest": "^29.5.0"
   },
   "keywords": [
     "dynamodb-helpers",

package/readme.md

@@ -1,11 +1,10 @@
 # @moicky/dynamodb
 
-## Stats
-
 ![](https://img.shields.io/github/languages/top/moicky/dynamodb)
-![](https://img.shields.io/github/actions/workflow/status/moicky/dynamodb/npm-publish.yml)
-![](https://img.shields.io/github/languages/code-size/moicky/dynamodb)
+![](https://img.shields.io/github/actions/workflow/status/moicky/dynamodb/npm-publish.yml?label=build)
+![](https://img.shields.io/github/actions/workflow/status/moicky/dynamodb/run-tests.yml?label=tests)
 ![](https://img.shields.io/github/languages/count/moicky/dynamodb)
+![](https://img.shields.io/bundlephobia/min/@moicky/dynamodb)
 
 ## Description
 
@@ -13,6 +12,7 @@ Contains convenience functions for all major dynamodb operations. Requires very
 
 - 🎁 Will **automatically marshall and unmarshall** items
 - 📦 Will **group items into batches** to avoid aws limits and improve performance
+- ⏱ Will **automatically** add `createdAt` and `updatedAt` attributes on all items to track their most recent create/update operation timestamp. Example value: `Date.now() -> 1685138436000`
 - 🔄 Will **retry** some operations (getItems, deleteItems) **up to 3 times** on unprocessed items
 - 🔒 When specifying an item using its keySchema, all additional attributes (apart from **PK** and **SK**) will be removed to avoid errors
 - 👻 Will **use placeholders** to avoid colliding with [reserved words](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ReservedWords.html) if applicable
@@ -97,28 +97,20 @@ await getAllItems();
 ```ts
 import { deleteItem, deleteItems } from "@moicky/dynamodb";
 
-// Passing more than just the key is possible, but will be removed to avoid errors
-
 // Delete single item
 await deleteItem({
   PK: "User/1",
   SK: "Book/1",
-  title: "The Great Gatsby", // additional fields will be removed before sending
+  title: "The Great Gatsby", // additional fields will be removed before sending to avoid errors
   author: "F. Scott Fitzgerald",
   released: 1925,
 });
 
 // Delete multiple items
-// Keys will be grouped into batches of 25 and will be retried up to 3 times if there are unprocessed items
-// Will also only delete each keySchema once, even if it is present multiple times in the array to improve performance
+// KeySchemas will be grouped into batches of 25 and will be retried up to 3 times if there are unprocessed items
+// Will only delete each keySchema only once, even if it is present multiple times in the array to improve performance
 await deleteItems([
-  {
-    PK: "User/1",
-    SK: "Book/1",
-    title: "The Great Gatsby", // additional fields will be removed before sending
-    author: "F. Scott Fitzgerald",
-    released: 1925,
-  },
+  { PK: "User/1", SK: "Book/1" },
   // ... infinite more items (will be grouped into batches of 25 due to aws limit) and retried up to 3 times
 ]);
 ```
@@ -128,27 +120,13 @@ await deleteItems([
 ```ts
 import { updateItem, removeAttributes } from "@moicky/dynamodb";
 
-// Passing more than just the key is possible, but will be removed to avoid errors
-
 // Update the item and overwrite all supplied fields
 await updateItem(
-  {
-    PK: "User/1",
-    SK: "Book/1",
-    title: "The Great Gatsby", // additional fields will be removed before sending
-  },
+  { PK: "User/1", SK: "Book/1" },
   { description: "A book about a rich guy", author: "F. Scott Fitzgerald" }
 );
 
-// Completely remove fields from the item
-await removeAttributes(
-  {
-    PK: "User/1",
-    SK: "Book/1",
-    title: "The Great Gatsby", // additional fields will be removed before sending
-  },
-  ["description"]
-);
+await removeAttributes({ PK: "User/1", SK: "Book/1" }, ["description"]);
 ```
 
 ### Query Items
@@ -156,7 +134,7 @@ await removeAttributes(
 ```ts
 import { query, queryItems, queryAllItems } from "@moicky/dynamodb";
 
-// You have to use placeholders for the keyCondition & filterExpression:
+// You HAVE TO use placeholders for the keyCondition & filterExpression:
 // prefix the attributeNames with a hash (#) and the attributeValues with a colon (:)
 
 // Query only using keyCondition and retrieve complete response
@@ -188,7 +166,7 @@ const booksWithFilter = await queryAllItems(
     to: 2000,
   },
   // additional args with filterExpression
-  { FilterExpression: "#released BETWEEN :from AND :to" }
+  { FilterExpression: "#released BETWEEN :from AND :to" } // allows to override all args
 );
 ```
 
@@ -201,15 +179,14 @@ import { itemExists, getNewId } from "@moicky/dynamodb";
 const exists = await itemExists({ PK: "User/1", SK: "Book/1" });
 
 // Generate ascending ID
+
 // Example Structure 1: PK: "User/1", SK: "{{ ASCENDING_ID }}"
 // Last item: { PK: "User/1", SK: "00000009" }
-
 const id1 = await getNewId({ PK: "User/1" });
 console.log(id1); // "00000010"
 
 // Example Structure 2: PK: "User/1", SK: "Book/{{ ASCENDING_ID }}"
 // Last item: { PK: "User/1", SK: "Book/00000009" }
-
 const id2 = await getNewId({ PK: "User/1", SK: "Book" });
 console.log(id2); // "00000010"