@moicky/dynamodb 2.0.1 → 2.2.0

package/dist/lib/client.d.ts

@@ -1,3 +1,11 @@
 import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+/**
+ * Initializes the {@link DynamoDBClient} to use for all operations.
+ * @param newClient - The new {@link DynamoDBClient} to use
+ */
 export declare const initClient: (newClient: DynamoDBClient) => void;
+/**
+ * Returns the current {@link DynamoDBClient} used for all operations.
+ * @returns The current {@link DynamoDBClient}
+ */
 export declare const getClient: () => DynamoDBClient;

package/dist/lib/client.js

@@ -10,9 +10,17 @@ const defaultTable = process.env.DYNAMODB_TABLE;
 if (defaultTable) {
     (0, schemas_1.initSchema)({ [defaultTable]: (0, schemas_1.getDefaultTableSchema)() });
 }
+/**
+ * Initializes the {@link DynamoDBClient} to use for all operations.
+ * @param newClient - The new {@link DynamoDBClient} to use
+ */
 const initClient = (newClient) => {
     client = newClient;
 };
 exports.initClient = initClient;
+/**
+ * Returns the current {@link DynamoDBClient} used for all operations.
+ * @returns The current {@link DynamoDBClient}
+ */
 const getClient = () => client;
 exports.getClient = getClient;

package/dist/lib/defaultArguments.d.ts

