dyna-record 0.1.5 → 0.2.1

package/dist/src/operations/Update/Update.d.ts

@@ -1,50 +1,211 @@
 import type DynaRecord from "../../DynaRecord";
+import { TransactWriteBuilder } from "../../dynamo-utils";
 import OperationBase from "../OperationBase";
 import type { UpdatedAttributes, UpdateOptions } from "./types";
 import type { EntityClass } from "../../types";
 /**
- * Facilitates the operation of updating an existing entity in the database, including handling updates to its attributes and managing changes to its relationships. It will de-normalize data to support relationship links
+ * Represents an update operation for a DynaRecord-backed entity, handling both attribute updates and relationship consistency via denormalization.
  *
- * The `Update` operation supports updating entity attributes and ensures consistency in relationships, especially for "BelongsTo" relationships. It handles the complexity of managing foreign keys and associated "BelongsToLink" records, including creating new links for updated relationships and removing outdated links when necessary.
+ * This class supports updating an existing entity and managing its relational links, specifically:
+ * - Updating entity attributes while preserving schema constraints.
+ * - Managing "BelongsTo" relationship links by creating or removing associated denormalized records.
+ * - Ensuring that if a foreign key changes, the old link record is removed, preventing stale references.
  *
- * Only attributes defined on the model can be configured, and will be enforced via types and runtime schema validation.
+ * Only attributes defined on the model can be updated. Both compile-time and runtime checks help ensure that updated values are valid.
+ *
+ * **Example**
+ * ```typescript
+ * const updateOp = new Update(MyEntityClass);
+ * await updateOp.run("entityId", { name: "NewName", status: "active" });
+ * ```
  *
  * @template T - The type of the entity being updated, extending `DynaRecord`.
  */
 declare class Update<T extends DynaRecord> extends OperationBase<T> {
-    #private;
-    constructor(Entity: EntityClass<T>);
+    protected readonly transactionBuilder: TransactWriteBuilder;
+    constructor(Entity: EntityClass<T>, transactionBuilder?: TransactWriteBuilder);
+    /**
+     * Executes the update operation against DynamoDB.
+     *
+     * **What it does:**
+     * - Fetches the current state of the entity and any related "Has" relationship entities.
+     * - Constructs an update expression for the main entity's attributes.
+     * - Applies the same update expression to related entities and "BelongsTo" link records to maintain denormalized consistency.
+     * - Manages foreign key changes by creating new link items and removing old link items.
+     *
+     * @param id - The unique identifier of the entity being updated.
+     * @param attributes - Partial set of entity attributes to update. Must be defined on the entity's model.
+     * @returns A promise that resolves to the set of updated attributes as applied to the entity.
+     * @throws If the entity does not exist, an error is thrown.
+     */
+    run(id: string, attributes: UpdateOptions<DynaRecord>): Promise<UpdatedAttributes<T>>;
+    protected commitTransaction(): Promise<void>;
+    /**
+     * BelongsToRelationship meta data and foreign key value pair for foreign keys being updated
+     * @param attributes
+     * @returns
+     */
+    private getBelongsToRelMetaAndKeyForUpdatedKeys;
+    /**
+     * Pre-fetches the target entity and any related entities from the database. This is done using a strong read operation to ensure consistency.
+     *
+     * **What it does:**
+     * - Retrieves the main entity and all linked entities in the entity's partition.
+     * - Performs a TransactGetItem operation on entities linked bai foreign keys (BelongsTo) to support denormalizing copies to associated partitions
+     * - Filters these entities to separate the main entity and its related link records.
+     *
+     * @param id - The unique identifier of the entity being fetched.
+     * @param belongsToRelFkAndMetas - BelongsTo relationship meta objects with foreign keys used for fetching associated records
+     * @returns A promise that resolves to an object containing:
+     *   - `entityPreUpdate`: The current state of the entity before updates.
+     *   - `relatedEntities`: An array of related link entities.
+     * @throws If the entity does not exist, it throws a NotFoundError.
+     * @private
+     */
+    private preFetch;
     /**
-     * Update entity transactions, including transactions to create/update BelongsToLinks
-     * @param id The id of the entity being updated
-     * @param attributes Attributes on the model to update.
+     * {reprocess pre-fetch data for processing
+     * @param id
+     * @param entities
+     * @param belongsToRelFkAndMetas
+     * @returns
      */
-    run(id: string, attributes: UpdateOptions<T>): Promise<UpdatedAttributes<T>>;
+    private preProcessFetchedData;
     /**
-     * Build the transaction to update the entity
-     * @param id The id of the entity being updated
-     * @param attributes Attributes on the model to update.
+     * Constructs updated attributes and the corresponding DynamoDB update expression.
+     *
+     * **What it does:**
+     * - Merges the provided attributes with `updatedAt` (automatically set to the current time).
+     * - Converts the updated attributes into a DynamoDB update expression.
+     *
+     * @param attributes - The partial attributes to be updated on the entity.
+     * @returns An object containing:
+     *   - `updatedAttrs`: The final updated attribute set.
+     *   - `expression`: A DynamoDB update expression to apply these changes.
+     * @private
+     */
+    private buildUpdateMetadata;
+    /**
+     * Adds a transaction operation to update the main entity's record.
+     *
+     * **What it does:**
+     * - Builds a DynamoDB Update transaction using the provided update expression.
+     * - Adds a condition to ensure the entity exists before updating.
+     *
+     * @param id - The unique identifier of the entity being updated.
+     * @param updateExpression - The DynamoDB update expression describing the changes.
+     * @private
      */
     private buildUpdateItemTransaction;
     /**
-     * Builds the transactions to persist relationships
-     *   - Creates BelongsToLinks when a foreign key changes
-     *   - Removes outdated BelongsToLinks if the entity previously was associated with a different entity
-     * @param id The id of the entity being updated
-     * @param attributes Attributes on the model to update.
+     * Builds all necessary transactions to handle "BelongsTo" or uni-directional "OwnedBy" relationships when updating the entity.
+     *
+     * **What it does:**
+     * - Checks if any foreign keys for "BelongsTo" or uni-directional "OwnedBy" relationships have changed.
+     * - If so, updates or creates new denormalized link records in the related partitions.
+     * - Removes old link records that are no longer valid due to foreign key changes.
+     *
+     * @param entityPreUpdate - The state of the entity before the update.
+     * @param updatedEntity - The entity state after proposed updates (partial attributes).
+     * @param updateExpression - The DynamoDB update expression representing the attribute updates.
+     * @private
+     */
+    private buildBelongsToTransactions;
+    /**
+     * Creates or updates the denormalized link record for a "BelongsTo" relationship to the related entity's partition.
+     *
+     * **What it does:**
+     * - Builds a DynamoDB Update transaction for the linked record identified by the relationship and foreign key.
+     * - Ensures the linked record exists before updating (if not, it will fail).
+     *
+     * @param entityId - The identifier of the main entity being updated.
+     * @param relMeta - Metadata describing the "BelongsTo" relationship.
+     * @param foreignKey - The new foreign key value after updates.
+     * @param updateExpression - The DynamoDB update expression for the attribute changes.
+     * @private
+     */
+    private buildUpdateBelongsToLinkedRecords;
+    /**
+     * Builds transactions to persist an updated/new belongs to record
+     * Denormalizes data to the entity being updates's partition and a link to the foreign entities partition
+     * Ensures that the new entity foreign key exists
+     * @param updatedEntity
+     * @param relMeta
+     * @param foreignKey
+     * @param newBelongsToEntityLookup
+     * @param persistToSelfCondition
+     * @param persistToSelfConditionErrMessage
+     */
+    private buildPutBelongsToLinkedRecords;
+    /**
+     * Builds a condition expression that an entity exists
+     * @param relMeta
+     * @param foreignKey
+     */
+    private buildEntityExistsCondition;
+    /**
+     * Denormalizes a link for the entity being updated to the new entities partition
+     * @param updatedEntity
+     * @param relMeta
+     * @param foreignKey
+     */
+    private buildLinkToForeignEntityTransaction;
+    /**
+     * Builds the transaction to add or replace the linked record for the foreign entity in the entity being updates partition
+     * @param updatedEntity
+     * @param relMeta
+     * @param foreignKey
+     * @param newBelongsToEntityLookup
+     * @param persistToSelfCondition
+     * @param persistToSelfConditionErrMessage
+     */
+    private buildAddForeignEntityToSelfTransaction;
+    /**
+     * Removes the old link record associated with a previous "BelongsTo" foreign key when the foreign key changes.
+     *
+     * **What it does:**
+     * - Builds a DynamoDB Delete transaction to remove the stale link record from the old relationship partition.
+     *
+     * @param entityId - The identifier of the entity whose foreign key was changed.
+     * @param relMeta - Metadata describing the "BelongsTo" relationship.
+     * @param oldForeignKey - The old foreign key value that should no longer link to the entity.
+     * @private
+     */
+    private removeForeignKeysTransactions;
+    /**
+     * Builds the transactions for updating the foreign key of an entity from one key to another
+     * @param updatedEntity
+     * @param relMeta
+     * @param newForeignKey
+     * @param oldForeignKey
+     * @param newBelongsToEntityLookup
+     */
+    private updateForeignKeyTransactions;
+    /**
+     * Builds transactions to update all related entities that exist in the main entity's partition, applying the same attribute updates.
+     *
+     * **What it does:**
+     * - For each linked entity found in `preFetch`, attempts to apply the same update expression.
+     * - Ensures each related entity exists before attempting to update.
+     *
+     * @param relatedEntities - An array of entities that are related to the primary entity and need synchronized attribute updates.
+     * @param expression - The DynamoDB update expression to apply to related entities.
+     * @private
      */
-    private buildRelationshipTransactions;
+    private buildUpdateRelatedEntityLinks;
     /**
-     * When updating the foreign key of an entity, delete the BelongsToLink in the previous relationships partition
-     * @param rel
-     * @param relType
+     * Builds the table key for a related entity that needs to be updated
+     * @param id - The id of the entity being updated
      * @param entity
+     * @param relLookup
+     * @returns
      */
-    private buildDeleteOldBelongsToLinkTransaction;
+    private buildUpdatedRelatedEntityLinkKey;
     /**
-     * If updating a ForeignKey, look up the current state of the item to build transactions
+     * Build a lookup object to lookup a HasAndBelongsToMany relationship for an entity. Used for processing to avoid excessive looping
+     * @returns
      */
-    private getEntity;
+    private buildHasAndBelongsToManyRelLookup;
 }
 export default Update;
 //# sourceMappingURL=Update.d.ts.map

