dyno-table 2.1.0 → 2.2.0

package/dist/entity.d.ts

@@ -1,18 +1,20 @@
-import { G as GetBuilder } from './batch-builder-BytHNL_u.js';
-import { S as ScanBuilder, T as Table } from './table-BhEeYauU.js';
-import { UpdateBuilder } from './builders/update-builder.js';
-import { StandardSchemaV1 } from './standard-schema.js';
 import { DynamoItem, TableConfig, Index } from './types.js';
 import { PutBuilder } from './builders/put-builder.js';
+import { G as GetBuilder } from './batch-builder-Cdo49C2r.js';
 import { DeleteBuilder } from './builders/delete-builder.js';
-import { Q as QueryBuilder } from './query-builder-BNWRCrJW.js';
-import { r as PrimaryKeyWithoutExpression, P as PrimaryKey } from './conditions-DD0bvyHm.js';
-import './builder-types-CzuLR4Th.js';
-import './builders/transaction-builder.js';
+import { UpdateBuilder } from './builders/update-builder.js';
+import { s as Path, t as PathType, C as Condition, q as ConditionOperator, r as PrimaryKeyWithoutExpression, P as PrimaryKey } from './conditions-DD0bvyHm.js';
+import { TransactionBuilder } from './builders/transaction-builder.js';
+import { U as UpdateCommandParams } from './builder-types-CzuLR4Th.js';
+import { T as Table, S as ScanBuilder } from './table-CZBMkW2Z.js';
+import { Q as QueryBuilder } from './query-builder-CUWdavZw.js';
+import { StandardSchemaV1 } from './standard-schema.js';
 import '@aws-sdk/lib-dynamodb';
 import './builders/condition-check-builder.js';
 import './builders/paginator.js';
 
+type SetElementType<T> = T extends Set<infer U> ? U : T extends Array<infer U> ? U : never;
+type PathSetElementType<T, K extends Path<T>> = SetElementType<PathType<T, K>>;
 /**
  * Entity-aware wrapper for PutBuilder that automatically provides entity name to batch operations
  */
