Merge pull request #29 from mindler-sasu/main

add JSDoc

src/queryBuilders/deleteItemQueryBuilder.ts

@@ -26,7 +26,24 @@ export interface DeleteItemQueryBuilderInterface<
   Table extends keyof DDB,
   O extends DDB[Table]
 > {
-  // 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<Key extends ObjectKeyPaths<DDB[Table]>>(
     ...args: ComparatorExprArg<DDB, Table, Key>
   ): DeleteItemQueryBuilder<DDB, Table, O>;
@@ -55,7 +72,26 @@ export interface DeleteItemQueryBuilderInterface<
     ...args: BuilderExprArg<DDB, Table, Key>
   ): DeleteItemQueryBuilder<DDB, Table, O>;
 
-  // 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<Key extends ObjectKeyPaths<DDB[Table]>>(
     ...args: ComparatorExprArg<DDB, Table, Key>
   ): DeleteItemQueryBuilder<DDB, Table, O>;
@@ -84,25 +120,63 @@ export interface DeleteItemQueryBuilderInterface<
     ...args: BuilderExprArg<DDB, Table, Key>
   ): DeleteItemQueryBuilder<DDB, Table, O>;
 
+  // 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<ReturnValuesOptions, "NONE" | "ALL_OLD">
   ): DeleteItemQueryBuilder<DDB, Table, O>;
 
+  /**
+   *
+   * Returns the item attributes for a DeleteItem operation that failed a condition check.
+   */
   returnValuesOnConditionCheckFailure(
     option: Extract<ReturnValuesOptions, "NONE" | "ALL_OLD">
   ): DeleteItemQueryBuilder<DDB, Table, O>;
 
+  /**
+   * 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<Keys extends PickPk<DDB[Table]> & PickSkRequired<DDB[Table]>>(
     pk: Keys
   ): DeleteItemQueryBuilder<DDB, Table, O>;
 
+  /**
+   * Compiles into an DynamoDB DocumentClient Command.
+   */
   compile(): DeleteCommand;
+  /**
+   * Executes the command and returns its output.
+   */
   execute(): Promise<ExecuteOutput<O>[] | undefined>;
 }
 
-/**
- * @todo support ReturnValuesOnConditionCheckFailure
- */
 export class DeleteItemQueryBuilder<
   DDB,
   Table extends keyof DDB,

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<DDB[Table]>

src/queryBuilders/getItemQueryBuilder.ts

@@ -11,17 +11,75 @@ import {
 import { preventAwait } from "../util/preventAwait";
 
 export interface GetQueryBuilderInterface<DDB, Table extends keyof DDB, O> {
+  /**
+   * 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<Keys extends PickPk<DDB[Table]> & PickSkRequired<DDB[Table]>>(
     pk: Keys
   ): GetQueryBuilder<DDB, Table, O>;
 
+  /**
+   * 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): GetQueryBuilder<DDB, Table, O>;
 
+  /**
+   * 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<A extends readonly ObjectFullPaths<DDB[Table]>[] & string[]>(
     attributes: A
   ): GetQueryBuilder<DDB, Table, SelectAttributes<DDB[Table], A>>;
 
+  /**
+   * Compiles into an DynamoDB DocumentClient Command.
+   */
   compile(): GetCommand;
+  /**
+   * Executes the command and returns its output.
+   */
   execute(): Promise<ExecuteOutput<O> | undefined>;
 }
 

src/queryBuilders/putItemQueryBuilder.ts

@@ -21,7 +21,25 @@ export interface PutItemQueryBuilderInterface<
   Table extends keyof DDB,
   O extends DDB[Table]
 > {
-  // 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<Key extends ObjectKeyPaths<DDB[Table]>>(
     ...args: ComparatorExprArg<DDB, Table, Key>
   ): PutItemQueryBuilder<DDB, Table, O>;
@@ -50,7 +68,25 @@ export interface PutItemQueryBuilderInterface<
     ...args: BuilderExprArg<DDB, Table, Key>
   ): PutItemQueryBuilder<DDB, Table, O>;
 
-  // 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<Key extends ObjectKeyPaths<DDB[Table]>>(
     ...args: ComparatorExprArg<DDB, Table, Key>
   ): PutItemQueryBuilder<DDB, Table, O>;
@@ -79,15 +115,57 @@ export interface PutItemQueryBuilderInterface<
     ...args: BuilderExprArg<DDB, Table, Key>
   ): PutItemQueryBuilder<DDB, Table, O>;
 
+  // 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<ReturnValuesOptions, "NONE" | "ALL_OLD">
   ): PutItemQueryBuilder<DDB, Table, O>;
 
+  /**
+   * 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 extends ExecuteOutput<O>>(
     item: Item
   ): PutItemQueryBuilder<DDB, Table, O>;
 
+  /**
+   * Compiles into an DynamoDB DocumentClient Command.
+   */
   compile(): PutCommand;
+  /**
+   * Executes the command and returns its output.
+   */
   execute(): Promise<ExecuteOutput<O>[] | undefined>;
 }