@moicky/dynamodb 2.0.1 → 2.2.1

package/dist/operations/update.js

@@ -3,6 +3,38 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.removeAttributes = exports.updateItem = void 0;
 const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
 const lib_1 = require("../lib");
+/**
+ * Updates an item in DynamoDB. All provided fields are overwritten.
+ *
+ * @param key - The primary key of the item to be updated
+ * @param data - An object containing the data to be updated
+ * @param args - Optional parameters for the {@link UpdateItemCommand}
+ * @returns Returns updated item if ReturnValues argument is set, otherwise undefined
+ *
+ * @example
+ * Update the item and overwrite all supplied fields
+ * ```javascript
+ * await updateItem(
+ *   { PK: "User/1", SK: "Book/1" }, // reference to item
+ *   { description: "A book about a rich guy", author: "F. Scott Fitzgerald" } // fields to update
+ * );
+ *
+ * // Conditionally update an item. 'maxReleased' will not be updated since it is referenced inside the ConditionExpression
+ * await updateItem(
+ *   { PK: "User/1", SK: "Book/1" },
+ *   { released: 2000, maxReleased: 1950 },
+ *   { ConditionExpression: "#released < :maxReleased" }
+ * );
+ *
+ * // Return all attributes of the new item
+ * const newItem = await updateItem(
+ *   { PK: "User/1", SK: "Book/1" },
+ *   { released: 2000 },
+ *   { ReturnValues: "ALL_NEW" }
+ * );
+ * console.log(newItem); // { "PK": "User/1", "SK": "Book/1", "released": 2000 }
+ * ```
+ */
 async function updateItem(key, data, args = {}) {
     args = (0, lib_1.withDefaults)(args, "updateItem");
     if (!Object.keys(data).includes("updatedAt")) {
@@ -30,6 +62,20 @@ async function updateItem(key, data, args = {}) {
         .then((res) => args?.ReturnValues ? (0, lib_1.unmarshallWithOptions)(res.Attributes) : undefined);
 }
 exports.updateItem = updateItem;
+/**
+ * Removes specified attributes from an item in DynamoDB.
+ *
+ * @param key - The primary key of the item from which attributes should be removed
+ * @param {string[]} attributes - Array of attribute names to be removed
+ * @param args - Optional parameters for the {@link UpdateItemCommand}
+ * @returns Promise object representing the output of the DynamoDB UpdateItem command
+ *
+ * @example
+ * Remove a specific attribute from an item
+ * ```javascript
+ * await removeAttributes({ PK: "User/1", SK: "Book/1" }, ["description"]);
+ * ```
+ */
 async function removeAttributes(key, attributes, args = {}) {
     args = (0, lib_1.withDefaults)(args, "removeAttributes");
     const UpdateExpression = "REMOVE " + attributes.map((att) => `#${att}`).join(", ");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moicky/dynamodb",
-  "version": "2.0.1",
+  "version": "2.2.1",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "description": "Contains a collection of convenience functions for working with AWS DynamoDB",

package/readme.md

@@ -15,6 +15,7 @@ Contains convenience functions for all major dynamodb operations. Requires very
 - 👻 Will **use placeholders** to avoid colliding with [reserved words](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ReservedWords.html) if applicable
 - 🌎 Supports globally defined default arguments for each operation ([example](#configuring-global-defaults))
 - 🔨 Supports fixes for several issues with dynamodb ([example](#applying-fixes))
+- 📖 Offers a convenient way to use pagination with queries
 
 ## Installation
 
@@ -219,6 +220,24 @@ const booksWithFilter = await queryAllItems(
   // additional args with filterExpression for example
   { FilterExpression: "#released BETWEEN :from AND :to" }
 );
+
+// Pagination
+const { items, hasNextPage, hasPreviousPage, currentPage } =
+  await queryPaginatedItems(
+    "#PK = :PK and begins_with(#SK, :SK)",
+    { PK: "User/1", SK: "Book/" },
+    { pageSize: 100 }
+  );
+// items: The items on the current page.
+// currentPage: { number: 1, firstKey: { ... }, lastKey: { ... } }
+
+const { items: nextItems, currentPage: nextPage } = await queryPaginatedItems(
+  "#PK = :PK and begins_with(#SK, :SK)",
+  { PK: "User/1", SK: "Book/" },
+  { pageSize: 100, currentPage }
+);
+// items: The items on the second page.
+// currentPage: { number: 2, firstKey: { ... }, lastKey: { ... } }
 ```
 
 ### Miscellaneous