@moicky/dynamodb 2.3.6 → 2.4.0

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./lib";
 export * from "./operations";
+export type * from "./types";

package/dist/lib/fixes.d.ts

@@ -1,5 +1,6 @@
 import { QueryCommandInput, ScanCommandInput } from "@aws-sdk/client-dynamodb";
 import { marshall, marshallOptions, unmarshall, unmarshallOptions } from "@aws-sdk/util-dynamodb";
+import { DynamoDBItem } from "../types";
 /**
  * DynamoDBFixes is a collection of fixes for DynamoDB.
  * @property disableConsistantReadWhenUsingIndexes - Disables ConsistentRead when using indexes.
@@ -63,4 +64,4 @@ export declare const marshallWithOptions: (input: Parameters<typeof marshall>[0]
  * @returns The unmarshalled input
  * @private
  */
-export declare const unmarshallWithOptions: (input: Parameters<typeof unmarshall>[0]) => Record<string, any>;
+export declare const unmarshallWithOptions: <T extends DynamoDBItem = DynamoDBItem>(input: Parameters<typeof unmarshall>[0]) => T;

package/dist/operations/delete.d.ts

@@ -1,4 +1,5 @@
 import { BatchWriteItemCommandInput, DeleteItemCommandInput, DeleteItemCommandOutput } from "@aws-sdk/client-dynamodb";
+import { DynamoDBItem } from "../types";
 /**
  * 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.
@@ -26,7 +27,7 @@ import { BatchWriteItemCommandInput, DeleteItemCommandInput, DeleteItemCommandOu
  * );
  * ```
  */
-export declare function deleteItem(key: Record<string, any>, args?: Partial<DeleteItemCommandInput>): Promise<DeleteItemCommandOutput>;
+export declare function deleteItem(key: DynamoDBItem, args?: Partial<DeleteItemCommandInput>): Promise<DeleteItemCommandOutput>;
 type DeleteItemsArgs = Partial<BatchWriteItemCommandInput & {
     TableName?: string;
 }>;
@@ -62,5 +63,5 @@ type DeleteItemsArgs = Partial<BatchWriteItemCommandInput & {
  * );
  * ```
  */
-export declare function deleteItems(keys: Record<string, any>[], args?: DeleteItemsArgs, retry?: number): Promise<void>;
+export declare function deleteItems(keys: DynamoDBItem[], args?: DeleteItemsArgs, retry?: number): Promise<void>;
 export {};

package/dist/operations/get.d.ts

@@ -1,4 +1,5 @@
 import { BatchGetItemCommandInput, GetItemCommandInput, ScanCommandInput } from "@aws-sdk/client-dynamodb";
+import { DynamoDBItem } from "../types";
 /**
  * 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.
@@ -25,7 +26,7 @@ import { BatchGetItemCommandInput, GetItemCommandInput, ScanCommandInput } from
  * );
  * ```
  */
-export declare function getItem(key: Record<string, any>, args?: Partial<GetItemCommandInput>): Promise<Record<string, any> | undefined>;
+export declare function getItem<T extends DynamoDBItem = DynamoDBItem>(key: T, args?: Partial<GetItemCommandInput>): Promise<T | undefined>;
 type GetItemsArgs = Partial<BatchGetItemCommandInput & {
     TableName?: string;
 }>;
@@ -58,7 +59,7 @@ type GetItemsArgs = Partial<BatchGetItemCommandInput & {
  * );
  * ```
  */
-export declare function getItems(keys: Record<string, any>[], args?: GetItemsArgs, retry?: number): Promise<Record<string, any>[]>;
+export declare function getItems<T extends DynamoDBItem = DynamoDBItem>(keys: T[], args?: GetItemsArgs, retry?: number): Promise<Array<T | undefined>>;
 /**
  * Retrieves all items from the DynamoDB table.
  * @param args - The additional arguments to override or specify for {@link ScanCommandInput}
@@ -77,5 +78,5 @@ export declare function getItems(keys: Record<string, any>[], args?: GetItemsArg
  * );
  * ```
  */
-export declare function getAllItems(args?: Partial<ScanCommandInput>): Promise<Record<string, any>[]>;
+export declare function getAllItems<T extends DynamoDBItem = DynamoDBItem>(args?: Partial<ScanCommandInput>): Promise<T[]>;
 export {};

package/dist/operations/get.js