package/dist/src/operations/Update/Update.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Update.d.ts","sourceRoot":"","sources":["../../../../src/operations/Update/Update.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAC;AAa/C,OAAO,aAAa,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG/C;;;;;;;;GAQG;AACH,cAAM,MAAM,CAAC,CAAC,SAAS,UAAU,CAAE,SAAQ,aAAa,CAAC,CAAC,CAAC;;gBAK7C,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;IAKlC;;;;OAIG;IACU,GAAG,CACd,EAAE,EAAE,MAAM,EACV,UAAU,EAAE,aAAa,CAAC,CAAC,CAAC,GAC3B,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC;IAahC;;;;OAIG;IACH,OAAO,CAAC,0BAA0B;IAoClC;;;;;;OAMG;YACW,6BAA6B;IAsB3C;;;;;OAKG;IACH,OAAO,CAAC,sCAAsC;IAyB9C;;OAEG;YACW,SAAS;CAOxB;AAED,eAAe,MAAM,CAAC"}
+{"version":3,"file":"Update.d.ts","sourceRoot":"","sources":["../../../../src/operations/Update/Update.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAGL,oBAAoB,EACrB,MAAM,oBAAoB,CAAC;AAkB5B,OAAO,aAAa,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAChE,OAAO,KAAK,EAAmB,WAAW,EAAgB,MAAM,aAAa,CAAC;AA4D9E;;;;;;;;;;;;;;;;;GAiBG;AACH,cAAM,MAAM,CAAC,CAAC,SAAS,UAAU,CAAE,SAAQ,aAAa,CAAC,CAAC,CAAC;IACzD,SAAS,CAAC,QAAQ,CAAC,kBAAkB,EAAE,oBAAoB,CAAC;gBAG1D,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,EACtB,kBAAkB,CAAC,EAAE,oBAAoB;IAO3C;;;;;;;;;;;;;OAaG;IACU,GAAG,CACd,EAAE,EAAE,MAAM,EACV,UAAU,EAAE,aAAa,CAAC,UAAU,CAAC,GACpC,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC;cA4ChB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IAIlD;;;;OAIG;IACH,OAAO,CAAC,uCAAuC;IAY/C;;;;;;;;;;;;;;;OAeG;YACW,QAAQ;IAqDtB;;;;;;OAMG;IACH,OAAO,CAAC,qBAAqB;IA4B7B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,mBAAmB;IAY3B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,0BAA0B;IAyBlC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,0BAA0B;IAuDlC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,iCAAiC;IAuBzC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,8BAA8B;IA+BtC;;;;OAIG;IACH,OAAO,CAAC,0BAA0B;IAkBlC;;;;;OAKG;IACH,OAAO,CAAC,mCAAmC;IAsB3C;;;;;;;;OAQG;IACH,OAAO,CAAC,sCAAsC;IAqC9C;;;;;;;;;;OAUG;IACH,OAAO,CAAC,6BAA6B;IAuCrC;;;;;;;OAOG;IACH,OAAO,CAAC,4BAA4B;IA6BpC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,6BAA6B;IAwBrC;;;;;;OAMG;IACH,OAAO,CAAC,gCAAgC;IAgBxC;;;OAGG;IACH,OAAO,CAAC,iCAAiC;CAU1C;AAED,eAAe,MAAM,CAAC"}