@@ -1,10 +1,11 @@
-import { deleteItem, deleteItems, getAllItems, getItem, getItems, itemExists, putItem, putItems, query, queryAllItems, queryItems, removeAttributes, updateItem } from "../operations";
+import { deleteItem, deleteItems, getAllItems, getItem, getItems, itemExists, putItem, putItems, query, queryAllItems, queryItems, queryPaginatedItems, removeAttributes, updateItem } from "../operations";
 export interface OperationArguments {
     deleteItem?: Parameters<typeof deleteItem>[1];
     deleteItems?: Parameters<typeof deleteItems>[1];
     getItem?: Parameters<typeof getItem>[1];
     getItems?: Parameters<typeof getItems>[1];
     getAllItems?: Parameters<typeof getAllItems>[0];
+    queryPaginatedItems?: Parameters<typeof queryPaginatedItems>[2];
     itemExists?: Parameters<typeof itemExists>[1];
     putItem?: Parameters<typeof putItem>[1];
     putItems?: Parameters<typeof putItems>[1];
@@ -14,6 +15,37 @@ export interface OperationArguments {
     updateItem?: Parameters<typeof updateItem>[2];
     removeAttributes?: Parameters<typeof removeAttributes>[2];
 }
+/**
+ * Initializes the default arguments to use for all operations.
+ * @param args - The new default arguments to use for all operations {@link OperationArguments}
+ * @returns void
+ * @example
+ * Enable consistent reads for all operations which support it:
+ * ```javascript
+ * initDefaultArguments({
+ *   getItem: { ConsistentRead: true },
+ *   getAllItems: { ConsistentRead: true },
+ *   queryPaginatedItems: { ConsistentRead: true, pageSize: 100 },
+ *
+ *   itemExists: { ConsistentRead: true },
+ *
+ *   query: { ConsistentRead: true },
+ *   queryItems: { ConsistentRead: true },
+ *   queryAllItems: { ConsistentRead: true },
+ * });
+ * ```
+ */
 export declare const initDefaultArguments: (args: OperationArguments) => void;
+/**
+ * Returns the current default arguments used for all operations.
+ * @returns The current default arguments {@link OperationArguments}
+ */
 export declare const getDefaultArguments: () => OperationArguments;
+/**
+ * Returns the current default arguments used for all operations.
+ * @param args - The arguments to override the default arguments with
+ * @param operation - The operation to get the default arguments for
+ * @returns The merged arguments
+ * @private
+ */
 export declare const withDefaults: <T extends keyof OperationArguments>(args: Partial<OperationArguments[T]>, operation: T) => OperationArguments[T];

package/dist/lib/defaultArguments.js

@@ -2,12 +2,43 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.withDefaults = exports.getDefaultArguments = exports.initDefaultArguments = void 0;
 let defaultArguments = {};
+/**
+ * Initializes the default arguments to use for all operations.
+ * @param args - The new default arguments to use for all operations {@link OperationArguments}
+ * @returns void
+ * @example
+ * Enable consistent reads for all operations which support it:
+ * ```javascript
+ * initDefaultArguments({
+ *   getItem: { ConsistentRead: true },
+ *   getAllItems: { ConsistentRead: true },
+ *   queryPaginatedItems: { ConsistentRead: true, pageSize: 100 },
+ *
+ *   itemExists: { ConsistentRead: true },
+ *
+ *   query: { ConsistentRead: true },
+ *   queryItems: { ConsistentRead: true },
+ *   queryAllItems: { ConsistentRead: true },
+ * });
+ * ```
+ */
 const initDefaultArguments = (args) => {
     defaultArguments = args;
 };
 exports.initDefaultArguments = initDefaultArguments;
+/**
+ * Returns the current default arguments used for all operations.
+ * @returns The current default arguments {@link OperationArguments}
+ */
 const getDefaultArguments = () => defaultArguments;
 exports.getDefaultArguments = getDefaultArguments;
+/**
+ * Returns the current default arguments used for all operations.
+ * @param args - The arguments to override the default arguments with
+ * @param operation - The operation to get the default arguments for
+ * @returns The merged arguments
+ * @private
+ */
 const withDefaults = (args, operation) => {
     return {
         ...defaultArguments[operation],

package/dist/lib/fixes.d.ts

@@ -1,5 +1,22 @@
 import { QueryCommandInput, ScanCommandInput } from "@aws-sdk/client-dynamodb";
 import { marshall, marshallOptions, unmarshall, unmarshallOptions } from "@aws-sdk/util-dynamodb";
+/**
+ * DynamoDBFixes is a collection of fixes for DynamoDB.
+ * @property disableConsistantReadWhenUsingIndexes - Disables ConsistentRead when using indexes.
+ * @property marshallOptions - Options to pass to the [marshall](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/interfaces/_aws_sdk_util_dynamodb.marshallOptions.html) function.
+ * @property unmarshallOptions - Options to pass to the [unmarshall](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/interfaces/_aws_sdk_util_dynamodb.unmarshallOptions.html) function.
+ * @example
+ * ```javascript
+ * initFixes({
+ *   disableConsistantReadWhenUsingIndexes: {
+ *     enabled: true, // default,
+ *
+ *     // Won't disable ConsistantRead if IndexName is specified here.
+ *     stillUseOnLocalIndexes: ["localIndexName1", "localIndexName1"],
+ *   },
+ * });
+ * ```
+ */
 export declare interface DynamoDBFixes {
     disableConsistantReadWhenUsingIndexes?: {
         enabled: boolean;
@@ -8,9 +25,42 @@ export declare interface DynamoDBFixes {
     marshallOptions?: marshallOptions;
     unmarshallOptions?: unmarshallOptions;
 }
+/**
+ * Initializes the {@link DynamoDBFixes} to use for all operations.
+ * @param fixesConfig - The new {@link DynamoDBFixes} to use
+ * @returns void
+ */
 export declare const initFixes: (fixesConfig: DynamoDBFixes) => void;
+/**
+ * Returns the current {@link DynamoDBFixes} used for all operations.
+ * @returns The current {@link DynamoDBFixes}
+ * @private
+ */
 export declare const getFixes: () => DynamoDBFixes;
+/**
+ * Returns the current {@link DynamoDBFixes} used for all operations.
+ * @param args - The arguments to override the default arguments with
+ * @returns The merged arguments
+ * @private
+ */
 export declare const withFixes: (args: Partial<QueryCommandInput> | Partial<ScanCommandInput>) => Partial<QueryCommandInput> | Partial<ScanCommandInput>;
+/**
+ * Returns the current {@link DynamoDBFixes} used for all operations.
+ * @returns The current {@link DynamoDBFixes}
+ * @private
+ */
 export declare const getDefaultFixes: () => DynamoDBFixes;
+/**
+ * Returns the current {@link DynamoDBFixes} used for all operations.
+ * @param input - The input to marshall
+ * @returns The marshalled input
+ * @private
+ */
 export declare const marshallWithOptions: (input: Parameters<typeof marshall>[0]) => Record<string, import("@aws-sdk/client-dynamodb").AttributeValue>;
+/**
+ * Returns the current {@link DynamoDBFixes} used for all operations.
+ * @param input - The input to unmarshall
+ * @returns The unmarshalled input
+ * @private
+ */
 export declare const unmarshallWithOptions: (input: Parameters<typeof unmarshall>[0]) => Record<string, any>;

package/dist/lib/fixes.js

@@ -8,10 +8,20 @@ const defaults = Object.freeze({
     },
 });
 let fixes = defaults;
+/**
+ * Initializes the {@link DynamoDBFixes} to use for all operations.
+ * @param fixesConfig - The new {@link DynamoDBFixes} to use
+ * @returns void
+ */
 const initFixes = (fixesConfig) => {
     fixes = fixesConfig;
 };
 exports.initFixes = initFixes;
+/**
+ * Returns the current {@link DynamoDBFixes} used for all operations.
+ * @returns The current {@link DynamoDBFixes}
+ * @private
+ */
 const getFixes = () => fixes;
 exports.getFixes = getFixes;
 const handleIndex = (args) => {
@@ -22,14 +32,37 @@ const handleIndex = (args) => {
         args.ConsistentRead = false;
     }
 };
+/**
+ * Returns the current {@link DynamoDBFixes} used for all operations.
+ * @param args - The arguments to override the default arguments with
+ * @returns The merged arguments
+ * @private
+ */
 const withFixes = (args) => {
     handleIndex(args);
     return args;
 };
 exports.withFixes = withFixes;
+/**
+ * Returns the current {@link DynamoDBFixes} used for all operations.
+ * @returns The current {@link DynamoDBFixes}
+ * @private
+ */
 const getDefaultFixes = () => defaults;
 exports.getDefaultFixes = getDefaultFixes;
+/**
+ * Returns the current {@link DynamoDBFixes} used for all operations.
+ * @param input - The input to marshall
+ * @returns The marshalled input
+ * @private
+ */
 const marshallWithOptions = (input) => (0, util_dynamodb_1.marshall)(input, fixes.marshallOptions);
 exports.marshallWithOptions = marshallWithOptions;
+/**
+ * Returns the current {@link DynamoDBFixes} used for all operations.
+ * @param input - The input to unmarshall
+ * @returns The unmarshalled input
+ * @private
+ */
 const unmarshallWithOptions = (input) => (0, util_dynamodb_1.unmarshall)(input, fixes.unmarshallOptions);
 exports.unmarshallWithOptions = unmarshallWithOptions;

package/dist/lib/schemas.d.ts

@@ -1,13 +1,44 @@
+/**
+ * @property {string} hash - The name of the hash key.
+ * @property {string} [range] - The name of the range key. Only required if the table has a range key.
+ */
 export declare interface KeySchema {
     hash: string;
     range?: string;
 }
+/**
+ * @property {string} tableName - The name of the table.
+ */
 export declare interface KeySchemaCollection {
     [tableName: string]: KeySchema;
 }
+/**
+ * Initializes the {@link KeySchemaCollection} to use for all operations.
+ * @param schema - The new {@link KeySchemaCollection} to use
+ * @returns The new {@link KeySchemaCollection}
+ */
 export declare const initSchema: (schema: KeySchemaCollection) => KeySchemaCollection;
+/**
+ * Validates the {@link KeySchemaCollection} to use for all operations.
+ * @param schema - The {@link KeySchemaCollection} to validate
+ * @returns true if the schema is valid
+ */
 export declare const validateSchema: (schema: KeySchemaCollection) => boolean;
+/**
+ * Returns the first table name from the {@link KeySchemaCollection}.
+ */
 export declare const getDefaultTable: () => string;
+/**
+ * Returns the {@link KeySchema} for the given or default table.
+ */
 export declare const getTableSchema: (tableName?: string) => KeySchema;
+/**
+ * Returns the default {@link KeySchema}.
+ * @returns The default {@link KeySchema}
+ */
 export declare const getDefaultTableSchema: () => KeySchema;
+/**
+ * Returns whether the {@link KeySchemaCollection} has been initialized.
+ * @returns true if the {@link KeySchemaCollection} has been initialized
+ */
 export declare const isInitialized: () => boolean;

package/dist/lib/schemas.js

@@ -3,6 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isInitialized = exports.getDefaultTableSchema = exports.getTableSchema = exports.getDefaultTable = exports.validateSchema = exports.initSchema = void 0;
 let initialized = false;
 let tablesSchema = {};
+/**
+ * Initializes the {@link KeySchemaCollection} to use for all operations.
+ * @param schema - The new {@link KeySchemaCollection} to use
+ * @returns The new {@link KeySchemaCollection}
+ */
 const initSchema = (schema) => {
     if (!(0, exports.validateSchema)(schema)) {
         throw new Error("[@moicky/dynamodb]: Invalid schema");
@@ -19,6 +24,11 @@ const initSchema = (schema) => {
     return tablesSchema;
 };
 exports.initSchema = initSchema;
+/**
+ * Validates the {@link KeySchemaCollection} to use for all operations.
+ * @param schema - The {@link KeySchemaCollection} to validate
+ * @returns true if the schema is valid
+ */
 const validateSchema = (schema) => {
     const tables = Object.keys(schema);
     if (tables.length === 0) {
@@ -40,6 +50,9 @@ const validateSchema = (schema) => {
     return true;
 };
 exports.validateSchema = validateSchema;
+/**
+ * Returns the first table name from the {@link KeySchemaCollection}.
+ */
 const getDefaultTable = () => {
     if (!initialized) {
         throw new Error("[@moicky/dynamodb]: Schema not initialized");
@@ -47,6 +60,9 @@ const getDefaultTable = () => {
     return Object.keys(tablesSchema)[0];
 };
 exports.getDefaultTable = getDefaultTable;
+/**
+ * Returns the {@link KeySchema} for the given or default table.
+ */
 const getTableSchema = (tableName) => {
     if (!initialized) {
         throw new Error("[@moicky/dynamodb]: Schema not initialized");
@@ -55,9 +71,17 @@ const getTableSchema = (tableName) => {
     return tablesSchema[table] || (0, exports.getDefaultTableSchema)();
 };
 exports.getTableSchema = getTableSchema;
+/**
+ * Returns the default {@link KeySchema}.
+ * @returns The default {@link KeySchema}
+ */
 const getDefaultTableSchema = () => {
     return { hash: "PK", range: "SK" };
 };
 exports.getDefaultTableSchema = getDefaultTableSchema;
+/**
+ * Returns whether the {@link KeySchemaCollection} has been initialized.
+ * @returns true if the {@link KeySchemaCollection} has been initialized
+ */
 const isInitialized = () => initialized;
 exports.isInitialized = isInitialized;

package/dist/operations/delete.d.ts

@@ -1,5 +1,66 @@
 import { BatchWriteItemCommandInput, DeleteItemCommandInput, DeleteItemCommandOutput } from "@aws-sdk/client-dynamodb";
+/**
+ * Deletes an item from 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 delete.
+ * @param args - The additional arguments to override or specify for {@link DeleteItemCommandInput}
+ * @returns A promise that resolves to the output of {@link DeleteItemCommandOutput}
+ *
+ * @example
+ * Delete a single item in default table
+ * ```javascript
+ * await deleteItem({
+ *   PK: "User/1",
+ *   SK: "Book/1",
+ *   // fields which are not part of the key schema will be removed
+ *   title: "The Great Gatsby",
+ *   author: "F. Scott Fitzgerald",
+ *   released: 1925,
+ * });
+ * ```
+ * @example
+ * Delete a single item in a different table
+ * ```javascript
+ * await deleteItem(
+ *   { PK: "User/1", SK: "Book/1" },
+ *   { TableName: "AnotherTable" }
+ * );
+ * ```
+ */
 export declare function deleteItem(key: any, args?: Partial<DeleteItemCommandInput>): Promise<DeleteItemCommandOutput>;
-export declare function deleteItems(keys: any[], args?: Partial<BatchWriteItemCommandInput & {
+type DeleteItemsArgs = Partial<BatchWriteItemCommandInput & {
     TableName?: string;
-}>, retry?: number): Promise<void>;
+}>;
+/**
+ * Deletes unlimited items from the DynamoDB table using their key schema.
+ * @param keys - The items with at least the partition key and the sort key (if applicable) of the items to delete.
+ * @param args - The additional arguments to override or specify for {@link DeleteItemsArgs}
+ * @returns A promise that resolves to void
+ *
+ * @example
+ * Delete items in default table
+ * ```javascript
+ * await deleteItems([
+ *   // fields which are not part of the key schema will be removed
+ *   { PK: "User/1", SK: "Book/1", title: "The Great Gatsby", released: 1925 },
+ *   { PK: "User/1", SK: "Book/2" },
+ *   { PK: "User/1", SK: "Book/3" },
+ *   // ... infinite more items (will be grouped into batches of 25 due to aws limit)
+ *   // and retried up to 3 times
+ * ]);
+ * ```
+ * @example
+ * Delete items in a different table
+ * ```javascript
+ * await deleteItems(
+ *   [
+ *     // fields which are not part of the key schema will be removed
+ *     { PK: "User/1", SK: "Book/1", title: "The Great Gatsby", released: 1925 },
+ *     { PK: "User/1", SK: "Book/2" },
+ *     { PK: "User/1", SK: "Book/3" },
+ *   ],
+ *   { TableName: "AnotherTable" }
+ * );
+ * ```
+ */
+export declare function deleteItems(keys: any[], args?: DeleteItemsArgs, retry?: number): Promise<void>;
+export {};

package/dist/operations/delete.js

@@ -3,6 +3,33 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.deleteItems = exports.deleteItem = void 0;
 const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
 const lib_1 = require("../lib");
+/**
+ * Deletes an item from 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 delete.
+ * @param args - The additional arguments to override or specify for {@link DeleteItemCommandInput}
+ * @returns A promise that resolves to the output of {@link DeleteItemCommandOutput}
+ *
+ * @example
+ * Delete a single item in default table
+ * ```javascript
+ * await deleteItem({
+ *   PK: "User/1",
+ *   SK: "Book/1",
+ *   // fields which are not part of the key schema will be removed
+ *   title: "The Great Gatsby",
+ *   author: "F. Scott Fitzgerald",
+ *   released: 1925,
+ * });
+ * ```
+ * @example
+ * Delete a single item in a different table
+ * ```javascript
+ * await deleteItem(
+ *   { PK: "User/1", SK: "Book/1" },
+ *   { TableName: "AnotherTable" }
+ * );
+ * ```
+ */
 async function deleteItem(key, args = {}) {
     return (0, lib_1.getClient)().send(new client_dynamodb_1.DeleteItemCommand({
         Key: (0, lib_1.stripKey)(key, args),
@@ -11,6 +38,38 @@ async function deleteItem(key, args = {}) {
     }));
 }
 exports.deleteItem = deleteItem;
+/**
+ * Deletes unlimited items from the DynamoDB table using their key schema.
+ * @param keys - The items with at least the partition key and the sort key (if applicable) of the items to delete.
+ * @param args - The additional arguments to override or specify for {@link DeleteItemsArgs}
+ * @returns A promise that resolves to void
+ *
+ * @example
+ * Delete items in default table
+ * ```javascript
+ * await deleteItems([
+ *   // fields which are not part of the key schema will be removed
+ *   { PK: "User/1", SK: "Book/1", title: "The Great Gatsby", released: 1925 },
+ *   { PK: "User/1", SK: "Book/2" },
+ *   { PK: "User/1", SK: "Book/3" },
+ *   // ... infinite more items (will be grouped into batches of 25 due to aws limit)
+ *   // and retried up to 3 times
+ * ]);
+ * ```
+ * @example
+ * Delete items in a different table
+ * ```javascript
+ * await deleteItems(
+ *   [
+ *     // fields which are not part of the key schema will be removed
+ *     { PK: "User/1", SK: "Book/1", title: "The Great Gatsby", released: 1925 },
+ *     { PK: "User/1", SK: "Book/2" },
+ *     { PK: "User/1", SK: "Book/3" },
+ *   ],
+ *   { TableName: "AnotherTable" }
+ * );
+ * ```
+ */
 async function deleteItems(keys, args = {}, retry = 0) {
     args = (0, lib_1.withDefaults)(args, "deleteItems");
     const uniqueKeys = Object.values(keys.reduce((acc, key) => {

package/dist/operations/get.d.ts

@@ -1,6 +1,81 @@
 import { BatchGetItemCommandInput, GetItemCommandInput, ScanCommandInput } from "@aws-sdk/client-dynamodb";
+/**
+ * Retrieves an item from 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 get.
+ * @param args - The additional arguments to override or specify for {@link GetItemCommandInput}
+ * @returns A promise that resolves to the unmarshalled item
+ *
+ * @example
+ * Get a single item
+ * ```javascript
+ * await getItem({
+ *   PK: "User/1",
+ *   SK: "Book/1",
+ *   title: "The Great Gatsby",
+ *   author: "F. Scott Fitzgerald",
+ *   released: 1925,
+ * });
+ * ```
+ * @example
+ * Get a single item in a different table
+ * ```javascript
+ * await getItem(
+ *   { PK: "User/1", SK: "Book/1" },
+ *   { TableName: "AnotherTable" }
+ * );
+ * ```
+ */
 export declare function getItem(key: any, args?: Partial<GetItemCommandInput>): Promise<Record<string, any> | undefined>;
-export declare function getItems(keys: any[], args?: Partial<BatchGetItemCommandInput & {
+type GetItemsArgs = Partial<BatchGetItemCommandInput & {
     TableName?: string;
-}>, retry?: number): Promise<Record<string, any>[]>;
+}>;
+/**
+ * Retrieves multiple items from the DynamoDB table using their key schema.
+ * @param keys - The items with at least the partition key and the sort key (if applicable) of the items to get.
+ * @param args - The additional arguments to override or specify for {@link GetItemsArgs}
+ * @returns A promise that resolves to an array of unmarshalled items
+ *
+ * @example
+ * Get items in default table
+ * ```javascript
+ * await getItems([
+ *   { PK: "User/1", SK: "Book/1", title: "The Great Gatsby", released: 1925 },
+ *   { PK: "User/1", SK: "Book/2" },
+ *   { PK: "User/1", SK: "Book/3" },
+ *   // ... infinite more items (will be grouped into batches of 100 due to aws limit) and retried up to 3 times
+ * ]);
+ * ```
+ * @example
+ * Get items in a different table
+ * ```javascript
+ * await getItems(
+ *   [
+ *     { PK: "User/1", SK: "Book/1", title: "The Great Gatsby", released: 1925 },
+ *     { PK: "User/1", SK: "Book/2" },
+ *     { PK: "User/1", SK: "Book/3" },
+ *   ],
+ *   { TableName: "AnotherTable" }
+ * );
+ * ```
+ */
+export declare function getItems(keys: any[], args?: GetItemsArgs, retry?: number): Promise<Record<string, any>[]>;
+/**
+ * Retrieves all items from the DynamoDB table.
+ * @param args - The additional arguments to override or specify for {@link ScanCommandInput}
+ * @returns A promise that resolves to an array of unmarshalled items
+ *
+ * @example
+ * Retrieve all items in default table
+ * ```javascript
+ * await getAllItems();
+ * ```
+ * @example
+ * Retrieve all items in a different table
+ * ```javascript
+ * await getAllItems(
+ *   { TableName: "AnotherTable" }
+ * );
+ * ```
+ */
 export declare function getAllItems(args?: Partial<ScanCommandInput>): Promise<Record<string, any>[]>;
+export {};

package/dist/operations/get.js

@@ -3,6 +3,32 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getAllItems = exports.getItems = exports.getItem = void 0;
 const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
 const lib_1 = require("../lib");
+/**
+ * Retrieves an item from 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 get.
+ * @param args - The additional arguments to override or specify for {@link GetItemCommandInput}
+ * @returns A promise that resolves to the unmarshalled item
+ *
+ * @example
+ * Get a single item
+ * ```javascript
+ * await getItem({
+ *   PK: "User/1",
+ *   SK: "Book/1",
+ *   title: "The Great Gatsby",
+ *   author: "F. Scott Fitzgerald",
+ *   released: 1925,
+ * });
+ * ```
+ * @example
+ * Get a single item in a different table
+ * ```javascript
+ * await getItem(
+ *   { PK: "User/1", SK: "Book/1" },
+ *   { TableName: "AnotherTable" }
+ * );
+ * ```
+ */
 async function getItem(key, args = {}) {
     args = (0, lib_1.withDefaults)(args, "getItem");
     return (0, lib_1.getClient)()
@@ -14,6 +40,35 @@ async function getItem(key, args = {}) {
         .then((res) => res?.Item && (0, lib_1.unmarshallWithOptions)(res.Item));
 }
 exports.getItem = getItem;
+/**
+ * Retrieves multiple items from the DynamoDB table using their key schema.
+ * @param keys - The items with at least the partition key and the sort key (if applicable) of the items to get.
+ * @param args - The additional arguments to override or specify for {@link GetItemsArgs}
+ * @returns A promise that resolves to an array of unmarshalled items
+ *
+ * @example
+ * Get items in default table
+ * ```javascript
+ * await getItems([
+ *   { PK: "User/1", SK: "Book/1", title: "The Great Gatsby", released: 1925 },
+ *   { PK: "User/1", SK: "Book/2" },
+ *   { PK: "User/1", SK: "Book/3" },
+ *   // ... infinite more items (will be grouped into batches of 100 due to aws limit) and retried up to 3 times
+ * ]);
+ * ```
+ * @example
+ * Get items in a different table
+ * ```javascript
+ * await getItems(
+ *   [
+ *     { PK: "User/1", SK: "Book/1", title: "The Great Gatsby", released: 1925 },
+ *     { PK: "User/1", SK: "Book/2" },
+ *     { PK: "User/1", SK: "Book/3" },
+ *   ],
+ *   { TableName: "AnotherTable" }
+ * );
+ * ```
+ */
 async function getItems(keys, args = {}, retry = 0) {
     args = (0, lib_1.withDefaults)(args, "getItems");
     // creates batches of 100 items each and performs batchGet on every batch.
@@ -68,6 +123,24 @@ async function getItems(keys, args = {}, retry = 0) {
     return keys.map((key) => resultItems[JSON.stringify((0, lib_1.stripKey)(key, { TableName }))] || undefined);
 }
 exports.getItems = getItems;
+/**
+ * Retrieves all items from the DynamoDB table.
+ * @param args - The additional arguments to override or specify for {@link ScanCommandInput}
+ * @returns A promise that resolves to an array of unmarshalled items
+ *
+ * @example
+ * Retrieve all items in default table
+ * ```javascript
+ * await getAllItems();
+ * ```
+ * @example
+ * Retrieve all items in a different table
+ * ```javascript
+ * await getAllItems(
+ *   { TableName: "AnotherTable" }
+ * );
+ * ```
+ */
 async function getAllItems(args = {}) {
     args = (0, lib_1.withFixes)((0, lib_1.withDefaults)(args, "getAllItems"));
     return (0, lib_1.getClient)()