@@ -114,7 +114,7 @@ async function getItems(keys, args = {}, retry = 0) {
             .then((items) => results.push(...items));
     }));
     const resultItems = results
-        .filter((i) => i)
+        .filter(Boolean)
         .reduce((acc, item) => {
         const keyString = JSON.stringify((0, lib_1.stripKey)(item, { TableName }));
         acc[keyString] = item;
@@ -148,6 +148,6 @@ async function getAllItems(args = {}) {
         ...args,
         TableName: args?.TableName || (0, lib_1.getDefaultTable)(),
     }))
-        .then((res) => res.Items.map((item) => item && (0, lib_1.unmarshallWithOptions)(item)));
+        .then((res) => res.Items.map((item) => (0, lib_1.unmarshallWithOptions)(item)));
 }
 exports.getAllItems = getAllItems;

package/dist/operations/misc.d.ts

@@ -1,4 +1,5 @@
 import { GetItemCommandInput } from "@aws-sdk/client-dynamodb";
+import { DynamoDBItem } from "../types";
 /**
  * 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.
@@ -12,7 +13,7 @@ import { GetItemCommandInput } from "@aws-sdk/client-dynamodb";
  * console.log(exists); // true / false
  * ```
  */
-export declare function itemExists(key: Record<string, any>, args?: Partial<GetItemCommandInput>): Promise<boolean>;
+export declare function itemExists(key: DynamoDBItem, 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

package/dist/operations/put.d.ts

@@ -1,4 +1,5 @@
 import { BatchWriteItemCommandInput, BatchWriteItemCommandOutput, PutItemCommandInput, PutItemCommandOutput } from "@aws-sdk/client-dynamodb";
+import { DynamoDBItem } from "../types";
 /**
  * Inserts an item into the DynamoDB table.
  * @param item - The item to insert into the table.
@@ -17,7 +18,10 @@ import { BatchWriteItemCommandInput, BatchWriteItemCommandOutput, PutItemCommand
  * });
  * ```
  */
-export declare function putItem(item: Record<string, any>, args?: Partial<PutItemCommandInput>): Promise<PutItemCommandOutput | Record<string, any>>;
+export declare function putItem<T extends DynamoDBItem>(item: T, args: Partial<PutItemCommandInput> & {
+    ReturnValues: string;
+}): Promise<T>;
+export declare function putItem<T extends DynamoDBItem, K extends Partial<PutItemCommandInput> = Partial<PutItemCommandInput>>(item: T, args?: K): Promise<PutItemCommandOutput>;
 type PutItemsArgs = Partial<BatchWriteItemCommandInput & {
     TableName?: string;
 }>;
@@ -42,5 +46,5 @@ type PutItemsArgs = Partial<BatchWriteItemCommandInput & {
  * ]);
  * ```
  */
-export declare function putItems(items: Record<string, any>[], args?: PutItemsArgs, retry?: number): Promise<BatchWriteItemCommandOutput[]>;
+export declare function putItems(items: DynamoDBItem[], args?: PutItemsArgs, retry?: number): Promise<BatchWriteItemCommandOutput[]>;
 export {};

package/dist/operations/put.js

@@ -3,36 +3,20 @@ 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 item - 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(item, args = {}) {
-    args = (0, lib_1.withDefaults)(args, "putItem");
+async function putItem(item, args) {
+    const argsWithDefaults = (0, lib_1.withDefaults)(args || {}, "putItem");
     if (!Object.keys(item).includes("createdAt")) {
         item.createdAt = Date.now();
     }
     return (0, lib_1.getClient)()
         .send(new client_dynamodb_1.PutItemCommand({
         Item: (0, lib_1.marshallWithOptions)(item),
-        ...args,
-        TableName: args?.TableName || (0, lib_1.getDefaultTable)(),
+        ...argsWithDefaults,
+        TableName: argsWithDefaults?.TableName || (0, lib_1.getDefaultTable)(),
     }))
-        .then((res) => args?.ReturnValues ? (0, lib_1.unmarshallWithOptions)(res?.Attributes) : res);
+        .then((res) => argsWithDefaults?.ReturnValues
+        ? (0, lib_1.unmarshallWithOptions)(res?.Attributes)
+        : res);
 }
 exports.putItem = putItem;
 /**

package/dist/operations/query.d.ts

@@ -1,4 +1,5 @@
 import { QueryCommandInput, QueryCommandOutput } from "@aws-sdk/client-dynamodb";
+import { DynamoDBItem } from "../types";
 /**
  * Query a single item in a DynamoDB table using a key condition.
  * @param keyCondition - The condition for the key in DynamoDB QueryCommand.
@@ -32,7 +33,7 @@ export declare function query(keyCondition: string, key: Record<string, any>, ar
  * });
  * ```
  */
