@moicky/dynamodb 2.0.1 → 2.2.0

package/dist/operations/misc.d.ts

@@ -1,5 +1,49 @@
 import { GetItemCommandInput } from "@aws-sdk/client-dynamodb";
+/**
+ * Check if an item exists in the DynamoDB table using its key schema.
+ * @param key - The item with at least the partition key and the sort key (if applicable) of the item to check.
+ * @param args - The additional arguments to override or specify for {@link GetItemCommandInput}
+ * @returns A promise that resolves to a boolean indicating whether the item exists or not.
+ *
+ * @example
+ * Check if an item exists
+ * ```typescript
+ * const exists = await itemExists({ PK: "User/1", SK: "Book/1" });
+ * console.log(exists); // true / false
+ * ```
+ */
 export declare function itemExists(key: any, args?: Partial<GetItemCommandInput>): Promise<boolean>;
+/**
+ * Generate an ascending ID for an item in the DynamoDB table using the key schema.
+ * @param params - An object containing key schema information and optional ID length and TableName
+ * @returns A promise that resolves to a string representing the new ascending ID.
+ *
+ * @example
+ * Generate ascending ID
+ * ```typescript
+ * // Example Structure 1: PK: "User/1", SK: "{{ ASCENDING_ID }}"
+ * // Last item: { PK: "User/1", SK: "00000009" }
+ * const id1 = await getAscendingId({ 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 getAscendingId({ PK: "User/1", SK: "Book" });
+ * console.log(id2); // "00000010"
+ *
+ * // Specify length of ID
+ * const id3 = await getAscendingId({ PK: "User/1", SK: "Book", length: 4 });
+ * console.log(id3); // "0010"
+ *
+ * // Example Structure 3: someKeySchemaHash: "User/1", SK: "Book/{{ ASCENDING_ID }}"
+ * // Last item: { someKeySchemaHash: "User/1", SK: "Book/00000009" }
+ * const id4 = await getAscendingId({
+ *   someKeySchemaHash: "User/1",
+ *   SK: "Book",
+ * });
+ * console.log(id4); // "00000010"
+ * ```
+ */
 export declare function getAscendingId({ length, TableName, ...keySchema }: {
     length?: number;
     TableName?: string;

package/dist/operations/misc.js

@@ -4,6 +4,19 @@ exports.getAscendingId = exports.itemExists = void 0;
 const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
 const lib_1 = require("../lib");
 const query_1 = require("./query");
+/**
+ * Check if an item exists in the DynamoDB table using its key schema.
+ * @param key - The item with at least the partition key and the sort key (if applicable) of the item to check.
+ * @param args - The additional arguments to override or specify for {@link GetItemCommandInput}
+ * @returns A promise that resolves to a boolean indicating whether the item exists or not.
+ *
+ * @example
+ * Check if an item exists
+ * ```typescript
+ * const exists = await itemExists({ PK: "User/1", SK: "Book/1" });
+ * console.log(exists); // true / false
+ * ```
+ */
 async function itemExists(key, args = {}) {
     args = (0, lib_1.withDefaults)(args, "itemExists");
     return (0, lib_1.getClient)()
@@ -15,6 +28,37 @@ async function itemExists(key, args = {}) {
         .then((res) => !!res?.Item);
 }
 exports.itemExists = itemExists;
+/**
+ * Generate an ascending ID for an item in the DynamoDB table using the key schema.
+ * @param params - An object containing key schema information and optional ID length and TableName
+ * @returns A promise that resolves to a string representing the new ascending ID.
+ *
+ * @example
+ * Generate ascending ID
+ * ```typescript
+ * // Example Structure 1: PK: "User/1", SK: "{{ ASCENDING_ID }}"
+ * // Last item: { PK: "User/1", SK: "00000009" }
+ * const id1 = await getAscendingId({ 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 getAscendingId({ PK: "User/1", SK: "Book" });
+ * console.log(id2); // "00000010"
+ *
+ * // Specify length of ID
+ * const id3 = await getAscendingId({ PK: "User/1", SK: "Book", length: 4 });
+ * console.log(id3); // "0010"
+ *
+ * // Example Structure 3: someKeySchemaHash: "User/1", SK: "Book/{{ ASCENDING_ID }}"
+ * // Last item: { someKeySchemaHash: "User/1", SK: "Book/00000009" }
+ * const id4 = await getAscendingId({
+ *   someKeySchemaHash: "User/1",
+ *   SK: "Book",
+ * });
+ * console.log(id4); // "00000010"
+ * ```
+ */
 async function getAscendingId({ length = 8, TableName, ...keySchema }) {
     // Assumes that you are the incrementing ID inside or as the keySchema range key
     const table = TableName || (0, lib_1.getDefaultTable)();

package/dist/operations/put.d.ts

@@ -1,5 +1,46 @@
 import { BatchWriteItemCommandInput, BatchWriteItemCommandOutput, PutItemCommandInput, PutItemCommandOutput } from "@aws-sdk/client-dynamodb";
+/**
+ * Inserts an item into the DynamoDB table.
+ * @param data - The item to insert into the table.
+ * @param args - The additional arguments to override or specify for {@link PutItemCommandInput}
+ * @returns A promise that resolves to the output of {@link PutItemCommandOutput} or the unmarshalled attributes if 'ReturnValues' is specified in 'args'.
+ *
+ * @example
+ * Put a single item into DynamoDB
+ * ```javascript
+ * await putItem({
+ *   PK: "User/1",
+ *   SK: "Book/1",
+ *   title: "The Great Gatsby",
+ *   author: "F. Scott Fitzgerald",
+ *   released: 1925,
+ * });
+ * ```
+ */
 export declare function putItem(data: any, args?: Partial<PutItemCommandInput>): Promise<PutItemCommandOutput | Record<string, any>>;
-export declare function putItems(items: any[], args?: Partial<BatchWriteItemCommandInput & {
+type PutItemsArgs = Partial<BatchWriteItemCommandInput & {
     TableName?: string;
-}>): Promise<BatchWriteItemCommandOutput[]>;
+}>;
+/**
+ * Inserts multiple items into the DynamoDB table.
+ * @param items - The items to insert into the table.
+ * @param args - The additional arguments to override or specify for {@link PutItemsArgs}
+ * @returns A promise that resolves to an array of {@link BatchWriteItemCommandOutput}
+ *
+ * @example
+ * Put multiple items into DynamoDB
+ * ```javascript
+ * await putItems([
+ *   {
+ *     PK: "User/1",
+ *     SK: "Book/1",
+ *     title: "The Great Gatsby",
+ *     author: "F. Scott Fitzgerald",
+ *     released: 1925,
+ *   },
+ *   // ... infinite more items (will be grouped into batches of 25 due to aws limit)
+ * ]);
+ * ```
+ */
+export declare function putItems(items: any[], args?: PutItemsArgs): Promise<BatchWriteItemCommandOutput[]>;
+export {};

package/dist/operations/put.js

@@ -3,6 +3,24 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.putItems = exports.putItem = void 0;
 const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
 const lib_1 = require("../lib");
+/**
+ * Inserts an item into the DynamoDB table.
+ * @param data - The item to insert into the table.
+ * @param args - The additional arguments to override or specify for {@link PutItemCommandInput}
+ * @returns A promise that resolves to the output of {@link PutItemCommandOutput} or the unmarshalled attributes if 'ReturnValues' is specified in 'args'.
+ *
+ * @example
+ * Put a single item into DynamoDB
+ * ```javascript
+ * await putItem({
+ *   PK: "User/1",
+ *   SK: "Book/1",
+ *   title: "The Great Gatsby",
+ *   author: "F. Scott Fitzgerald",
+ *   released: 1925,
+ * });
+ * ```
+ */
 async function putItem(data, args = {}) {
     args = (0, lib_1.withDefaults)(args, "putItem");
     if (!Object.keys(data).includes("createdAt")) {
@@ -17,6 +35,27 @@ async function putItem(data, args = {}) {
         .then((res) => args?.ReturnValues ? (0, lib_1.unmarshallWithOptions)(res?.Attributes) : res);
 }
 exports.putItem = putItem;
+/**
+ * Inserts multiple items into the DynamoDB table.
+ * @param items - The items to insert into the table.
+ * @param args - The additional arguments to override or specify for {@link PutItemsArgs}
+ * @returns A promise that resolves to an array of {@link BatchWriteItemCommandOutput}
+ *
+ * @example
+ * Put multiple items into DynamoDB
+ * ```javascript
+ * await putItems([
+ *   {
+ *     PK: "User/1",
+ *     SK: "Book/1",
+ *     title: "The Great Gatsby",
+ *     author: "F. Scott Fitzgerald",
+ *     released: 1925,
+ *   },
+ *   // ... infinite more items (will be grouped into batches of 25 due to aws limit)
+ * ]);
+ * ```
+ */
 async function putItems(items, args = {}) {
     args = (0, lib_1.withDefaults)(args, "putItems");
     return new Promise(async (resolve, reject) => {

package/dist/operations/query.d.ts

@@ -1,4 +1,128 @@
 import { QueryCommandInput, QueryCommandOutput } from "@aws-sdk/client-dynamodb";
+/**
+ * Query a single item in a DynamoDB table using a key condition.
+ * @param keyCondition - The condition for the key in DynamoDB QueryCommand.
+ * @param key - Definitions for the attributes used in keyCondition and FilterExpression
+ * @param args - The additional arguments to override or specify for {@link QueryCommandInput}
+ * @returns A promise that resolves to the output of {@link QueryCommandOutput}
+ *
+ * @example
+ * Query a single item using a key condition
+ * ```javascript
+ * const booksResponse = await query("#PK = :PK and begins_with(#SK, :SK)", {
+ *   PK: "User/1",
+ *   SK: "Book/",
+ * });
+ * ```
+ */
 export declare function query(keyCondition: string, key: any, args?: Partial<QueryCommandInput>): Promise<QueryCommandOutput>;
+/**
+ * Query multiple items from the DynamoDB table using a key condition and unmarshalls the result.
+ * @param keyCondition - The condition for the key in DynamoDB QueryCommand.
+ * @param key - Definitions for the attributes used in keyCondition and FilterExpression
+ * @param args - The additional arguments to override or specify for {@link QueryCommandInput}
+ * @returns A promise that resolves to an array of unmarshalled items.
+ *
+ * @example
+ * Query multiple items using a key condition
+ * ```javascript
+ * const books = await queryItems("#PK = :PK and begins_with(#SK, :SK)", {
+ *   PK: "User/1",
+ *   SK: "Book/",
+ * });
+ * ```
+ */
 export declare function queryItems(keyCondition: string, key: any, args?: Partial<QueryCommandInput>): Promise<Record<string, any>[]>;
+/**
+ * Query all items from the DynamoDB table using a key condition and unmarshalls the result.
+ * This function retries until all items are retrieved due to the AWS limit of 1MB per query.
+ * @param keyCondition - The condition for the key in DynamoDB QueryCommand.
+ * @param key - Definitions for the attributes used in keyCondition and FilterExpression
+ * @param args - The additional arguments to override or specify for {@link QueryCommandInput}
+ * @returns A promise that resolves to an array of unmarshalled items.
+ *
+ * @example
+ * Query all items using a key condition
+ * ```javascript
+ * const allBooks = await queryAllItems("#PK = :PK and begins_with(#SK, :SK)", {
+ *   PK: "User/1",
+ *   SK: "Book/",
+ * });
+ * const booksWithFilter = await queryAllItems(
+ *   "#PK = :PK and begins_with(#SK, :SK)", // keyCondition
+ *   {
+ *     // definition for all attributes
+ *     PK: "User/1",
+ *     SK: "Book/",
+ *     from: 1950,
+ *     to: 2000,
+ *   },
+ *   // additional args with FilterExpression for example
+ *   { FilterExpression: "#released BETWEEN :from AND :to" }
+ * );
+ * ```
+ */
 export declare function queryAllItems(keyCondition: string, key: any, args?: Partial<QueryCommandInput>): Promise<Record<string, any>[]>;
+/**
+ * The structure for the PaginationPage type.
+ * @property number - The page number. Cannot be set manually.
+ * @property firstKey - The key for the first item on the page.
+ * @property lastKey - The key for the last item on the page.
+ */
+export type PaginationPage = {
+    number?: number;
+    firstKey: Record<string, any>;
+    lastKey: Record<string, any>;
+};
+/**
+ * The structure for the PaginationResult type.
+ * @property items - The items on the current page.
+ * @property hasPreviousPage - Whether there is a previous page.
+ * @property hasNextPage - Whether there is a next page.
+ * @property currentPage - The current page.
+ */
+export type PaginationResult = {
+    items: Record<string, any>[];
+    hasPreviousPage: boolean;
+    hasNextPage: boolean;
+    currentPage: PaginationPage;
+};
+/**
+ * The arguments for the queryPaginatedItems function.
+ * @property pageSize - The size of each page.
+ * @property direction - The direction of pagination, 'next' or 'previous'. Default is 'next'.
+ * @property currentPage - The current page.
+ */
+export interface PaginationArgs extends Partial<Omit<QueryCommandInput, "Limit">> {
+    pageSize: number;
+    direction?: "next" | "previous";
+    currentPage?: PaginationPage;
+}
+/**
+ * Query items from the DynamoDB table using a key condition in a paginated manner.
+ * @param keyCondition - The condition for the key in DynamoDB QueryCommand.
+ * @param key - Definitions for the attributes used in keyCondition and FilterExpression
+ * @param args- The pagination arguments, including pageSize and direction. {@link PaginationArgs}
+ * @returns A promise that resolves to a {@link PaginationResult}.
+ * @example
+ * Query the first page of items using a key condition
+ * ```javascript
+ * 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: { ... } }
+ * ```
+ */
+export declare function queryPaginatedItems(keyCondition: string, key: any, args: PaginationArgs): Promise<PaginationResult>;

package/dist/operations/query.js

@@ -1,8 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.queryAllItems = exports.queryItems = exports.query = void 0;
+exports.queryPaginatedItems = exports.queryAllItems = exports.queryItems = exports.query = void 0;
 const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
 const lib_1 = require("../lib");
+/**
+ * The internal _query function that executes the QueryCommand with given conditions and arguments.
+ * @param keyCondition - The condition for the key in DynamoDB QueryCommand.
+ * @param key - Definitions for the attributes used in keyCondition and FilterExpression
+ * @param args - The additional arguments to override or specify for {@link QueryCommandInput}
+ * @returns A promise that resolves to the output of {@link QueryCommandOutput}
+ * @private
+ */
 async function _query(keyCondition, key, args = {}) {
     args = (0, lib_1.withFixes)(args);
     return (0, lib_1.getClient)().send(new client_dynamodb_1.QueryCommand({
@@ -19,10 +27,42 @@ async function _query(keyCondition, key, args = {}) {
         TableName: args?.TableName || (0, lib_1.getDefaultTable)(),
     }));
 }
+/**
+ * Query a single item in a DynamoDB table using a key condition.
+ * @param keyCondition - The condition for the key in DynamoDB QueryCommand.
+ * @param key - Definitions for the attributes used in keyCondition and FilterExpression
+ * @param args - The additional arguments to override or specify for {@link QueryCommandInput}
+ * @returns A promise that resolves to the output of {@link QueryCommandOutput}
+ *
+ * @example
+ * Query a single item using a key condition
+ * ```javascript
+ * const booksResponse = await query("#PK = :PK and begins_with(#SK, :SK)", {
+ *   PK: "User/1",
+ *   SK: "Book/",
+ * });
+ * ```
+ */
 async function query(keyCondition, key, args) {
     return _query(keyCondition, key, (0, lib_1.withDefaults)(args, "query"));
 }
 exports.query = query;
+/**
+ * Query multiple items from the DynamoDB table using a key condition and unmarshalls the result.
+ * @param keyCondition - The condition for the key in DynamoDB QueryCommand.
+ * @param key - Definitions for the attributes used in keyCondition and FilterExpression
+ * @param args - The additional arguments to override or specify for {@link QueryCommandInput}
+ * @returns A promise that resolves to an array of unmarshalled items.
+ *
+ * @example
+ * Query multiple items using a key condition
+ * ```javascript
+ * const books = await queryItems("#PK = :PK and begins_with(#SK, :SK)", {
+ *   PK: "User/1",
+ *   SK: "Book/",
+ * });
+ * ```
+ */
 async function queryItems(keyCondition, key, args = {}) {
     args = (0, lib_1.withDefaults)(args, "queryItems");
     return _query(keyCondition, key, args).then((res) => (res?.Items || [])
@@ -30,23 +70,166 @@ async function queryItems(keyCondition, key, args = {}) {
         .filter((item) => item));
 }
 exports.queryItems = queryItems;
+/**
+ * Query all items from the DynamoDB table using a key condition and unmarshalls the result.
+ * This function retries until all items are retrieved due to the AWS limit of 1MB per query.
+ * @param keyCondition - The condition for the key in DynamoDB QueryCommand.
+ * @param key - Definitions for the attributes used in keyCondition and FilterExpression
+ * @param args - The additional arguments to override or specify for {@link QueryCommandInput}
+ * @returns A promise that resolves to an array of unmarshalled items.
+ *
+ * @example
+ * Query all items using a key condition
+ * ```javascript
+ * const allBooks = await queryAllItems("#PK = :PK and begins_with(#SK, :SK)", {
+ *   PK: "User/1",
+ *   SK: "Book/",
+ * });
+ * const booksWithFilter = await queryAllItems(
+ *   "#PK = :PK and begins_with(#SK, :SK)", // keyCondition
+ *   {
+ *     // definition for all attributes
+ *     PK: "User/1",
+ *     SK: "Book/",
+ *     from: 1950,
+ *     to: 2000,
+ *   },
+ *   // additional args with FilterExpression for example
+ *   { FilterExpression: "#released BETWEEN :from AND :to" }
+ * );
+ * ```
+ */
 async function queryAllItems(keyCondition, key, args = {}) {
     args = (0, lib_1.withDefaults)(args, "queryAllItems");
     let data = await _query(keyCondition, key, args);
     while (data.LastEvaluatedKey) {
-        if (data.LastEvaluatedKey) {
+        if (!Object.hasOwn(args, "Limit") || data.Items.length < args?.Limit) {
             let helper = await _query(keyCondition, key, {
                 ...args,
                 ExclusiveStartKey: data.LastEvaluatedKey,
             });
-            if (helper?.Items && data?.Items) {
+            if (helper?.Items) {
                 data.Items.push(...helper.Items);
             }
-            data && (data.LastEvaluatedKey = helper.LastEvaluatedKey);
+            else {
+                break;
+            }
+            data.LastEvaluatedKey = helper.LastEvaluatedKey;
+        }
+        else {
+            break;
         }
     }
     return (data?.Items || [])
         .map((item) => item && (0, lib_1.unmarshallWithOptions)(item))
-        .filter((item) => item);
+        .filter(Boolean);
 }
 exports.queryAllItems = queryAllItems;
+/**
+ * Query items from the DynamoDB table using a key condition in a paginated manner.
+ * @param keyCondition - The condition for the key in DynamoDB QueryCommand.
+ * @param key - Definitions for the attributes used in keyCondition and FilterExpression
+ * @param args- The pagination arguments, including pageSize and direction. {@link PaginationArgs}
+ * @returns A promise that resolves to a {@link PaginationResult}.
+ * @example
+ * Query the first page of items using a key condition
+ * ```javascript
+ * 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: { ... } }
+ * ```
+ */
+async function queryPaginatedItems(keyCondition, key, args) {
+    args = (0, lib_1.withDefaults)(args, "queryPaginatedItems");
+    const pageSize = args.pageSize;
+    const direction = args.direction || "next";
+    const currentPage = args.currentPage;
+    delete args.pageSize;
+    delete args.direction;
+    delete args.currentPage;
+    const queryArgs = {
+        ...args,
+        Limit: pageSize,
+        ScanIndexForward: direction === "next",
+    };
+    let newPageNumber;
+    switch (direction) {
+        case "next":
+            if (currentPage?.lastKey) {
+                queryArgs.ExclusiveStartKey = (0, lib_1.marshallWithOptions)(currentPage.lastKey);
+            }
+            newPageNumber = (currentPage?.number || 0) + 1;
+            break;
+        case "previous":
+            if (currentPage?.firstKey) {
+                queryArgs.ExclusiveStartKey = (0, lib_1.marshallWithOptions)(currentPage.firstKey);
+            }
+            newPageNumber = (currentPage?.number || 2) - 1;
+            break;
+    }
+    let data = await _query(keyCondition, key, queryArgs);
+    // Assume schema for either given index or the table's schema
+    const keyAttributes = Object.keys(data.LastEvaluatedKey || queryArgs.ExclusiveStartKey || {});
+    while (data.LastEvaluatedKey) {
+        if (data.Items.length < pageSize) {
+            let helper = await _query(keyCondition, key, {
+                ...queryArgs,
+                ExclusiveStartKey: data.LastEvaluatedKey,
+            });
+            if (helper?.Items) {
+                data.Items.push(...helper.Items);
+            }
+            else {
+                break;
+            }
+            data.LastEvaluatedKey = helper.LastEvaluatedKey;
+        }
+        else {
+            break;
+        }
+    }
+    let hasNextPage = direction === "previous" ||
+        // If pagination matches exactly with total items, dynamodb still returns a LastEvaluatedKey even tho next page is empty
+        // Therefore we check if the next page actually has items
+        (!!data.LastEvaluatedKey &&
+            (await _query(keyCondition, key, {
+                ...queryArgs,
+                Limit: 1,
+                ExclusiveStartKey: data.LastEvaluatedKey,
+            }).then(({ Count }) => Count > 0)));
+    let hasPreviousPage = newPageNumber > 1;
+    data.Items = data.Items || [];
+    direction === "previous" && data.Items.reverse();
+    const applySchema = (item) => {
+        return keyAttributes.reduce((acc, key) => ({ ...acc, [key]: item[key] }), {});
+    };
+    const firstItem = data.Items?.[0];
+    const lastItem = data.Items?.[data.Items?.length - 1];
+    const firstKey = firstItem && (0, lib_1.unmarshallWithOptions)(applySchema(firstItem));
+    const lastKey = lastItem && (0, lib_1.unmarshallWithOptions)(applySchema(lastItem));
+    const items = data.Items.map((item) => item && (0, lib_1.unmarshallWithOptions)(item)).filter(Boolean);
+    return {
+        items,
+        hasPreviousPage,
+        hasNextPage,
+        currentPage: {
+            number: newPageNumber,
+            firstKey,
+            lastKey,
+        },
+    };
+}
+exports.queryPaginatedItems = queryPaginatedItems;

package/dist/operations/update.d.ts

@@ -1,3 +1,49 @@
 import { UpdateItemCommandInput, UpdateItemCommandOutput } from "@aws-sdk/client-dynamodb";
+/**
+ * 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 }
+ * ```
+ */
 export declare function updateItem(key: any, data: any, args?: Partial<UpdateItemCommandInput>): Promise<undefined | Record<string, any>>;
+/**
+ * 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"]);
+ * ```
+ */
 export declare function removeAttributes(key: any, attributes: string[], args?: Partial<UpdateItemCommandInput>): Promise<UpdateItemCommandOutput>;

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(", ");