From f1eaba5d0a8184e883bd3912676dc289efc73268 Mon Sep 17 00:00:00 2001 From: sasumaki Date: Wed, 8 May 2024 14:44:34 +0300 Subject: [PATCH 1/2] add JSDoc --- src/queryBuilders/deleteItemQueryBuilder.ts | 85 +++++++++- src/queryBuilders/expressionBuilder.ts | 20 ++- src/queryBuilders/getItemQueryBuilder.ts | 58 +++++++ src/queryBuilders/putItemQueryBuilder.ts | 82 ++++++++- src/queryBuilders/queryQueryBuilder.ts | 106 +++++++++++- src/queryBuilders/updateItemQueryBuilder.ts | 177 +++++++++++++++++++- src/queryCreator.ts | 91 +++++++++- src/tsynamo.ts | 30 +++- 8 files changed, 625 insertions(+), 24 deletions(-) diff --git a/src/queryBuilders/deleteItemQueryBuilder.ts b/src/queryBuilders/deleteItemQueryBuilder.ts index 50dd957..649afe3 100644 --- a/src/queryBuilders/deleteItemQueryBuilder.ts +++ b/src/queryBuilders/deleteItemQueryBuilder.ts @@ -26,7 +26,24 @@ export interface DeleteItemQueryBuilderInterface< Table extends keyof DDB, O > { - // conditionExpression + /** + * A condition that must be satisfied in order for a DeleteItem operation to be executed. + * + * Multiple conditionExpressions are added as `AND` statements. see {@link orConditionExpression} for `OR` statements. + * + * Example + * + * ```ts + * await tsynamoClient + * .deleteItem("myTable") + * .keys({ + * userId: "333", + * dataTimestamp: 222, + * }) + * .conditionExpression("tags", "contains", "meow") + * .execute() + * ``` + */ conditionExpression>( ...args: ComparatorExprArg ): DeleteItemQueryBuilderInterface; @@ -55,7 +72,26 @@ export interface DeleteItemQueryBuilderInterface< ...args: BuilderExprArg ): DeleteItemQueryBuilderInterface; - // orConditionExpression + /** + * A {@link conditionExpression} that is concatenated as an OR statement. + * + * A condition that must be satisfied in order for a DeleteItem operation to be executed. + * + * Example + * + * ```ts + * await tsynamoClient + * .putItem("myTable") + * .item({ + * userId: "333", + * dataTimestamp: 222, + * someBoolean: true, + * }) + * .conditionExpression("userId", "attribute_not_exists") + * .orConditionExpression("someBoolean", "attribute_exists") + * .execute() + * ``` + */ orConditionExpression>( ...args: ComparatorExprArg ): DeleteItemQueryBuilderInterface; @@ -84,25 +120,62 @@ export interface DeleteItemQueryBuilderInterface< ...args: BuilderExprArg ): DeleteItemQueryBuilderInterface; + // TODO: returnValues should probably just be `returnValues()` without any parameters as ALL_OLD is the only value it takes. + + /** + * + * Use this if you want to get the item attributes as they appeared before they were updated with the PutItem request. + * + * The valid values are: + * + * - NONE - If returnValues is not specified, or if its value is NONE, then nothing is returned. (This setting is the default.) + * + * - ALL_OLD - If PutItem overwrote an attribute name-value pair, then the content of the old item is returned. + * + * The values returned are strongly consistent. + */ returnValues( option: Extract ): DeleteItemQueryBuilderInterface; + /** + * + * Returns the item attributes for a DeleteItem operation that failed a condition check. + */ returnValuesOnConditionCheckFailure( option: Extract ): DeleteItemQueryBuilderInterface; + /** + * An object of attribute names to attribute values, representing the primary key of the item to delete. + * + * For the primary key, you must provide all of the attributes. For example, with a simple primary key, you only need to provide a value for the partition key. For a composite primary key, you must provide values for both the partition key and the sort key. + * + * Example + * + * ```ts + * await tsynamoClient + * .deleteItem("myTable") + * .keys({ + * userId: "123", // partition key + * eventId: 222, // sort key + * }) + * .execute(); + * ``` + */ keys & PickSkRequired>( pk: Keys ): DeleteItemQueryBuilderInterface; - + /** + * Compiles into an DynamoDB DocumentClient Command. + */ compile(): DeleteCommand; + /** + * Executes the command and returns its output. + */ execute(): Promise[] | undefined>; } -/** - * @todo support ReturnValuesOnConditionCheckFailure - */ export class DeleteItemQueryBuilder< DDB, Table extends keyof DDB, diff --git a/src/queryBuilders/expressionBuilder.ts b/src/queryBuilders/expressionBuilder.ts index 2d7d963..6aadc89 100644 --- a/src/queryBuilders/expressionBuilder.ts +++ b/src/queryBuilders/expressionBuilder.ts @@ -24,7 +24,25 @@ export interface ExpressionBuilderInterface< O, AllowKeys = false > { - // expression + /** + * + * Expression builder for {@link conditionExpression} or {@link orConditionExpression}. + * + * Example + * + * ```ts + * tsynamoClient + * .deleteItem("myTable") + * .keys({ + * userId: "1", + * dataTimestamp: 2, + * }) + * .conditionExpression("NOT", (qb) => { + * return qb.expression("tags", "contains", "meow"); + * }) + * .execute() + * ``` + */ expression< Key extends ObjectKeyPaths< AllowKeys extends true ? DDB[Table] : PickNonKeys diff --git a/src/queryBuilders/getItemQueryBuilder.ts b/src/queryBuilders/getItemQueryBuilder.ts index 2935428..8e03598 100644 --- a/src/queryBuilders/getItemQueryBuilder.ts +++ b/src/queryBuilders/getItemQueryBuilder.ts @@ -11,17 +11,75 @@ import { import { preventAwait } from "../util/preventAwait"; export interface GetQueryBuilderInterface { + /** + * An object of attribute names to attribute values, representing the primary key of the item to retrieve. + * + * For the primary key, you must provide all of the attributes. For example, with a simple primary key, you only need to provide a value for the partition key. For a composite primary key, you must provide values for both the partition key and the sort key. + * + * Example + * + * ```ts + * await tsynamoClient + * .getItem("UserEvents") + * .keys({ + * userId: "123", // partition key + * eventId: 222, // sort key + * }) + * .execute(); + * ``` + */ keys & PickSkRequired>( pk: Keys ): GetQueryBuilderInterface; + /** + * Determines the read consistency model: If set to true, then the operation uses strongly consistent reads; otherwise, the operation uses eventually consistent reads. + * + * set this to true, if you must have up-to-date data. + * + * Example + * + * ```ts + * await tsynamoClient + * .getItem("myTable") + * .keys({ + * userId: TEST_DATA[0].userId, + * dataTimestamp: TEST_DATA[0].dataTimestamp, + * }) + * .consistentRead(true) + * .attributes(["somethingElse", "someBoolean"]) + * .execute() + * ``` + */ consistentRead(enabled: boolean): GetQueryBuilderInterface; + /** + * List of attributes to get from the table. + * + * Example + * + * ```ts + * await tsynamoClient + * .getItem("myTable") + * .keys({ + * userId: TEST_DATA[0].userId, + * dataTimestamp: TEST_DATA[0].dataTimestamp, + * }) + .attributes(["someBoolean", "nested.nestedBoolean", "cats[1].age"]) + * .execute() + * ``` + */ attributes[] & string[]>( attributes: A ): GetQueryBuilderInterface>; + /** + * Compiles into an DynamoDB DocumentClient Command. + */ compile(): GetCommand; + /** + * Executes the command and returns its output. + */ execute(): Promise | undefined>; } diff --git a/src/queryBuilders/putItemQueryBuilder.ts b/src/queryBuilders/putItemQueryBuilder.ts index 2ddbb42..6701260 100644 --- a/src/queryBuilders/putItemQueryBuilder.ts +++ b/src/queryBuilders/putItemQueryBuilder.ts @@ -17,7 +17,25 @@ import { } from "./expressionBuilder"; export interface PutItemQueryBuilderInterface { - // conditionExpression + /** + * A condition that must be satisfied in order for a PutItem operation to be executed. + * + * Multiple FilterExpressions are added as `AND` statements. see {@link orConditionExpression} for `OR` statements. + * + * Example + * + * ```ts + * await tsynamoClient + * .putItem("myTable") + * .item({ + * userId: "333", + * dataTimestamp: 222, + * someBoolean: true, + * }) + * .conditionExpression("userId", "attribute_not_exists") + * .execute() + * ``` + */ conditionExpression>( ...args: ComparatorExprArg ): PutItemQueryBuilderInterface; @@ -46,7 +64,25 @@ export interface PutItemQueryBuilderInterface { ...args: BuilderExprArg ): PutItemQueryBuilderInterface; - // orConditionExpression + /** + * A {@link conditionExpression} that is concatenated as an OR statement. + * + * A condition that must be satisfied in order for a PutItem operation to be executed. + * + * Example + * + * ```ts + * await tsynamoClient + * .putItem("myTable") + * .item({ + * userId: "333", + * dataTimestamp: 222, + * someBoolean: true, + * }) + * .conditionExpression("userId", "attribute_not_exists") + * .execute() + * ``` + */ orConditionExpression>( ...args: ComparatorExprArg ): PutItemQueryBuilderInterface; @@ -75,15 +111,57 @@ export interface PutItemQueryBuilderInterface { ...args: BuilderExprArg ): PutItemQueryBuilderInterface; + // TODO: returnValues should probably just be `returnValues()` without any parameters as ALL_OLD is the only value it takes. + + /** + * + * Use this if you want to get the item attributes as they appeared before they were updated with the PutItem request. + * + * The valid values are: + * + * - NONE - If returnValues is not specified, or if its value is NONE, then nothing is returned. (This setting is the default.) + * + * - ALL_OLD - If PutItem overwrote an attribute name-value pair, then the content of the old item is returned. + * + * The values returned are strongly consistent. + */ returnValues( option: Extract ): PutItemQueryBuilderInterface; + /** + * The item that is put into the table. + * + * Only the primary key attributes are required; you can optionally provide other attribute name-value pairs for the item. + * + * You must provide all of the attributes for the primary key. For example, with a simple primary key, you only need to provide a value for the partition key. For a composite primary key, you must provide values for both the partition key and the sort key. + * + * If you specify any attributes that are part of an index key, then the data types for those attributes must match those of the schema in the table's attribute definition. + * + * Example + * + * ```ts + * await tsynamoClient + * .putItem("myTable") + * .item({ + * userId: "333", + * dataTimestamp: 222, + * someBoolean: true, + * }) + * .execute() + * ``` + */ item>( item: Item ): PutItemQueryBuilderInterface; + /** + * Compiles into an DynamoDB DocumentClient Command. + */ compile(): PutCommand; + /** + * Executes the command and returns its output. + */ execute(): Promise[] | undefined>; } diff --git a/src/queryBuilders/queryQueryBuilder.ts b/src/queryBuilders/queryQueryBuilder.ts index f2183e6..a119964 100644 --- a/src/queryBuilders/queryQueryBuilder.ts +++ b/src/queryBuilders/queryQueryBuilder.ts @@ -30,7 +30,26 @@ import { } from "./expressionBuilder"; export interface QueryQueryBuilderInterface { - // filterExpression + /** + * Conditions that DynamoDB applies after the Query operation, but before the data is returned to you. + * + * Items that do not satisfy the FilterExpression criteria are not returned. + * + * A FilterExpression does not allow key attributes. You cannot define a filter expression based on a partition key or a sort key. + * + * A FilterExpression is applied after the items have already been read; the process of filtering does not change consumed read capacity units. + * + * Multiple FilterExpressions are added as `AND` statements. see {@link orFilterExpression} for `OR` statements. + * + * Example + * ```ts + * await tsynamoClient + * .query("myTable") + * .keyCondition("userId", "=", "123") + * .filterExpression("someBoolean", "=", true) + * .execute(); + * ``` + */ filterExpression>>( ...args: ComparatorExprArg ): QueryQueryBuilderInterface; @@ -59,8 +78,27 @@ export interface QueryQueryBuilderInterface { ...args: BuilderExprArg ): QueryQueryBuilderInterface; - // orFilterExpression - orFilterExpression>>( + /** + * A {@link filterExpression} that is concatenated as an OR statement. + * + * Conditions that DynamoDB applies after the Query operation, but before the data is returned to you. + * + * Items that do not satisfy the FilterExpression criteria are not returned. + * + * A FilterExpression does not allow key attributes. You cannot define a filter expression based on a partition key or a sort key. + * + * A FilterExpression is applied after the items have already been read; the process of filtering does not change consumed read capacity units. + * + * Example + * ```ts + * await tsynamoClient + * .query("myTable") + * .keyCondition("userId", "=", "123") + * .filterExpression("someBoolean", "=", true) + * .orFilterExpression("somethingElse", "BETWEEN", 9, 10) + * .execute(); + * ``` + */ orFilterExpression>>( ...args: ComparatorExprArg ): QueryQueryBuilderInterface; @@ -89,7 +127,23 @@ export interface QueryQueryBuilderInterface { ): QueryQueryBuilderInterface; /** - * keyCondition methods + * The condition that specifies the key values for items to be retrieved by the Query action. + * + * The condition must perform an equality test on a single partition key value. + * + * The condition can optionally perform one of several comparison tests on a single sort key value. This allows Query to retrieve one item with a given partition key value and sort key value, or several items that have the same partition key value but different sort key values. + * + * The partition key equality test is required. + * + * Example + * + * ```ts + * await tsynamoClient + * .query("myTable") + * .keyCondition("userId", "=", "123") + * .keyCondition("dataTimestamp", "BETWEEN", 150, 500) + * .execute(); + * ``` */ keyCondition & string>( key: Key, @@ -112,17 +166,57 @@ export interface QueryQueryBuilderInterface { val: StripKeys ): QueryQueryBuilderInterface; + /** + * The maximum number of items to evaluate (not necessarily the number of matching items). + * If DynamoDB processes the number of items up to the limit while processing the results, it stops the operation and returns the matching values up to that point. + */ limit(value: number): QueryQueryBuilderInterface; + /** + * + * Specifies the order for index traversal: If true (default), the traversal is performed in ascending order; if false, the traversal is performed in descending order. + */ scanIndexForward(enabled: boolean): QueryQueryBuilderInterface; - + /** + * Determines the read consistency model: If set to true, then the operation uses strongly consistent reads; otherwise, the operation uses eventually consistent reads. + * + * set this to true, if you must have up-to-date data. + * + * Example + * + * ```ts + * await tsynamoClient + * .query("myTable") + * .keyCondition("userId", "=", "123") + * .consistentRead(true) + * .execute() + * ``` + */ consistentRead(enabled: boolean): QueryQueryBuilderInterface; + /** + * List of attributes to get from the table. + * + * Example + * + * ```ts + * await tsynamoClient + * .query("myTable") + * .keyCondition("userId", "=", "123") + * .attributes(["someBoolean", "nested.nestedBoolean", "cats[1].age"]) + * .execute() + * ``` + */ attributes[] & string[]>( attributes: A ): QueryQueryBuilderInterface>; - + /** + * Compiles into an DynamoDB DocumentClient Command. + */ compile(): QueryCommand; + /** + * Executes the command and returns its output. + */ execute(): Promise[] | undefined>; } diff --git a/src/queryBuilders/updateItemQueryBuilder.ts b/src/queryBuilders/updateItemQueryBuilder.ts index 6579aa7..66d8bc3 100644 --- a/src/queryBuilders/updateItemQueryBuilder.ts +++ b/src/queryBuilders/updateItemQueryBuilder.ts @@ -33,7 +33,25 @@ export interface UpdateItemQueryBuilderInterface< Table extends keyof DDB, O > { - // conditionExpression + /** + * A condition that must be satisfied in order for a UpdateItem operation to be executed. + * + * Multiple conditionExpressions are added as `AND` statements. see {@link orConditionExpression} for `OR` statements. + * + * Example + * + * ```ts + * await tsynamoClient + * .updateItem("myTable") + * .keys({ + * userId: "333", + * dataTimestamp: 222, + * }) + * .remove("somethingElse") + * .conditionExpression("tags", "contains", "meow") + * .execute() + * ``` + */ conditionExpression>( ...args: ComparatorExprArg ): UpdateItemQueryBuilderInterface; @@ -62,7 +80,26 @@ export interface UpdateItemQueryBuilderInterface< ...args: BuilderExprArg ): UpdateItemQueryBuilderInterface; - // orConditionExpression + /** + * A {@link conditionExpression} that is concatenated as an OR statement. + * + * A condition that must be satisfied in order for a UpdateItem operation to be executed. + * + * Example + * + * ```ts + * await tsynamoClient + * .updateItem("myTable") + * .keys({ + * userId: "333", + * dataTimestamp: 222, + * }) + * .remove("somethingElse") + * .conditionExpression("tags", "contains", "meow") + * .orConditionExpression("somethingElse", ">", 0) + * .execute() + * ``` + */ orConditionExpression>( ...args: ComparatorExprArg ): UpdateItemQueryBuilderInterface; @@ -91,6 +128,39 @@ export interface UpdateItemQueryBuilderInterface< ...args: BuilderExprArg ): UpdateItemQueryBuilderInterface; + /** + * Adds an SET action to the UpdateItem statement. + * + * SET adds one or more attributes and values to an item. If any of these attributes already exist, they are replaced by the new values. You can also use SET to add or subtract from an attribute that is of type Number. + * + * SET supports the following functions: + * + * - if_not_exists (path, operand) - if the item does not contain an attribute at the specified path, then if_not_exists evaluates to operand; otherwise, it evaluates to path. You can use this function to avoid overwriting an attribute that may already be present in the item. + * + * - list_append (operand, operand) - evaluates to a list with a new element added to it. You can append the new element to the start or the end of the list by reversing the order of the operands. + * + * Example + * + * ```ts + * await tsynamoClient + * .updateItem("myTable") + * .keys({ userId: "1", dataTimestamp: 2 }) + * .set("someBoolean", "=", (qb) => { + * return qb.ifNotExists("someBoolean", true); + * }) + * .set("tags", "=", (qb) => { + * return qb.listAppend( + * (qbb) => qbb.ifNotExists("tags", []), + * ["test_tag"] + * ); + * }) + * .set("somethingElse", "+=", (qb) => { + * return [qb.ifNotExists("somethingElse", 1), 2]; + * }) + * .returnValues("ALL_NEW") + * .execute(); + * ``` + */ set>>( key: Key, operand: UpdateExpressionOperands, @@ -112,16 +182,74 @@ export interface UpdateItemQueryBuilderInterface< builder: SetUpdateExpressionFunctionQueryBuilder ) => [SetUpdateExpressionFunction, number] ): UpdateItemQueryBuilderInterface; - + /** + * An object of attribute names to attribute values, representing the primary key of the item to update. + * + * For the primary key, you must provide all of the attributes. For example, with a simple primary key, you only need to provide a value for the partition key. For a composite primary key, you must provide values for both the partition key and the sort key. + * + * Example + * + * ```ts + * await tsynamoClient + * .updateItem("myTable") + * .keys({ + * userId: "123", // partition key + * eventId: 222, // sort key + * }) + * .execute(); + * ``` + */ keys & PickSkRequired>( pk: Keys ): UpdateItemQueryBuilderInterface; // TODO: Make it possible to delete a whole object, and not just nested keys + /** + * Adds an REMOVE action to the UpdateItem statement. + * + * Removes attributes from the item. + * + * Example + * + * ```ts + * await tsynamoClient + * .updateItem("myTable") + * .keys({ userId: "1010", dataTimestamp: 200 }) + * .remove("somethingElse") + * .execute(); + * ``` + */ remove>>( attribute: Key ): UpdateItemQueryBuilderInterface; - + /** + * Adds an ADD action to the UpdateItem statement. + * + * Adds the specified value to the item, if the attribute does not already exist. If the attribute does exist, then the behavior of ADD depends on the data type of the attribute: + * + * If the existing attribute is a number, and if Value is also a number, then Value is mathematically added to the existing attribute. If Value is a negative number, then it is subtracted from the existing attribute. + * + * If you use ADD to increment or decrement a number value for an item that doesn't exist before the update, DynamoDB uses 0 as the initial value. + * + * Similarly, if you use ADD for an existing item to increment or decrement an attribute value that doesn't exist before the update, DynamoDB uses 0 as the initial value. For example, suppose that the item you want to update doesn't have an attribute named itemcount, but you decide to ADD the number 3 to this attribute anyway. DynamoDB will create the itemcount attribute, set its initial value to 0, and finally add 3 to it. The result will be a new itemcount attribute in the item, with a value of 3. + * + * If the existing data type is a set and if Value is also a set, then Value is added to the existing set. For example, if the attribute value is the set [1,2], and the ADD action specified [3], then the final attribute value is [1,2,3]. An error occurs if an ADD action is specified for a set attribute and the attribute type specified does not match the existing set type. + * + * Both sets must have the same primitive data type. For example, if the existing data type is a set of strings, the Value must also be a set of strings. + * + * The ADD action only supports Number and set data types. In addition, ADD can only be used on top-level attributes, not nested attributes. + * + * Example + * + * ```ts + * await tsynamoClient + * .updateItem("myTable") + * .keys({ userId: "1010", dataTimestamp: 200 }) + * .add("somethingElse", 7) + * .add("someSet", new Set(["item1", "item2"])) + * .execute(); + * ``` + */ add< Key extends ObjectKeyPaths< FilteredKeys, Set | number> @@ -131,6 +259,25 @@ export interface UpdateItemQueryBuilderInterface< value: StripKeys> ): UpdateItemQueryBuilderInterface; + /** + * Adds an DELETE action to the UpdateItem statement. + * + * DELETE - Deletes an element from a set. + * + * If a set of values is specified, then those values are subtracted from the old set. For example, if the attribute value was the set [a,b,c] and the DELETE action specifies [a,c], then the final attribute value is [b]. Specifying an empty set is an error. + * + * The DELETE action only supports set data types. In addition, DELETE can only be used on top-level attributes, not nested attributes. + * + * Example + * + * ```ts + * await tsynamoClient + * .updateItem("myTable") + * .keys({ userId: "1010", dataTimestamp: 200 }) + * .delete("someSet", new Set(["2", "3"])) + * .execute(); + * ``` + */ delete< Key extends ObjectKeyPaths< FilteredKeys, Set> @@ -139,12 +286,30 @@ export interface UpdateItemQueryBuilderInterface< attribute: Key, value: StripKeys> ): UpdateItemQueryBuilderInterface; - + /** + * + * Use returnValues if you want to get the item attributes as they appear before or after they are successfully updated. For UpdateItem, the valid values are: + * + * - NONE - If returnValues is not specified, or if its value is NONE, then nothing is returned. (This setting is the default for returnValues.) + * + * - ALL_OLD - Returns all of the attributes of the item, as they appeared before the UpdateItem operation. + * + * - UPDATED_OLD - Returns only the updated attributes, as they appeared before the UpdateItem operation. + * + * - ALL_NEW - Returns all of the attributes of the item, as they appear after the UpdateItem operation. + * + * - UPDATED_NEW - Returns only the updated attributes, as they appear after the UpdateItem operation. + */ returnValues( option: ReturnValuesOptions ): UpdateItemQueryBuilderInterface; - + /** + * Compiles into an DynamoDB DocumentClient Command. + */ compile(): UpdateCommand; + /** + * Executes the command and returns its output. + */ execute(): Promise[] | undefined>; } diff --git a/src/queryCreator.ts b/src/queryCreator.ts index ced2865..b9c495d 100644 --- a/src/queryCreator.ts +++ b/src/queryCreator.ts @@ -21,7 +21,24 @@ export class QueryCreator { /** * - * @param table Table to perform the get-item command to + * Creates a GetItem Command to get items from the given DynamoDB table. + * + * The GetItem operation returns a set of attributes for the item with the given primary key. If there is no matching item, GetItem does not return any data and there will be no Item element in the response. + * + * Example + * + * ```ts + * await tsynamoClient + * .getItem("UserEvents") + * .keys({ + * userId: "123", + * eventId: 222, + * }) + * .attributes(["userId"]) + * .execute(); + * ``` + * + * @param table DynamoDB Table name to perform the get-item command to * * @see https://docs.aws.amazon.com/cli/latest/reference/dynamodb/get-item.html * @see https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/dynamodb/command/GetItemCommand/ @@ -44,6 +61,21 @@ export class QueryCreator { /** * + * Creates a Query Command to query items from the given DynamoDB table. + * + * You must provide the name of the partition key attribute and a single value for that attribute as a key condition. Query returns all items with that partition key value. + * + * Optionally, you can provide a sort key attribute and use a comparison operator to refine the search results. + * + * Example + * + * ```ts + * await tsynamoClient + * .query("UserEvents") + * .keyCondition("userId", "=", "123") + * .filterExpression("eventType", "begins_with", "LOG") + * .execute(); + * ``` * @param table Table to perform the query command to * * @see https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/dynamodb/command/QueryCommand/ @@ -71,6 +103,26 @@ export class QueryCreator { /** * + * Creates a Put Item Command to put items in the given DynamoDB table. + * + * Creates a new item, or replaces an old item with a new item. If an item that has the same primary key as the new item already exists in the specified table, the new item completely replaces the existing item. + * + * You can perform a conditional put operation (add a new item if one with the specified primary key doesn't exist), or replace an existing item if it has certain attribute values. You can return the item's attribute values in the same operation, using the returnValues function. + * + * When you add an item, the primary key attributes are the only required attributes. + * + * Example + * + * ```ts + * await tsynamoClient + * .putItem("myTable") + * .item({ + * userId: "123", + * eventId: 313, + * }) + * .conditionExpression("userId", "attribute_not_exists") + * .execute(); + * ``` * @param table Table to perform the put item command to * * @see https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/dynamodb/command/PutItemCommand/ @@ -96,7 +148,24 @@ export class QueryCreator { } /** + * Creates a Delete Item command to the given DynamoDB Table. + * + * Deletes a single item in a table by primary key. You can perform a conditional delete operation that deletes the item if it exists, or if it has an expected attribute value. + * + * In addition to deleting an item, you can also return the item's attribute values in the same operation, using the returnValues function. * + * Example + * + * ```ts + * await tsynamoClient + * .deleteItem("myTable") + * .keys({ + * userId: "123", + * eventId: 313, + * }) + * .conditionExpression("eventType", "attribute_not_exists") + * .execute(); + * ``` * @param table Table to perform the delete item command to * * @see https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/dynamodb/command/DeleteItemCommand/ @@ -123,6 +192,24 @@ export class QueryCreator { /** * + * Creates an Update Item Command to the given DynamoDB table. + * + * Edits an existing item's attributes, or adds a new item to the table if it does not already exist. You can put, delete, or add attribute values. You can also perform a conditional update on an existing item (insert a new attribute name-value pair if it doesn't exist, or replace an existing name-value pair if it has certain expected attribute values). + * + * Example + * + * ```ts + * await tsynamoClient + * .updateItem("myTable") + * .keys({ userId: "1", dataTimestamp: 2 }) + * .set("nested.nestedBoolean", "=", true) + * .remove("nested.nestedString") + * .add("somethingElse", 10) + * .add("someSet", new Set(["4", "5"])) + * .delete("nested.nestedSet", new Set(["4", "5"])) + * .conditionExpression("somethingElse", ">", 0) + * .execute(); + * ``` * @param table Table to perform the update item command to * * @see https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/dynamodb/command/UpdateItemCommand/ @@ -146,7 +233,7 @@ export class QueryCreator { setUpdateExpressions: [], removeUpdateExpressions: [], addUpdateExpressions: [], - deleteUpdateExpressions: [] + deleteUpdateExpressions: [], }, }, ddbClient: this.#props.ddbClient, diff --git a/src/tsynamo.ts b/src/tsynamo.ts index 3bff07c..9bb1d39 100644 --- a/src/tsynamo.ts +++ b/src/tsynamo.ts @@ -1,7 +1,35 @@ import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb"; import { QueryCreator } from "./queryCreator"; import { QueryCompiler } from "./queryCompiler/queryCompiler"; - +/** + * The main Tsynamo class. + * Create instance of Tsynamo using the {@link Tsynamo} constructor. + * + * Examples + * ```ts + * import { PartitionKey, SortKey } from "tsynamo"; + * import { DynamoDBClient } from "@aws-sdk/client-dynamodb"; + * import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb"; + * + * interface DDB { + * UserEvents: { + * userId: PartitionKey; + * eventId: SortKey; + * eventType: string; + * userAuthenticated: boolean; + * }; + * }; + * + * const ddbClient = DynamoDBDocumentClient.from( + * new DynamoDBClient({ + * \/* Configure client... *\/ + * }) + * ); + * const tsynamoClient = new Tsynamo({ + * ddbClient, + * }); + * ``` + */ export class Tsynamo extends QueryCreator { constructor(args: TsynamoProps) { const queryCompiler = new QueryCompiler(); From 1e455f7f1a89714b3ea224407e75eafe53b63321 Mon Sep 17 00:00:00 2001 From: sasumaki Date: Fri, 7 Jun 2024 15:03:46 +0300 Subject: [PATCH 2/2] :broom: merge fuckups --- src/queryBuilders/deleteItemQueryBuilder.ts | 2 +- src/queryBuilders/queryQueryBuilder.ts | 3 ++- src/queryBuilders/updateItemQueryBuilder.ts | 4 ++-- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/src/queryBuilders/deleteItemQueryBuilder.ts b/src/queryBuilders/deleteItemQueryBuilder.ts index 4851170..e85a63a 100644 --- a/src/queryBuilders/deleteItemQueryBuilder.ts +++ b/src/queryBuilders/deleteItemQueryBuilder.ts @@ -165,7 +165,7 @@ export interface DeleteItemQueryBuilderInterface< */ keys & PickSkRequired>( pk: Keys - ): DeleteItemQueryBuilderInterface; + ): DeleteItemQueryBuilder; /** * Compiles into an DynamoDB DocumentClient Command. diff --git a/src/queryBuilders/queryQueryBuilder.ts b/src/queryBuilders/queryQueryBuilder.ts index a119964..5cfe1a5 100644 --- a/src/queryBuilders/queryQueryBuilder.ts +++ b/src/queryBuilders/queryQueryBuilder.ts @@ -98,7 +98,8 @@ export interface QueryQueryBuilderInterface { * .orFilterExpression("somethingElse", "BETWEEN", 9, 10) * .execute(); * ``` - */ orFilterExpression>>( + */ + orFilterExpression>>( ...args: ComparatorExprArg ): QueryQueryBuilderInterface; diff --git a/src/queryBuilders/updateItemQueryBuilder.ts b/src/queryBuilders/updateItemQueryBuilder.ts index 3f1e7bf..0a1153f 100644 --- a/src/queryBuilders/updateItemQueryBuilder.ts +++ b/src/queryBuilders/updateItemQueryBuilder.ts @@ -222,7 +222,7 @@ export interface UpdateItemQueryBuilderInterface< */ remove>>( attribute: Key - ): UpdateItemQueryBuilderInterface; + ): UpdateItemQueryBuilder; /** * Adds an ADD action to the UpdateItem statement. * @@ -286,7 +286,7 @@ export interface UpdateItemQueryBuilderInterface< >( attribute: Key, value: StripKeys> - ): UpdateItemQueryBuilderInterface; + ): UpdateItemQueryBuilder; /** * * Use returnValues if you want to get the item attributes as they appear before or after they are successfully updated. For UpdateItem, the valid values are: