dyno-table 0.2.0-0 → 1.0.0-alpha.1

package/dist/{table.js → index.js}

@@ -861,14 +861,6 @@ var PutBuilder = class {
       returnValues: "NONE"
     };
   }
-  set(valuesOrPath, value) {
-    if (typeof valuesOrPath === "object") {
-      Object.assign(this.item, valuesOrPath);
-    } else {
-      this.item[valuesOrPath] = value;
-    }
-    return this;
-  }
   /**
    * Adds a condition that must be satisfied for the put operation to succeed.
    * Use this method when you need to:
@@ -1113,6 +1105,10 @@ var DeleteBuilder = class {
   }
   /**
    * Adds a condition that must be satisfied for the delete operation to succeed.
+   * Use this method when you need to:
+   * - Ensure safe removal conditions
+   * - Verify habitat status before deletion
+   * - Implement safety protocols
    *
    * @example
    * ```typescript
@@ -1164,6 +1160,10 @@ var DeleteBuilder = class {
   }
   /**
    * Sets whether to return the item's attribute values before deletion.
+   * Use this method when you need to:
+   * - Archive removed dinosaur data
+   * - Track habitat decommissioning history
+   * - Maintain removal audit logs
    *
    * @example
    * ```ts
@@ -1204,6 +1204,10 @@ var DeleteBuilder = class {
   }
   /**
    * Adds this delete operation to a transaction.
+   * Use this method when you need to:
+   * - Coordinate dinosaur transfers
+   * - Manage habitat decommissioning
+   * - Handle species relocations
    *
    * @example
    * ```ts
@@ -1254,6 +1258,11 @@ var DeleteBuilder = class {
   /**
    * Gets a human-readable representation of the delete command
    * with all expression placeholders replaced by their actual values.
+   * Use this method when you need to:
+   * - Debug complex deletion conditions
+   * - Verify safety checks
+   * - Log removal operations
+   * - Troubleshoot failed deletions
    *
    * @example
    * ```ts
@@ -1312,6 +1321,10 @@ var UpdateBuilder = class {
   }
   /**
    * Removes an attribute from the item.
+   * Use this method when you need to:
+   * - Delete attributes completely
+   * - Remove nested attributes
+   * - Clean up deprecated fields
    *
    * @example
    * ```typescript
@@ -1338,6 +1351,10 @@ var UpdateBuilder = class {
   }
   /**
    * Adds a value to a number attribute or adds elements to a set.
+   * Use this method when you need to:
+   * - Increment counters
+   * - Add elements to a set atomically
+   * - Update numerical statistics
    *
    * @example
    * ```typescript
@@ -1366,6 +1383,10 @@ var UpdateBuilder = class {
   }
   /**
    * Removes elements from a set attribute.
+   * Use this method when you need to:
+   * - Remove specific elements from a set
+   * - Update set-based attributes atomically
+   * - Maintain set membership
    *
    * @example
    * ```typescript
@@ -1375,7 +1396,7 @@ var UpdateBuilder = class {
    *   ['JUNGLE', 'COASTAL']
    * );
    *
-   * // Remove from sets using Set DynamoItems
+   * // Remove from sets using Set objects
    * builder.deleteElementsFromSet(
    *   'knownBehaviors',
    *   new Set(['NOCTURNAL', 'TERRITORIAL'])
@@ -1408,6 +1429,11 @@ var UpdateBuilder = class {
   }
   /**
    * Adds a condition that must be satisfied for the update to succeed.
+   * Use this method when you need to:
+   * - Implement optimistic locking
+   * - Ensure item state before update
+   * - Validate business rules
+   * - Prevent concurrent modifications
    *
    * @example
    * ```typescript
@@ -1439,7 +1465,7 @@ var UpdateBuilder = class {
    * );
    * ```
    *
-   * @param condition - Either a Condition DynamoItem or a callback function that builds the condition
+   * @param condition - Either a Condition object or a callback function that builds the condition
    * @returns The builder instance for method chaining
    */
   condition(condition) {
@@ -1468,6 +1494,11 @@ var UpdateBuilder = class {
   }
   /**
    * Sets which item attributes to include in the response.
+   * Use this method when you need to:
+   * - Get the complete updated item
+   * - Track changes to specific attributes
+   * - Compare old and new values
+   * - Monitor attribute modifications
    *
    * Available options:
    * - ALL_NEW: All attributes after the update
@@ -1595,6 +1626,10 @@ var UpdateBuilder = class {
   }
   /**
    * Adds this update operation to a transaction.
+   * Use this method when you need to:
+   * - Update items as part of a larger transaction
+   * - Ensure multiple updates are atomic
+   * - Coordinate updates across multiple items
    *
    * @example
    * ```typescript
@@ -1624,6 +1659,11 @@ var UpdateBuilder = class {
   }
   /**
    * Gets a human-readable representation of the update command.
+   * Use this method when you need to:
+   * - Debug complex update expressions
+   * - Verify attribute names and values
+   * - Log update operations
+   * - Troubleshoot condition expressions
    *
    * @example
    * ```typescript
@@ -1650,6 +1690,10 @@ var UpdateBuilder = class {
   }
   /**
    * Executes the update operation against DynamoDB.
+   * Use this method when you need to:
+   * - Apply updates immediately
+   * - Get the updated item values
+   * - Handle conditional update failures
    *
    * @example
    * ```typescript
@@ -1684,7 +1728,7 @@ var UpdateBuilder = class {
    * }
    * ```
    *
-   * @returns A promise that resolves to an DynamoItem containing the updated item (if returnValues is set)
+   * @returns A promise that resolves to an object containing the updated item (if returnValues is set)
    * @throws {ConditionalCheckFailedException} If the condition check fails
    * @throws {Error} If the update operation fails for other reasons
    */
@@ -1738,7 +1782,7 @@ var TransactionBuilder = class {
    */
   checkForDuplicateItem(tableName, newItem) {
     const pkName = this.indexConfig.partitionKey;
-    const skName = this.indexConfig.sortKey ?? "";
+    const skName = this.indexConfig.sortKey || "";
     const pkValue = newItem[pkName];
     const skValue = skName ? newItem[skName] : void 0;
     if (!pkValue) {
@@ -1779,18 +1823,6 @@ var TransactionBuilder = class {
       );
     }
   }
-  createKeyForPrimaryIndex(key) {
-    const keyCondition = {
-      [this.indexConfig.partitionKey]: key.pk
-    };
-    if (this.indexConfig.sortKey) {
-      if (key.sk === void 0) {
-        throw new Error("Sort key is required for delete operation");
-      }
-      keyCondition[this.indexConfig.sortKey] = key.sk;
-    }
-    return keyCondition;
-  }
   /**
    * Adds a put operation to the transaction.
    * Use this method when you need to:
@@ -1930,13 +1962,15 @@ var TransactionBuilder = class {
    * @throws {Error} If a duplicate item is detected in the transaction
    */
   delete(tableName, key, condition) {
-    const keyCondition = this.createKeyForPrimaryIndex(key);
-    this.checkForDuplicateItem(tableName, keyCondition);
+    this.checkForDuplicateItem(tableName, key);
     const transactionItem = {
       type: "Delete",
       params: {
         tableName,
-        key: keyCondition
+        key: {
+          pk: key.pk,
+          sk: key.sk
+        }
       }
     };
     if (condition) {
@@ -1978,14 +2012,10 @@ var TransactionBuilder = class {
    * @see DeleteBuilder for creating delete commands
    */
   deleteWithCommand(command) {
-    const keyCondition = this.createKeyForPrimaryIndex(command.key);
-    this.checkForDuplicateItem(command.tableName, keyCondition);
+    this.checkForDuplicateItem(command.tableName, command.key);
     const transactionItem = {
       type: "Delete",
-      params: {
-        ...command,
-        key: keyCondition
-      }
+      params: command
     };
     this.items.push(transactionItem);
     return this;
@@ -2045,13 +2075,15 @@ var TransactionBuilder = class {
    * @throws {Error} If a duplicate item is detected in the transaction
    */
   update(tableName, key, updateExpression, expressionAttributeNames, expressionAttributeValues, condition) {
-    const keyCondition = this.createKeyForPrimaryIndex(key);
-    this.checkForDuplicateItem(tableName, keyCondition);
+    this.checkForDuplicateItem(tableName, key);
     const transactionItem = {
       type: "Update",
       params: {
         tableName,
-        key: keyCondition,
+        key: {
+          pk: key.pk,
+          sk: key.sk
+        },
         updateExpression,
         expressionAttributeNames,
         expressionAttributeValues
@@ -2105,14 +2137,10 @@ var TransactionBuilder = class {
    * @see UpdateBuilder for creating update commands
    */
   updateWithCommand(command) {
-    const keyCondition = this.createKeyForPrimaryIndex(command.key);
-    this.checkForDuplicateItem(command.tableName, keyCondition);
+    this.checkForDuplicateItem(command.tableName, command.key);
     const transactionItem = {
       type: "Update",
-      params: {
-        ...command,
-        key: keyCondition
-      }
+      params: command
     };
     this.items.push(transactionItem);
     return this;
@@ -2169,8 +2197,7 @@ var TransactionBuilder = class {
    * @throws {Error} If condition expression generation fails
    */
   conditionCheck(tableName, key, condition) {
-    const keyCondition = this.createKeyForPrimaryIndex(key);
-    this.checkForDuplicateItem(tableName, keyCondition);
+    this.checkForDuplicateItem(tableName, key);
     const { expression, names, values } = prepareExpressionParams(condition);
     if (!expression) {
       throw new Error("Failed to generate condition expression");
@@ -2179,7 +2206,10 @@ var TransactionBuilder = class {
       type: "ConditionCheck",
       params: {
         tableName,
-        key: keyCondition,
+        key: {
+          pk: key.pk,
+          sk: key.sk
+        },
         conditionExpression: expression,
         expressionAttributeNames: names,
         expressionAttributeValues: values
@@ -2219,14 +2249,10 @@ var TransactionBuilder = class {
    * @see ConditionCheckBuilder for creating condition check commands
    */
   conditionCheckWithCommand(command) {
-    const keyCondition = this.createKeyForPrimaryIndex(command.key);
-    this.checkForDuplicateItem(command.tableName, keyCondition);
+    this.checkForDuplicateItem(command.tableName, command.key);
     const transactionItem = {
       type: "ConditionCheck",
-      params: {
-        ...command,
-        key: keyCondition
-      }
+      params: command
     };
     this.items.push(transactionItem);
     return this;
@@ -2459,7 +2485,7 @@ var ConditionCheckBuilder = class {
    * );
    * ```
    *
-   * @param condition - Either a Condition DynamoItem or a callback function that builds the condition
+   * @param condition - Either a Condition object or a callback function that builds the condition
    * @returns The builder instance for method chaining
    */
   condition(condition) {
@@ -2685,18 +2711,18 @@ var GetBuilder = class {
    *          - item: The retrieved dinosaur or undefined if not found
    */
   async execute() {
-    const expressionParams = {
-      expressionAttributeNames: {},
-      expressionAttributeValues: {},
-      valueCounter: { count: 0 }
-    };
-    const projectionExpression = Array.from(this.selectedFields).map((p) => generateAttributeName(expressionParams, p)).join(", ");
-    const { expressionAttributeNames } = expressionParams;
-    return this.executor({
-      ...this.params,
-      projectionExpression: projectionExpression.length > 0 ? projectionExpression : void 0,
-      expressionAttributeNames: Object.keys(expressionAttributeNames).length > 0 ? expressionAttributeNames : void 0
-    });
+    if (this.selectedFields.size > 0) {
+      const expressionAttributeNames = {};
+      const projectionParts = [];
+      for (const path of this.selectedFields) {
+        const attrName = `#attr${projectionParts.length}`;
+        expressionAttributeNames[attrName] = path;
+        projectionParts.push(attrName);
+      }
+      this.params.projectionExpression = projectionParts.join(", ");
+      this.params.expressionAttributeNames = expressionAttributeNames;
+    }
+    return this.executor(this.params);
   }
 };
 
@@ -2791,16 +2817,6 @@ var Table = class {
     this.sortKey = config.indexes.sortKey;
     this.gsis = config.indexes.gsis || {};
   }
-  createKeyForPrimaryIndex(keyCondition) {
-    const primaryCondition = { [this.partitionKey]: keyCondition.pk };
-    if (this.sortKey) {
-      if (!keyCondition.sk) {
-        throw new Error("Sort key has not been provided but the Table has a sort key");
-      }
-      primaryCondition[this.sortKey] = keyCondition.sk;
-    }
-    return primaryCondition;
-  }
   /**
    * Creates a new item in the table, it will fail if the item already exists
    *
@@ -2815,7 +2831,7 @@ var Table = class {
       try {
         const result = await this.dynamoClient.get({
           TableName: params.tableName,
-          Key: this.createKeyForPrimaryIndex(keyCondition),
+          Key: params.key,
           ProjectionExpression: params.projectionExpression,
           ExpressionAttributeNames: params.expressionAttributeNames,
           ConsistentRead: params.consistentRead
@@ -2850,12 +2866,13 @@ var Table = class {
           ReturnValues: params.returnValues === "CONSISTENT" ? "NONE" : params.returnValues
         });
         if (params.returnValues === "CONSISTENT") {
+          const key = {
+            pk: params.item[this.partitionKey],
+            ...this.sortKey && { sk: params.item[this.sortKey] }
+          };
           const getResult = await this.dynamoClient.get({
             TableName: params.tableName,
-            Key: this.createKeyForPrimaryIndex({
-              pk: params.item[this.partitionKey],
-              ...this.sortKey && { sk: params.item[this.sortKey] }
-            }),
+            Key: key,
             ConsistentRead: true
           });
           return getResult.Item;
@@ -3039,7 +3056,7 @@ var Table = class {
       try {
         const result = await this.dynamoClient.delete({
           TableName: params.tableName,
-          Key: this.createKeyForPrimaryIndex(keyCondition),
+          Key: params.key,
           ConditionExpression: params.conditionExpression,
           ExpressionAttributeNames: params.expressionAttributeNames,
           ExpressionAttributeValues: params.expressionAttributeValues,
@@ -3066,7 +3083,7 @@ var Table = class {
       try {
         const result = await this.dynamoClient.update({
           TableName: params.tableName,
-          Key: this.createKeyForPrimaryIndex(keyCondition),
+          Key: params.key,
           UpdateExpression: params.updateExpression,
           ConditionExpression: params.conditionExpression,
           ExpressionAttributeNames: params.expressionAttributeNames,
@@ -3194,7 +3211,10 @@ var Table = class {
         }
         return {
           DeleteRequest: {
-            Key: this.createKeyForPrimaryIndex(operation.key)
+            Key: {
+              [this.partitionKey]: operation.key.pk,
+              ...this.sortKey ? { [this.sortKey]: operation.key.sk } : {}
+            }
           }
         };
       });
@@ -3237,7 +3257,28 @@ var Table = class {
     };
   }
 };
-
-export { Table };
-//# sourceMappingURL=table.js.map
-//# sourceMappingURL=table.js.map
+export {
+  ConditionCheckBuilder,
+  DeleteBuilder,
+  Paginator,
+  PutBuilder,
+  QueryBuilder,
+  Table,
+  TransactionBuilder,
+  UpdateBuilder,
+  and,
+  attributeExists,
+  attributeNotExists,
+  beginsWith,
+  between,
+  contains,
+  createComparisonCondition,
+  eq,
+  gt,
+  gte,
+  lt,
+  lte,
+  ne,
+  not,
+  or
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dyno-table",
-  "version": "0.2.0-0",
+  "version": "1.0.0-alpha.1",
   "description": "A TypeScript library to simplify working with DynamoDB",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -11,80 +11,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
-    },
-    "./table": {
-      "types": "./dist/table.d.ts",
-      "import": "./dist/table.js",
-      "require": "./dist/table.cjs"
-    },
-    "./entity": {
-      "types": "./dist/entity.d.ts",
-      "import": "./dist/entity.js",
-      "require": "./dist/entity.cjs"
-    },
-    "./conditions": {
-      "types": "./dist/conditions.d.ts",
-      "import": "./dist/conditions.js",
-      "require": "./dist/conditions.cjs"
-    },
-    "./types": {
-      "types": "./dist/types.d.ts",
-      "import": "./dist/types.js",
-      "require": "./dist/types.cjs"
-    },
-    "./standard-schema": {
-      "types": "./dist/standard-schema.d.ts",
-      "import": "./dist/standard-schema.js",
-      "require": "./dist/standard-schema.cjs"
-    },
-    "./utils/partition-key-template": {
-      "types": "./dist/utils/partition-key-template.d.ts",
-      "import": "./dist/utils/partition-key-template.js",
-      "require": "./dist/utils/partition-key-template.cjs"
-    },
-    "./utils/sort-key-template": {
-      "types": "./dist/utils/sort-key-template.d.ts",
-      "import": "./dist/utils/sort-key-template.js",
-      "require": "./dist/utils/sort-key-template.cjs"
-    },
-    "./builders/query-builder": {
-      "types": "./dist/builders/query-builder.d.ts",
-      "import": "./dist/builders/query-builder.js",
-      "require": "./dist/builders/query-builder.cjs"
-    },
-    "./builders/paginator": {
-      "types": "./dist/builders/paginator.d.ts",
-      "import": "./dist/builders/paginator.js",
-      "require": "./dist/builders/paginator.cjs"
-    },
-    "./builders/put-builder": {
-      "types": "./dist/builders/put-builder.d.ts",
-      "import": "./dist/builders/put-builder.js",
-      "require": "./dist/builders/put-builder.cjs"
-    },
-    "./builders/update-builder": {
-      "types": "./dist/builders/update-builder.d.ts",
-      "import": "./dist/builders/update-builder.js",
-      "require": "./dist/builders/update-builder.cjs"
-    },
-    "./builders/delete-builder": {
-      "types": "./dist/builders/delete-builder.d.ts",
-      "import": "./dist/builders/delete-builder.js",
-      "require": "./dist/builders/delete-builder.cjs"
-    },
-    "./builders/transaction-builder": {
-      "types": "./dist/builders/transaction-builder.d.ts",
-      "import": "./dist/builders/transaction-builder.js",
-      "require": "./dist/builders/transaction-builder.cjs"
-    },
-    "./builders/condition-check-builder": {
-      "types": "./dist/builders/condition-check-builder.d.ts",
-      "import": "./dist/builders/condition-check-builder.js",
-      "require": "./dist/builders/condition-check-builder.cjs"
     }
   },
   "scripts": {
-    "build": "tsup --config tsup.config.ts",
+    "build": "tsup src/index.ts --format esm,cjs --dts",
     "clean": "rm -rf dist",
     "test": "vitest run",
     "test:w": "vitest watch",
@@ -111,11 +41,14 @@
   "devDependencies": {
     "@babel/preset-typescript": "^7.26.0",
     "@biomejs/biome": "1.9.4",
-    "@types/node": "^20.17.11",
-    "rimraf": "^5.0.10",
-    "tsup": "^8.3.5",
-    "typescript": "^5.7.2",
-    "vitest": "3.0.5"
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@types/node": "^20.0.0",
+    "rimraf": "^5.0.0",
+    "semantic-release": "24.2.3",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^2.1.8"
   },
   "peerDependencies": {
     "@aws-sdk/client-dynamodb": "^3.0.0",

package/dist/builder-types-C_PDZhnP.d.ts

@@ -1,118 +0,0 @@
-import { DynamoItem, TableConfig } from './types.js';
-
-/**
- * Interface for DynamoDB command objects that can contain expressions
- */
-interface DynamoCommandWithExpressions {
-    conditionExpression?: string;
-    updateExpression?: string;
-    filterExpression?: string;
-    keyConditionExpression?: string;
-    projectionExpression?: string;
-    expressionAttributeNames?: Record<string, string>;
-    expressionAttributeValues?: Record<string, unknown>;
-    [key: string]: unknown;
-}
-
-interface DeleteCommandParams extends DynamoCommandWithExpressions {
-    tableName: string;
-    key: Record<string, unknown>;
-    conditionExpression?: string;
-    expressionAttributeNames?: Record<string, string>;
-    expressionAttributeValues?: DynamoItem;
-    returnValues?: "ALL_OLD";
-}
-/**
- * Parameters for the DynamoDB put command.
- *
- * These parameters are used when executing the operation against DynamoDB.
- *
- * The `returnValues` property can be:
- * - `"ALL_OLD"`: Return the attributes of the item as they were before the operation
- * - `"NONE"`: Return nothing
- * - `"CONSISTENT"`: Triggers a GET operation after the put to retrieve the updated item state
- */
-interface PutCommandParams extends DynamoCommandWithExpressions {
-    tableName: string;
-    item: DynamoItem;
-    conditionExpression?: string;
-    expressionAttributeNames?: Record<string, string>;
-    expressionAttributeValues?: Record<string, unknown>;
-    returnValues?: "ALL_OLD" | "NONE" | "CONSISTENT";
-}
-/**
- * Parameters for the DynamoDB update command.
- * These parameters are used when executing the operation against DynamoDB.
- */
-interface UpdateCommandParams extends DynamoCommandWithExpressions {
-    /** The name of the DynamoDB table */
-    tableName: string;
-    /** The primary key of the item to update */
-    key: Record<string, unknown>;
-    /** The update expression (SET, REMOVE, ADD, DELETE clauses) */
-    updateExpression: string;
-    /** Optional condition expression that must be satisfied */
-    conditionExpression?: string;
-    /** Map of expression attribute name placeholders to actual names */
-    expressionAttributeNames?: Record<string, string>;
-    /** Map of expression attribute value placeholders to actual values */
-    expressionAttributeValues?: DynamoItem;
-    /** Which item attributes to include in the response */
-    returnValues?: "ALL_NEW" | "UPDATED_NEW" | "ALL_OLD" | "UPDATED_OLD" | "NONE";
-}
-interface ConditionCheckCommandParams extends DynamoCommandWithExpressions {
-    tableName: string;
-    key: Record<string, unknown>;
-    conditionExpression: string;
-    expressionAttributeNames?: Record<string, string>;
-    expressionAttributeValues?: DynamoItem;
-}
-/**
- * Base interface for all builder classes that support pagination
- * to be used by Paginator without creating circular dependencies.
- */
-interface BaseBuilderInterface<T extends DynamoItem, TConfig extends TableConfig = TableConfig, B = unknown> {
-    clone(): B;
-    limit(limit: number): B;
-    getLimit(): number | undefined;
-    startFrom(lastEvaluatedKey: DynamoItem): B;
-    execute(): Promise<{
-        items: T[];
-        lastEvaluatedKey?: DynamoItem;
-    }>;
-}
-/**
- * Interface for the QueryBuilder class to be used by Paginator
- * without creating a circular dependency.
- */
-interface QueryBuilderInterface<T extends DynamoItem, TConfig extends TableConfig = TableConfig> extends BaseBuilderInterface<T, TConfig, QueryBuilderInterface<T, TConfig>> {
-}
-/**
- * Interface for the ScanBuilder class to be used by Paginator
- * without creating a circular dependency.
- */
-interface ScanBuilderInterface<T extends DynamoItem, TConfig extends TableConfig = TableConfig> extends BaseBuilderInterface<T, TConfig, ScanBuilderInterface<T, TConfig>> {
-}
-/**
- * Interface for the FilterBuilder class to be used by Paginator
- * without creating a circular dependency.
- */
-interface FilterBuilderInterface<T extends DynamoItem, TConfig extends TableConfig = TableConfig> extends BaseBuilderInterface<T, TConfig, FilterBuilderInterface<T, TConfig>> {
-}
-/**
- * Represents the result of a single page query operation.
- * This interface provides all necessary information about the current page
- * and the availability of subsequent pages.
- */
-interface PaginationResult<T> {
-    /** The items (dinosaurs, habitats, etc.) retrieved for the current page */
-    items: T[];
-    /** DynamoDB's last evaluated key, used internally for pagination */
-    lastEvaluatedKey?: DynamoItem;
-    /** Indicates whether there are more pages available */
-    hasNextPage: boolean;
-    /** The current page number (1-indexed) */
-    page: number;
-}
-
-export type { ConditionCheckCommandParams as C, DeleteCommandParams as D, FilterBuilderInterface as F, PaginationResult as P, QueryBuilderInterface as Q, ScanBuilderInterface as S, UpdateCommandParams as U, PutCommandParams as a };