@@ -31,8 +33,87 @@ type EntityAwareGetBuilder<T extends DynamoItem> = GetBuilder<T> & {
 type EntityAwareDeleteBuilder = DeleteBuilder & {
     readonly entityName: string;
 };
+/**
+ * Entity-aware wrapper for UpdateBuilder that adds forceIndexRebuild functionality
+ * and automatically provides entity name to batch operations
+ */
+declare class EntityAwareUpdateBuilder<T extends DynamoItem> {
+    private forceRebuildIndexes;
+    readonly entityName: string;
+    private builder;
+    private entityConfig?;
+    private updateDataApplied;
+    constructor(builder: UpdateBuilder<T>, entityName: string);
+    /**
+     * Configure entity-specific logic for automatic timestamp generation and index updates
+     */
+    configureEntityLogic(config: {
+        data: Partial<T>;
+        key: T;
+        table: Table;
+        indexes: Record<string, IndexDefinition<T>> | undefined;
+        generateTimestamps: () => Record<string, string | number>;
+        buildIndexUpdates: (currentData: T, updates: Partial<T>, table: Table, indexes: Record<string, IndexDefinition<T>> | undefined, forceRebuildIndexes?: string[]) => Record<string, string>;
+    }): void;
+    /**
+     * Forces a rebuild of one or more readonly indexes during the update operation.
+     *
+     * By default, readonly indexes are not updated during entity updates to prevent
+     * errors when required index attributes are missing. This method allows you to
+     * override that behavior and force specific indexes to be rebuilt.
+     *
+     * @example
+     * ```typescript
+     * // Force rebuild a single readonly index
+     * const result = await repo.update({ id: 'TREX-001' }, { status: 'ACTIVE' })
+     *   .forceIndexRebuild('gsi1')
+     *   .execute();
+     *
+     * // Force rebuild multiple readonly indexes
+     * const result = await repo.update({ id: 'TREX-001' }, { status: 'ACTIVE' })
+     *   .forceIndexRebuild(['gsi1', 'gsi2'])
+     *   .execute();
+     *
+     * // Chain with other update operations
+     * const result = await repo.update({ id: 'TREX-001' }, { status: 'ACTIVE' })
+     *   .set('lastUpdated', new Date().toISOString())
+     *   .forceIndexRebuild('gsi1')
+     *   .condition(op => op.eq('status', 'INACTIVE'))
+     *   .execute();
+     * ```
+     *
+     * @param indexes - A single index name or array of index names to force rebuild
+     * @returns The builder instance for method chaining
+     */
+    forceIndexRebuild(indexes: string | string[]): this;
+    /**
+     * Gets the list of indexes that should be force rebuilt.
+     * This is used internally by entity update logic.
+     *
+     * @returns Array of index names to force rebuild
+     */
+    getForceRebuildIndexes(): string[];
+    /**
+     * Apply entity-specific update data (timestamps and index updates)
+     * This is called automatically when needed
+     */
+    private applyEntityUpdates;
+    set(values: Partial<T>): this;
+    set<K extends Path<T>>(path: K, value: PathType<T, K>): this;
+    remove<K extends Path<T>>(path: K): this;
+    add<K extends Path<T>>(path: K, value: PathType<T, K>): this;
+    deleteElementsFromSet<K extends Path<T>>(path: K, value: PathSetElementType<T, K>[] | Set<PathSetElementType<T, K>>): this;
+    condition(condition: Condition | ((op: ConditionOperator<T>) => Condition)): this;
+    returnValues(returnValues: "ALL_NEW" | "UPDATED_NEW" | "ALL_OLD" | "UPDATED_OLD" | "NONE"): this;
+    toDynamoCommand(): UpdateCommandParams;
+    withTransaction(transaction: TransactionBuilder): void;
+    debug(): ReturnType<UpdateBuilder<T>['debug']>;
+    execute(): Promise<{
+        item?: T;
+    }>;
+}
 
-type QueryFunction<T extends DynamoItem, I, R> = (input: I) => R;
+type QueryFunction<_T extends DynamoItem, I, R> = (input: I) => R;
 type QueryFunctionWithSchema<T extends DynamoItem, I, R> = QueryFunction<T, I, R> & {
     schema?: StandardSchemaV1<I>;
 };
@@ -120,7 +201,7 @@ Q extends QueryRecord<T> = QueryRecord<T>> {
     create: (data: TInput) => EntityAwarePutBuilder<T>;
     upsert: (data: TInput & I) => EntityAwarePutBuilder<T>;
     get: (key: I) => EntityAwareGetBuilder<T>;
-    update: (key: I, data: Partial<T>) => UpdateBuilder<T>;
+    update: (key: I, data: Partial<T>) => EntityAwareUpdateBuilder<T>;
     delete: (key: I) => EntityAwareDeleteBuilder;
     query: Q;
     scan: () => ScanBuilder<T>;

package/dist/entity.js

@@ -25,6 +25,137 @@ function createEntityAwareGetBuilder(builder, entityName) {
 function createEntityAwareDeleteBuilder(builder, entityName) {
   return createEntityAwareBuilder(builder, entityName);
 }
+var EntityAwareUpdateBuilder = class {
+  forceRebuildIndexes = [];
+  entityName;
+  builder;
+  entityConfig;
+  updateDataApplied = false;
+  constructor(builder, entityName) {
+    this.builder = builder;
+    this.entityName = entityName;
+  }
+  /**
+   * Configure entity-specific logic for automatic timestamp generation and index updates
+   */
+  configureEntityLogic(config) {
+    this.entityConfig = config;
+  }
+  /**
+   * Forces a rebuild of one or more readonly indexes during the update operation.
+   *
+   * By default, readonly indexes are not updated during entity updates to prevent
+   * errors when required index attributes are missing. This method allows you to
+   * override that behavior and force specific indexes to be rebuilt.
+   *
+   * @example
+   * ```typescript
+   * // Force rebuild a single readonly index
+   * const result = await repo.update({ id: 'TREX-001' }, { status: 'ACTIVE' })
+   *   .forceIndexRebuild('gsi1')
+   *   .execute();
+   *
+   * // Force rebuild multiple readonly indexes
+   * const result = await repo.update({ id: 'TREX-001' }, { status: 'ACTIVE' })
+   *   .forceIndexRebuild(['gsi1', 'gsi2'])
+   *   .execute();
+   *
+   * // Chain with other update operations
+   * const result = await repo.update({ id: 'TREX-001' }, { status: 'ACTIVE' })
+   *   .set('lastUpdated', new Date().toISOString())
+   *   .forceIndexRebuild('gsi1')
+   *   .condition(op => op.eq('status', 'INACTIVE'))
+   *   .execute();
+   * ```
+   *
+   * @param indexes - A single index name or array of index names to force rebuild
+   * @returns The builder instance for method chaining
+   */
+  forceIndexRebuild(indexes) {
+    if (Array.isArray(indexes)) {
+      this.forceRebuildIndexes = [...this.forceRebuildIndexes, ...indexes];
+    } else {
+      this.forceRebuildIndexes.push(indexes);
+    }
+    return this;
+  }
+  /**
+   * Gets the list of indexes that should be force rebuilt.
+   * This is used internally by entity update logic.
+   *
+   * @returns Array of index names to force rebuild
+   */
+  getForceRebuildIndexes() {
+    return [...this.forceRebuildIndexes];
+  }
+  /**
+   * Apply entity-specific update data (timestamps and index updates)
+   * This is called automatically when needed
+   */
+  applyEntityUpdates() {
+    if (!this.entityConfig || this.updateDataApplied) return;
+    const timestamps = this.entityConfig.generateTimestamps();
+    const updatedItem = { ...this.entityConfig.key, ...this.entityConfig.data, ...timestamps };
+    const indexUpdates = this.entityConfig.buildIndexUpdates(
+      this.entityConfig.key,
+      updatedItem,
+      this.entityConfig.table,
+      this.entityConfig.indexes,
+      this.forceRebuildIndexes
+    );
+    this.builder.set({ ...this.entityConfig.data, ...timestamps, ...indexUpdates });
+    this.updateDataApplied = true;
+  }
+  set(valuesOrPath, value) {
+    if (typeof valuesOrPath === "object") {
+      this.builder.set(valuesOrPath);
+    } else {
+      if (value === void 0) {
+        throw new Error("Value is required when setting a single path");
+      }
+      this.builder.set(valuesOrPath, value);
+    }
+    return this;
+  }
+  remove(path) {
+    this.builder.remove(path);
+    return this;
+  }
+  add(path, value) {
+    this.builder.add(path, value);
+    return this;
+  }
+  deleteElementsFromSet(path, value) {
+    this.builder.deleteElementsFromSet(path, value);
+    return this;
+  }
+  condition(condition) {
+    this.builder.condition(condition);
+    return this;
+  }
+  returnValues(returnValues) {
+    this.builder.returnValues(returnValues);
+    return this;
+  }
+  toDynamoCommand() {
+    return this.builder.toDynamoCommand();
+  }
+  withTransaction(transaction) {
+    this.applyEntityUpdates();
+    this.builder.withTransaction(transaction);
+  }
+  debug() {
+    return this.builder.debug();
+  }
+  async execute() {
+    this.updateDataApplied = false;
+    this.applyEntityUpdates();
+    return this.builder.execute();
+  }
+};
+function createEntityAwareUpdateBuilder(builder, entityName) {
+  return new EntityAwareUpdateBuilder(builder, entityName);
+}
 
 // src/conditions.ts
 var createComparisonCondition = (type) => (attr, value) => ({
@@ -81,51 +212,61 @@ var IndexBuilder = class {
    * @param options - Options for building indexes
    * @returns Record of GSI attribute names to their updated values
    */
-  buildForUpdate(currentData, updates) {
+  buildForUpdate(currentData, updates, options = {}) {
     const attributes = {};
     const updatedItem = { ...currentData, ...updates };
+    if (options.forceRebuildIndexes && options.forceRebuildIndexes.length > 0) {
+      const invalidIndexes = options.forceRebuildIndexes.filter((indexName) => !this.indexes[indexName]);
+      if (invalidIndexes.length > 0) {
+        throw new Error(
+          `Cannot force rebuild unknown indexes: ${invalidIndexes.join(", ")}. Available indexes: ${Object.keys(this.indexes).join(", ")}`
+        );
+      }
+    }
     for (const [indexName, indexDef] of Object.entries(this.indexes)) {
-      if (indexDef.isReadOnly) {
+      const isForced = options.forceRebuildIndexes?.includes(indexName);
+      if (indexDef.isReadOnly && !isForced) {
         continue;
       }
-      let shouldUpdateIndex = false;
-      try {
-        const currentKey = indexDef.generateKey(currentData);
-        const updatedKey = indexDef.generateKey(updatedItem);
-        if (currentKey.pk !== updatedKey.pk || currentKey.sk !== updatedKey.sk) {
+      if (!isForced) {
+        let shouldUpdateIndex = false;
+        try {
+          const currentKey = indexDef.generateKey(currentData);
+          const updatedKey = indexDef.generateKey(updatedItem);
+          if (currentKey.pk !== updatedKey.pk || currentKey.sk !== updatedKey.sk) {
+            shouldUpdateIndex = true;
+          }
+        } catch {
           shouldUpdateIndex = true;
         }
-      } catch {
-        shouldUpdateIndex = true;
-      }
-      if (!shouldUpdateIndex) {
-        continue;
+        if (!shouldUpdateIndex) {
+          continue;
+        }
       }
+      let key;
       try {
-        const key = indexDef.generateKey(updatedItem);
-        if (this.hasUndefinedValues(key)) {
-          throw new Error(
-            `Cannot update entity: insufficient data to regenerate index "${indexName}". All attributes required by the index must be provided in the update operation, or the index must be marked as readOnly.`
-          );
-        }
-        const gsiConfig = this.table.gsis[indexName];
-        if (!gsiConfig) {
-          throw new Error(`GSI configuration not found for index: ${indexName}`);
-        }
-        if (key.pk) {
-          attributes[gsiConfig.partitionKey] = key.pk;
-        }
-        if (key.sk && gsiConfig.sortKey) {
-          attributes[gsiConfig.sortKey] = key.sk;
-        }
+        key = indexDef.generateKey(updatedItem);
       } catch (error) {
-        if (error instanceof Error && error.message.includes("insufficient data")) {
-          throw error;
+        if (error instanceof Error) {
+          throw new Error(`Missing attributes: ${error.message}`);
         }
+        throw error;
+      }
+      if (this.hasUndefinedValues(key)) {
         throw new Error(
-          `Cannot update entity: insufficient data to regenerate index "${indexName}". All attributes required by the index must be provided in the update operation, or the index must be readOnly.`
+          `Missing attributes: Cannot update entity: insufficient data to regenerate index "${indexName}". All attributes required by the index must be provided in the update operation, or the index must be marked as readOnly.`
         );
       }
+      const gsiConfig = this.table.gsis[indexName];
+      if (!gsiConfig) {
+        throw new Error(`GSI configuration not found for index: ${indexName}`);
+      }
+      if (key.pk) {
+        attributes[gsiConfig.partitionKey] = key.pk;
+      }
+      if (key.sk && gsiConfig.sortKey) {
+        attributes[gsiConfig.sortKey] = key.sk;
+      }
     }
     return attributes;
   }
@@ -148,12 +289,12 @@ function buildIndexes(dataForKeyGeneration, table, indexes, excludeReadOnly = fa
   const indexBuilder = new IndexBuilder(table, indexes);
   return indexBuilder.buildForCreate(dataForKeyGeneration, { excludeReadOnly });
 }
-function buildIndexUpdates(currentData, updates, table, indexes) {
+function buildIndexUpdates(currentData, updates, table, indexes, forceRebuildIndexes) {
   if (!indexes) {
     return {};
   }
   const indexBuilder = new IndexBuilder(table, indexes);
-  return indexBuilder.buildForUpdate(currentData, updates);
+  return indexBuilder.buildForUpdate(currentData, updates, { forceRebuildIndexes });
 }
 
 // src/entity/entity.ts
@@ -347,15 +488,16 @@ function defineEntity(config) {
           const primaryKeyObj = config.primaryKey.generateKey(key);
           const builder = table.update(primaryKeyObj);
           builder.condition(eq(entityTypeAttributeName, config.name));
-          const timestamps = generateTimestamps(["updatedAt"], data);
-          const indexUpdates = buildIndexUpdates(
-            { ...key },
-            { ...data, ...timestamps },
+          const entityAwareBuilder = createEntityAwareUpdateBuilder(builder, config.name);
+          entityAwareBuilder.configureEntityLogic({
+            data,
+            key,
             table,
-            config.indexes
-          );
-          builder.set({ ...data, ...timestamps, ...indexUpdates });
-          return builder;
+            indexes: config.indexes,
+            generateTimestamps: () => generateTimestamps(["updatedAt"], data),
+            buildIndexUpdates
+          });
+          return entityAwareBuilder;
         },
         delete: (key) => {
           const builder = table.delete(config.primaryKey.generateKey(key));