-export declare function queryItems(keyCondition: string, key: Record<string, any>, args?: Partial<QueryCommandInput>): Promise<Record<string, any>[]>;
+export declare function queryItems<T extends DynamoDBItem = DynamoDBItem>(keyCondition: string, key: Record<string, any>, args?: Partial<QueryCommandInput>): Promise<T[]>;
 /**
  * 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.
@@ -62,7 +63,7 @@ export declare function queryItems(keyCondition: string, key: Record<string, any
  * );
  * ```
  */
-export declare function queryAllItems(keyCondition: string, key: Record<string, any>, args?: Partial<QueryCommandInput>): Promise<Record<string, any>[]>;
+export declare function queryAllItems<T extends DynamoDBItem = DynamoDBItem>(keyCondition: string, key: Record<string, any>, args?: Partial<QueryCommandInput>): Promise<T[]>;
 /**
  * The structure for the PaginationPage type.
  * @property number - The page number. Cannot be set manually.
@@ -81,8 +82,8 @@ export type PaginationPage = {
  * @property hasNextPage - Whether there is a next page.
  * @property currentPage - The current page.
  */
-export type PaginationResult = {
-    items: Record<string, any>[];
+export type PaginationResult<T extends DynamoDBItem = DynamoDBItem> = {
+    items: T[];
     hasPreviousPage: boolean;
     hasNextPage: boolean;
     currentPage: PaginationPage;
@@ -125,4 +126,4 @@ export interface PaginationArgs extends Partial<Omit<QueryCommandInput, "Limit">
  * // currentPage: { number: 2, firstKey: { ... }, lastKey: { ... } }
  * ```
  */
-export declare function queryPaginatedItems(keyCondition: string, key: Record<string, any>, args: PaginationArgs): Promise<PaginationResult>;
+export declare function queryPaginatedItems<T extends DynamoDBItem = DynamoDBItem>(keyCondition: string, key: Record<string, any>, args: PaginationArgs): Promise<PaginationResult<T>>;

package/dist/operations/query.js

@@ -67,7 +67,7 @@ async function queryItems(keyCondition, key, args = {}) {
     args = (0, lib_1.withDefaults)(args, "queryItems");
     return _query(keyCondition, key, args).then((res) => (res?.Items || [])
         .map((item) => item && (0, lib_1.unmarshallWithOptions)(item))
-        .filter((item) => item));
+        .filter(Boolean));
 }
 exports.queryItems = queryItems;
 /**

package/dist/operations/transactGetItems.d.ts

@@ -1,4 +1,5 @@
 import { Get, TransactGetItemsCommandInput } from "@aws-sdk/client-dynamodb";
+import { DynamoDBItem } from "../types";
 /**
  * Performs a TransactGetItems operation against DynamoDB. This allows you to retrieve many items at once.
  * @param keys - Array of items to retrieve. Each item requires a `key` property, with at least the partition and the sort key (according to the table definition).
@@ -34,9 +35,9 @@ import { Get, TransactGetItemsCommandInput } from "@aws-sdk/client-dynamodb";
  * );
  * ```
  */
-export declare function transactGetItems(keys: Array<Omit<Get, "TableName" | "Key"> & {
-    key: Record<string, any>;
+export declare function transactGetItems<T extends DynamoDBItem = DynamoDBItem>(keys: Array<Omit<Get, "TableName" | "Key"> & {
+    key: T;
     TableName?: string;
 }>, args?: Partial<TransactGetItemsCommandInput & {
     TableName?: string;
-}>): Promise<Array<Record<string, any> | undefined>>;
+}>): Promise<Array<T | undefined>>;

package/dist/operations/update.d.ts

@@ -1,4 +1,5 @@
 import { UpdateItemCommandInput, UpdateItemCommandOutput } from "@aws-sdk/client-dynamodb";
+import { DynamoDBItem } from "../types";
 /**
  * Updates an item in DynamoDB. All provided fields are overwritten.
  *
@@ -31,7 +32,10 @@ import { UpdateItemCommandInput, UpdateItemCommandOutput } from "@aws-sdk/client
  * console.log(newItem); // { "PK": "User/1", "SK": "Book/1", "released": 2000 }
  * ```
  */
-export declare function updateItem(key: Record<string, any>, data: Record<string, any>, args?: Partial<UpdateItemCommandInput>): Promise<undefined | Record<string, any>>;
+export declare function updateItem<T extends DynamoDBItem>(key: T, data: Partial<T>, args: Partial<UpdateItemCommandInput>): Promise<T>;
+export declare function updateItem<T extends DynamoDBItem, K extends Partial<UpdateItemCommandInput> = Partial<UpdateItemCommandInput>>(key: T, data: Partial<T>, args?: K): Promise<K extends {
+    ReturnValues: string;
+} ? T : undefined>;
 /**
  * Removes specified attributes from an item in DynamoDB.
  *
@@ -46,4 +50,4 @@ export declare function updateItem(key: Record<string, any>, data: Record<string
  * await removeAttributes({ PK: "User/1", SK: "Book/1" }, ["description"]);
  * ```
  */
-export declare function removeAttributes(key: Record<string, any>, attributes: string[], args?: Partial<UpdateItemCommandInput>): Promise<UpdateItemCommandOutput>;
+export declare function removeAttributes<T extends DynamoDBItem = DynamoDBItem>(key: T, attributes: Array<keyof T>, args?: Partial<UpdateItemCommandInput>): Promise<UpdateItemCommandOutput>;

package/dist/operations/update.js

@@ -3,50 +3,18 @@ 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");
+async function updateItem(key, data, args) {
+    const argsWithDefaults = (0, lib_1.withDefaults)(args || {}, "updateItem");
     if (!Object.keys(data).includes("updatedAt")) {
         data.updatedAt = Date.now();
     }
-    const valuesInCondition = (0, lib_1.getAttributesFromExpression)(args?.ConditionExpression || "", ":");
-    const namesInCondition = (0, lib_1.getAttributesFromExpression)(args?.ConditionExpression || "");
+    const valuesInCondition = (0, lib_1.getAttributesFromExpression)(argsWithDefaults?.ConditionExpression || "", ":");
+    const namesInCondition = (0, lib_1.getAttributesFromExpression)(argsWithDefaults?.ConditionExpression || "");
     const attributesToUpdate = Object.keys(data).filter((key) => !valuesInCondition.includes(key));
     const UpdateExpression = "SET " + attributesToUpdate.map((key) => `#${key} = :${key}`).join(", ");
     return (0, lib_1.getClient)()
         .send(new client_dynamodb_1.UpdateItemCommand({
-        Key: (0, lib_1.stripKey)(key, args),
+        Key: (0, lib_1.stripKey)(key, argsWithDefaults),
         UpdateExpression,
         ExpressionAttributeValues: (0, lib_1.getAttributeValues)(data, [
             ...attributesToUpdate,
@@ -56,10 +24,12 @@ async function updateItem(key, data, args = {}) {
             ...attributesToUpdate,
             ...namesInCondition,
         ]),
-        ...args,
-        TableName: args?.TableName || (0, lib_1.getDefaultTable)(),
+        ...argsWithDefaults,
+        TableName: argsWithDefaults?.TableName || (0, lib_1.getDefaultTable)(),
     }))
-        .then((res) => args?.ReturnValues ? (0, lib_1.unmarshallWithOptions)(res.Attributes) : undefined);
+        .then((res) => argsWithDefaults?.ReturnValues
+        ? (0, lib_1.unmarshallWithOptions)(res.Attributes)
+        : undefined);
 }
 exports.updateItem = updateItem;
 /**
@@ -78,7 +48,7 @@ exports.updateItem = updateItem;
  */
 async function removeAttributes(key, attributes, args = {}) {
     args = (0, lib_1.withDefaults)(args, "removeAttributes");
-    const UpdateExpression = "REMOVE " + attributes.map((att) => `#${att}`).join(", ");
+    const UpdateExpression = "REMOVE " + attributes.map((att) => `#${String(att)}`).join(", ");
     return (0, lib_1.getClient)().send(new client_dynamodb_1.UpdateItemCommand({
         Key: (0, lib_1.stripKey)(key, args),
         UpdateExpression,

package/dist/types.d.ts

@@ -0,0 +1,4 @@
+export type DynamoDBItem = Record<string, any> & {
+    createdAt?: number;
+    updatedAt?: number;
+};

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

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