dyno-table 2.5.2 → 2.6.1

package/dist/entity.js

@@ -1,3 +1,1127 @@
-export { createIndex, createQueries, defineEntity } from './chunk-RNX2DAHA.js';
-import './chunk-FF7FYGDH.js';
-import './chunk-2WIBY7PZ.js';
+// src/builders/entity-aware-builders.ts
+function createEntityAwareBuilder(builder, entityName) {
+  return new Proxy(builder, {
+    get(target, prop, receiver) {
+      if (prop === "entityName") {
+        return entityName;
+      }
+      if (prop === "withBatch" && typeof target[prop] === "function") {
+        return (batch, entityType) => {
+          const typeToUse = entityType ?? entityName;
+          const fn = target[prop];
+          return fn.call(target, batch, typeToUse);
+        };
+      }
+      return Reflect.get(target, prop, receiver);
+    }
+  });
+}
+function createEntityAwarePutBuilder(builder, entityName) {
+  return createEntityAwareBuilder(builder, entityName);
+}
+function createEntityAwareGetBuilder(builder, entityName) {
+  return createEntityAwareBuilder(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 {
+      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) => ({
+  type,
+  attr,
+  value
+});
+var eq = createComparisonCondition("eq");
+
+// src/errors.ts
+var DynoTableError = class extends Error {
+  /**
+   * Machine-readable error code for programmatic error handling
+   * @example "KEY_GENERATION_FAILED", "VALIDATION_ERROR", etc.
+   */
+  code;
+  /**
+   * Additional context about the error
+   * Contains operation-specific details like entity names, table names,
+   * expressions, conditions, and other relevant debugging information
+   */
+  context;
+  /**
+   * The original error that caused this error (if wrapping another error)
+   * Useful for preserving AWS SDK errors or other underlying errors
+   */
+  cause;
+  constructor(message, code, context = {}, cause) {
+    super(message);
+    this.name = "DynoTableError";
+    this.code = code;
+    this.context = context;
+    this.cause = cause;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+};
+var ValidationError = class extends DynoTableError {
+  constructor(message, code, context = {}, cause) {
+    super(message, code, context, cause);
+    this.name = "ValidationError";
+  }
+};
+var OperationError = class extends DynoTableError {
+  constructor(message, code, context = {}, cause) {
+    super(message, code, context, cause);
+    this.name = "OperationError";
+  }
+};
+var ExpressionError = class extends DynoTableError {
+  constructor(message, code, context = {}, cause) {
+    super(message, code, context, cause);
+    this.name = "ExpressionError";
+  }
+};
+var ConfigurationError = class extends DynoTableError {
+  constructor(message, code, context = {}, cause) {
+    super(message, code, context, cause);
+    this.name = "ConfigurationError";
+  }
+};
+var EntityError = class extends DynoTableError {
+  constructor(message, code, context = {}, cause) {
+    super(message, code, context, cause);
+    this.name = "EntityError";
+  }
+};
+var KeyGenerationError = class extends EntityError {
+  constructor(message, code, context = {}, cause) {
+    super(message, code, context, cause);
+    this.name = "KeyGenerationError";
+  }
+};
+var IndexGenerationError = class extends EntityError {
+  constructor(message, code, context = {}, cause) {
+    super(message, code, context, cause);
+    this.name = "IndexGenerationError";
+  }
+};
+var EntityValidationError = class extends ValidationError {
+  constructor(message, code, context = {}, cause) {
+    super(message, code, context, cause);
+    this.name = "EntityValidationError";
+  }
+};
+var ErrorCodes = {
+  // Key Generation Errors
+  KEY_GENERATION_FAILED: "KEY_GENERATION_FAILED",
+  KEY_MISSING_ATTRIBUTES: "KEY_MISSING_ATTRIBUTES",
+  KEY_INVALID_FORMAT: "KEY_INVALID_FORMAT",
+  // Index Errors
+  INDEX_GENERATION_FAILED: "INDEX_GENERATION_FAILED",
+  INDEX_MISSING_ATTRIBUTES: "INDEX_MISSING_ATTRIBUTES",
+  INDEX_NOT_FOUND: "INDEX_NOT_FOUND",
+  INDEX_READONLY_UPDATE_FAILED: "INDEX_READONLY_UPDATE_FAILED",
+  INDEX_UNDEFINED_VALUES: "INDEX_UNDEFINED_VALUES",
+  // Validation Errors
+  ENTITY_VALIDATION_FAILED: "ENTITY_VALIDATION_FAILED",
+  ASYNC_VALIDATION_NOT_SUPPORTED: "ASYNC_VALIDATION_NOT_SUPPORTED",
+  QUERY_INPUT_VALIDATION_FAILED: "QUERY_INPUT_VALIDATION_FAILED",
+  SCHEMA_VALIDATION_FAILED: "SCHEMA_VALIDATION_FAILED",
+  UNDEFINED_VALUE: "UNDEFINED_VALUE",
+  // Operation Errors
+  QUERY_FAILED: "QUERY_FAILED",
+  SCAN_FAILED: "SCAN_FAILED",
+  GET_FAILED: "GET_FAILED",
+  PUT_FAILED: "PUT_FAILED",
+  DELETE_FAILED: "DELETE_FAILED",
+  UPDATE_FAILED: "UPDATE_FAILED",
+  BATCH_GET_FAILED: "BATCH_GET_FAILED",
+  BATCH_WRITE_FAILED: "BATCH_WRITE_FAILED",
+  NO_UPDATE_ACTIONS: "NO_UPDATE_ACTIONS",
+  // Configuration Errors
+  GSI_NOT_FOUND: "GSI_NOT_FOUND",
+  SORT_KEY_REQUIRED: "SORT_KEY_REQUIRED",
+  SORT_KEY_NOT_DEFINED: "SORT_KEY_NOT_DEFINED",
+  PRIMARY_KEY_MISSING: "PRIMARY_KEY_MISSING",
+  INVALID_CHUNK_SIZE: "INVALID_CHUNK_SIZE",
+  CONDITION_REQUIRED: "CONDITION_REQUIRED",
+  CONDITION_GENERATION_FAILED: "CONDITION_GENERATION_FAILED",
+  PK_EXTRACTION_FAILED: "PK_EXTRACTION_FAILED"};
+
+// src/utils/error-factory.ts
+var ValidationErrors = {
+  indexSchemaValidationFailed: (validationIssues, keyType) => {
+    const keyLabel = keyType === "partition" ? "partition key" : keyType === "sort" ? "sort key" : "partition/sort key";
+    return new ValidationError(
+      `Index validation failed while generating ${keyLabel}: missing required attribute(s) or invalid values.`,
+      ErrorCodes.SCHEMA_VALIDATION_FAILED,
+      {
+        keyType,
+        validationIssues,
+        suggestion: `Provide the required attributes to construct the index ${keyLabel}`
+      }
+    );
+  },
+  noUpdateActions: (tableName, key) => new ValidationError("No update actions specified", ErrorCodes.NO_UPDATE_ACTIONS, {
+    tableName,
+    key,
+    suggestion: "Use set(), remove(), add(), or delete() to specify update actions"
+  }),
+  conditionRequired: (tableName, key) => new ValidationError("Condition is required for condition check operations", ErrorCodes.CONDITION_REQUIRED, {
+    tableName,
+    key,
+    suggestion: "Use the condition() method to specify a condition"
+  }),
+  queryInputValidationFailed: (entityName, queryName, validationIssues, providedInput) => new ValidationError(
+    `Query input validation failed for "${queryName}" on entity "${entityName}"`,
+    ErrorCodes.QUERY_INPUT_VALIDATION_FAILED,
+    {
+      entityName,
+      queryName,
+      validationIssues,
+      providedInput,
+      suggestion: "Ensure the query input matches the expected schema"
+    }
+  ),
+  undefinedValue: (path, tableName, key) => new ValidationError(`Cannot set undefined value for attribute "${path}"`, ErrorCodes.UNDEFINED_VALUE, {
+    path,
+    tableName,
+    key,
+    suggestion: "DynamoDB does not support undefined values. Use remove() to delete an attribute, or provide a valid value (null, string, number, etc.)"
+  })
+};
+var ConfigurationErrors = {
+  invalidChunkSize: (size) => new ConfigurationError("Chunk size must be greater than 0", ErrorCodes.INVALID_CHUNK_SIZE, {
+    size,
+    suggestion: "Provide a chunk size greater than 0"
+  }),
+  sortKeyRequired: (tableName, partitionKey, sortKey) => new ConfigurationError("Sort key is required for this operation", ErrorCodes.SORT_KEY_REQUIRED, {
+    tableName,
+    partitionKey,
+    sortKey,
+    suggestion: "Provide a sort key value or use a table with only a partition key"
+  }),
+  sortKeyNotDefined: (tableName, partitionKey, indexName) => new ConfigurationError("Sort key is not defined for this table/index", ErrorCodes.SORT_KEY_NOT_DEFINED, {
+    tableName,
+    partitionKey,
+    indexName,
+    suggestion: "This operation requires a table/index with a sort key defined"
+  }),
+  gsiNotFound: (indexName, tableName, availableIndexes) => new ConfigurationError(`GSI "${indexName}" not found in table configuration`, ErrorCodes.GSI_NOT_FOUND, {
+    indexName,
+    tableName,
+    availableIndexes,
+    suggestion: `Use one of the available indexes: ${availableIndexes.join(", ")}`
+  }),
+  primaryKeyMissing: (tableName, partitionKeyName, providedItem) => new ConfigurationError(`Primary key value for '${partitionKeyName}' is missing`, ErrorCodes.PRIMARY_KEY_MISSING, {
+    tableName,
+    partitionKeyName,
+    providedItem,
+    suggestion: `Ensure the item includes a value for '${partitionKeyName}'`
+  }),
+  pkExtractionFailed: (tableName, indexName, item, cause) => new ConfigurationError(
+    `Failed to extract partition key from item for index "${indexName}"`,
+    ErrorCodes.PK_EXTRACTION_FAILED,
+    {
+      tableName,
+      indexName,
+      item,
+      suggestion: "Ensure the item has the required partition key attribute"
+    },
+    cause
+  ),
+  conditionGenerationFailed: (condition, suggestion) => new ExpressionError("Failed to generate condition expression", ErrorCodes.CONDITION_GENERATION_FAILED, {
+    condition,
+    suggestion: suggestion || "Check that the condition is properly formed"
+  })
+};
+var OperationErrors = {
+  queryFailed: (tableName, context, cause) => new OperationError(
+    `Query operation failed on table "${tableName}"`,
+    ErrorCodes.QUERY_FAILED,
+    {
+      tableName,
+      operation: "query",
+      ...context
+    },
+    cause
+  ),
+  scanFailed: (tableName, context, cause) => new OperationError(
+    `Scan operation failed on table "${tableName}"`,
+    ErrorCodes.SCAN_FAILED,
+    {
+      tableName,
+      operation: "scan",
+      ...context
+    },
+    cause
+  ),
+  getFailed: (tableName, key, cause) => new OperationError(
+    `Get operation failed on table "${tableName}"`,
+    ErrorCodes.GET_FAILED,
+    {
+      tableName,
+      operation: "get",
+      key
+    },
+    cause
+  ),
+  putFailed: (tableName, item, cause) => new OperationError(
+    `Put operation failed on table "${tableName}"`,
+    ErrorCodes.PUT_FAILED,
+    {
+      tableName,
+      operation: "put",
+      item
+    },
+    cause
+  ),
+  updateFailed: (tableName, key, cause) => new OperationError(
+    `Update operation failed on table "${tableName}"`,
+    ErrorCodes.UPDATE_FAILED,
+    {
+      tableName,
+      operation: "update",
+      key
+    },
+    cause
+  ),
+  deleteFailed: (tableName, key, cause) => new OperationError(
+    `Delete operation failed on table "${tableName}"`,
+    ErrorCodes.DELETE_FAILED,
+    {
+      tableName,
+      operation: "delete",
+      key
+    },
+    cause
+  ),
+  batchGetFailed: (tableName, context, cause) => new OperationError(
+    `Batch get operation failed on table "${tableName}"`,
+    ErrorCodes.BATCH_GET_FAILED,
+    {
+      tableName,
+      operation: "batchGet",
+      ...context
+    },
+    cause
+  ),
+  batchWriteFailed: (tableName, context, cause) => new OperationError(
+    `Batch write operation failed on table "${tableName}"`,
+    ErrorCodes.BATCH_WRITE_FAILED,
+    {
+      tableName,
+      operation: "batchWrite",
+      ...context
+    },
+    cause
+  )
+};
+var EntityErrors = {
+  validationFailed: (entityName, operation, validationIssues, providedData) => new EntityValidationError(
+    `Validation failed for entity "${entityName}" during ${operation} operation`,
+    ErrorCodes.ENTITY_VALIDATION_FAILED,
+    {
+      entityName,
+      operation,
+      validationIssues,
+      providedData,
+      suggestion: "Check that all required fields are provided and match the schema"
+    }
+  ),
+  queryInputValidationFailed: (entityName, queryName, validationIssues, providedInput) => new EntityValidationError(
+    `Query input validation failed for "${queryName}" on entity "${entityName}"`,
+    ErrorCodes.QUERY_INPUT_VALIDATION_FAILED,
+    {
+      entityName,
+      queryName,
+      validationIssues,
+      providedInput,
+      suggestion: "Ensure the query input matches the expected schema"
+    }
+  ),
+  asyncValidationNotSupported: (entityName, operation) => new EntityValidationError(
+    `Entity "${entityName}" uses async validation which is not supported in transactions/batches`,
+    ErrorCodes.ASYNC_VALIDATION_NOT_SUPPORTED,
+    {
+      entityName,
+      operation,
+      suggestion: "Use .execute() for async validation or switch to synchronous schema validation"
+    }
+  ),
+  keyGenerationFailed: (entityName, operation, providedData, requiredAttributes, cause) => new KeyGenerationError(
+    `Failed to generate primary key for entity "${entityName}"`,
+    ErrorCodes.KEY_GENERATION_FAILED,
+    {
+      entityName,
+      operation,
+      providedData,
+      requiredAttributes,
+      suggestion: requiredAttributes ? `Ensure these attributes are provided: ${requiredAttributes.join(", ")}` : "Check that all required attributes for key generation are provided"
+    },
+    cause
+  ),
+  keyInvalidFormat: (entityName, operation, providedData, generatedKey) => new KeyGenerationError(
+    `Primary key generation for entity "${entityName}" produced undefined/null partition key`,
+    ErrorCodes.KEY_INVALID_FORMAT,
+    {
+      entityName,
+      operation,
+      providedData,
+      generatedKey,
+      suggestion: "Ensure the key generation function returns valid pk (and sk if applicable) values"
+    }
+  ),
+  keyMissingAttributes: (entityName, operation, missingAttributes, providedData) => new KeyGenerationError(
+    `Missing required attributes for key generation in entity "${entityName}": ${missingAttributes.join(", ")}`,
+    ErrorCodes.KEY_MISSING_ATTRIBUTES,
+    {
+      entityName,
+      operation,
+      missingAttributes,
+      providedData,
+      suggestion: `Provide the following attributes: ${missingAttributes.join(", ")}`
+    }
+  )
+};
+var IndexErrors = {
+  generationFailed: (indexName, operation, providedItem, partitionKeyAttribute, sortKeyAttribute, cause) => new IndexGenerationError(
+    `Failed to generate key for index "${indexName}"`,
+    ErrorCodes.INDEX_GENERATION_FAILED,
+    {
+      indexName,
+      operation,
+      providedItem,
+      partitionKeyAttribute,
+      sortKeyAttribute,
+      suggestion: "Ensure all attributes required by the index are present in the item"
+    },
+    cause
+  ),
+  missingAttributes: (indexName, operation, missingAttributes, providedData, isReadOnly) => new IndexGenerationError(
+    `Cannot regenerate readonly index "${indexName}" - missing required attributes: ${missingAttributes.join(", ")}`,
+    ErrorCodes.INDEX_MISSING_ATTRIBUTES,
+    {
+      indexName,
+      operation,
+      missingAttributes,
+      providedData,
+      isReadOnly,
+      suggestion: isReadOnly ? "For readonly indexes, provide all attributes or use forceIndexRebuild() with complete data" : `Provide the following attributes: ${missingAttributes.join(", ")}`
+    }
+  ),
+  undefinedValues: (indexName, operation, generatedKey, providedItem) => new IndexGenerationError(`Index "${indexName}" generated undefined values`, ErrorCodes.INDEX_UNDEFINED_VALUES, {
+    indexName,
+    operation,
+    generatedKey,
+    providedItem,
+    suggestion: "Ensure all attributes required by the index are present in the item"
+  }),
+  notFound: (requestedIndexes, availableIndexes, entityName, tableName) => new IndexGenerationError(
+    `Requested indexes not found: ${requestedIndexes.join(", ")}`,
+    ErrorCodes.INDEX_NOT_FOUND,
+    {
+      requestedIndexes,
+      availableIndexes,
+      entityName,
+      tableName,
+      suggestion: `Available indexes are: ${availableIndexes.join(", ")}`
+    }
+  ),
+  readonlyUpdateFailed: (indexName, operation, providedData) => new IndexGenerationError(
+    `Cannot update readonly index "${indexName}" without forcing rebuild`,
+    ErrorCodes.INDEX_READONLY_UPDATE_FAILED,
+    {
+      indexName,
+      operation,
+      providedData,
+      isReadOnly: true,
+      suggestion: "Use forceIndexRebuild() to update readonly indexes, or provide all required attributes"
+    }
+  )
+};
+
+// src/utils/error-utils.ts
+function getAwsErrorMessage(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (typeof error === "object" && error !== null && "message" in error) {
+    return String(error.message);
+  }
+  return void 0;
+}
+function extractRequiredAttributes(error) {
+  const message = getAwsErrorMessage(error);
+  if (!message) return void 0;
+  const patterns = [
+    /(?:missing|required)\s+(?:attribute|field|property)(?:s)?[:\s]+([a-zA-Z0-9_,\s]+)/i,
+    /(?:attribute|field|property)[:\s]+([a-zA-Z0-9_]+)\s+is\s+(?:missing|required)/i,
+    /"([a-zA-Z0-9_]+)"\s+is\s+(?:missing|required)/i
+  ];
+  for (const pattern of patterns) {
+    const match = message.match(pattern);
+    if (match?.[1]) {
+      return match[1].split(",").map((attr) => attr.trim()).filter((attr) => attr.length > 0);
+    }
+  }
+  return void 0;
+}
+
+// src/entity/ddb-indexing.ts
+var IndexBuilder = class {
+  /**
+   * Creates a new IndexBuilder instance
+   *
+   * @param table - The DynamoDB table instance
+   * @param indexes - The index definitions
+   */
+  constructor(table, indexes = {}) {
+    this.table = table;
+    this.indexes = indexes;
+  }
+  /**
+   * Build index attributes for item creation
+   *
+   * @param item - The item to generate indexes for
+   * @param options - Options for building indexes
+   * @returns Record of GSI attribute names to their values
+   */
+  buildForCreate(item, options = {}) {
+    const attributes = {};
+    for (const [indexName, indexDef] of Object.entries(this.indexes)) {
+      if (options.excludeReadOnly && indexDef.isReadOnly) {
+        continue;
+      }
+      let key;
+      try {
+        key = indexDef.generateKey(item);
+        if (this.hasUndefinedValues(key)) {
+          throw IndexErrors.undefinedValues(indexName, "create", key, item);
+        }
+      } catch (error) {
+        if (error instanceof DynoTableError) throw error;
+        throw IndexErrors.generationFailed(
+          indexName,
+          "create",
+          item,
+          indexDef.partitionKey,
+          indexDef.sortKey,
+          error instanceof Error ? error : void 0
+        );
+      }
+      const gsiConfig = this.table.gsis[indexName];
+      if (!gsiConfig) {
+        throw ConfigurationErrors.gsiNotFound(indexName, this.table.tableName, Object.keys(this.table.gsis));
+      }
+      if (key.pk) {
+        attributes[gsiConfig.partitionKey] = key.pk;
+      }
+      if (key.sk && gsiConfig.sortKey) {
+        attributes[gsiConfig.sortKey] = key.sk;
+      }
+    }
+    return attributes;
+  }
+  /**
+   * Build index attributes for item updates
+   *
+   * @param currentData - The current data before update
+   * @param updates - The update data
+   * @param options - Options for building indexes
+   * @returns Record of GSI attribute names to their updated values
+   */
+  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 IndexErrors.notFound(invalidIndexes, Object.keys(this.indexes), void 0, this.table.tableName);
+      }
+    }
+    for (const [indexName, indexDef] of Object.entries(this.indexes)) {
+      const isForced = options.forceRebuildIndexes?.includes(indexName);
+      if (indexDef.isReadOnly && !isForced) {
+        continue;
+      }
+      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;
+        }
+        if (!shouldUpdateIndex) {
+          continue;
+        }
+      }
+      let key;
+      try {
+        key = indexDef.generateKey(updatedItem);
+      } catch (error) {
+        if (error instanceof DynoTableError) throw error;
+        throw IndexErrors.missingAttributes(
+          indexName,
+          "update",
+          [],
+          // We don't know which specific attributes are missing from the error
+          updates,
+          indexDef.isReadOnly
+        );
+      }
+      if (this.hasUndefinedValues(key)) {
+        throw IndexErrors.undefinedValues(indexName, "update", key, updates);
+      }
+      const gsiConfig = this.table.gsis[indexName];
+      if (!gsiConfig) {
+        throw ConfigurationErrors.gsiNotFound(indexName, this.table.tableName, Object.keys(this.table.gsis));
+      }
+      if (key.pk) {
+        attributes[gsiConfig.partitionKey] = key.pk;
+      }
+      if (key.sk && gsiConfig.sortKey) {
+        attributes[gsiConfig.sortKey] = key.sk;
+      }
+    }
+    return attributes;
+  }
+  /**
+   * Check if a key has undefined values
+   *
+   * @param key - The index key to check
+   * @returns True if the key contains undefined values, false otherwise
+   */
+  hasUndefinedValues(key) {
+    return (key.pk?.includes("undefined") ?? false) || (key.sk?.includes("undefined") ?? false);
+  }
+};
+
+// src/entity/index-utils.ts
+function buildIndexes(dataForKeyGeneration, table, indexes, excludeReadOnly = false) {
+  if (!indexes) {
+    return {};
+  }
+  const indexBuilder = new IndexBuilder(table, indexes);
+  return indexBuilder.buildForCreate(dataForKeyGeneration, { excludeReadOnly });
+}
+function buildIndexUpdates(currentData, updates, table, indexes, forceRebuildIndexes) {
+  if (!indexes) {
+    return {};
+  }
+  const indexBuilder = new IndexBuilder(table, indexes);
+  return indexBuilder.buildForUpdate(currentData, updates, { forceRebuildIndexes });
+}
+
+// src/entity/entity.ts
+function defineEntity(config) {
+  const entityTypeAttributeName = config.settings?.entityTypeAttributeName ?? "entityType";
+  const buildIndexes2 = (dataForKeyGeneration, table, excludeReadOnly = false) => {
+    return buildIndexes(dataForKeyGeneration, table, config.indexes, excludeReadOnly);
+  };
+  const wrapMethodWithPreparation = (originalMethod, prepareFn, context) => {
+    const wrappedMethod = (...args) => {
+      prepareFn();
+      return originalMethod.call(context, ...args);
+    };
+    Object.setPrototypeOf(wrappedMethod, originalMethod);
+    const propertyNames = Object.getOwnPropertyNames(originalMethod);
+    for (let i = 0; i < propertyNames.length; i++) {
+      const prop = propertyNames[i];
+      if (prop !== "length" && prop !== "name" && prop !== "prototype") {
+        const descriptor = Object.getOwnPropertyDescriptor(originalMethod, prop);
+        if (descriptor && descriptor.writable !== false && !descriptor.get) {
+          wrappedMethod[prop] = originalMethod[prop];
+        }
+      }
+    }
+    return wrappedMethod;
+  };
+  const generateTimestamps = (timestampsToGenerate, data) => {
+    if (!config.settings?.timestamps) return {};
+    const timestamps = {};
+    const now = /* @__PURE__ */ new Date();
+    const unixTime = Math.floor(Date.now() / 1e3);
+    const { createdAt, updatedAt } = config.settings.timestamps;
+    if (createdAt && timestampsToGenerate.includes("createdAt") && !data.createdAt) {
+      const name = createdAt.attributeName ?? "createdAt";
+      timestamps[name] = createdAt.format === "UNIX" ? unixTime : now.toISOString();
+    }
+    if (updatedAt && timestampsToGenerate.includes("updatedAt") && !data.updatedAt) {
+      const name = updatedAt.attributeName ?? "updatedAt";
+      timestamps[name] = updatedAt.format === "UNIX" ? unixTime : now.toISOString();
+    }
+    return timestamps;
+  };
+  return {
+    name: config.name,
+    createRepository: (table) => {
+      const repository = {
+        create: (data) => {
+          const builder = table.create({});
+          const prepareValidatedItemAsync = async () => {
+            const validatedData = await config.schema["~standard"].validate(data);
+            if ("issues" in validatedData && validatedData.issues) {
+              throw EntityErrors.validationFailed(config.name, "create", validatedData.issues, data);
+            }
+            const dataForKeyGeneration = {
+              ...validatedData.value,
+              ...generateTimestamps(["createdAt", "updatedAt"], validatedData.value)
+            };
+            let primaryKey;
+            try {
+              primaryKey = config.primaryKey.generateKey(dataForKeyGeneration);
+              if (primaryKey.pk === void 0 || primaryKey.pk === null) {
+                throw EntityErrors.keyInvalidFormat(config.name, "create", dataForKeyGeneration, primaryKey);
+              }
+            } catch (error) {
+              if (error instanceof DynoTableError) throw error;
+              throw EntityErrors.keyGenerationFailed(
+                config.name,
+                "create",
+                dataForKeyGeneration,
+                extractRequiredAttributes(error),
+                error instanceof Error ? error : void 0
+              );
+            }
+            const indexes = buildIndexes(dataForKeyGeneration, table, config.indexes, false);
+            const validatedItem = {
+              ...dataForKeyGeneration,
+              [entityTypeAttributeName]: config.name,
+              [table.partitionKey]: primaryKey.pk,
+              ...table.sortKey ? { [table.sortKey]: primaryKey.sk } : {},
+              ...indexes
+            };
+            Object.assign(builder, { item: validatedItem });
+            return validatedItem;
+          };
+          const prepareValidatedItemSync = () => {
+            const validationResult = config.schema["~standard"].validate(data);
+            if (validationResult instanceof Promise) {
+              throw EntityErrors.asyncValidationNotSupported(config.name, "create");
+            }
+            if ("issues" in validationResult && validationResult.issues) {
+              throw EntityErrors.validationFailed(config.name, "create", validationResult.issues, data);
+            }
+            const dataForKeyGeneration = {
+              ...validationResult.value,
+              ...generateTimestamps(["createdAt", "updatedAt"], validationResult.value)
+            };
+            let primaryKey;
+            try {
+              primaryKey = config.primaryKey.generateKey(dataForKeyGeneration);
+              if (primaryKey.pk === void 0 || primaryKey.pk === null) {
+                throw EntityErrors.keyInvalidFormat(config.name, "create", dataForKeyGeneration, primaryKey);
+              }
+            } catch (error) {
+              if (error instanceof DynoTableError) throw error;
+              throw EntityErrors.keyGenerationFailed(
+                config.name,
+                "create",
+                dataForKeyGeneration,
+                extractRequiredAttributes(error),
+                error instanceof Error ? error : void 0
+              );
+            }
+            const indexes = buildIndexes(dataForKeyGeneration, table, config.indexes, false);
+            const validatedItem = {
+              ...dataForKeyGeneration,
+              [entityTypeAttributeName]: config.name,
+              [table.partitionKey]: primaryKey.pk,
+              ...table.sortKey ? { [table.sortKey]: primaryKey.sk } : {},
+              ...indexes
+            };
+            Object.assign(builder, { item: validatedItem });
+            return validatedItem;
+          };
+          const originalExecute = builder.execute;
+          builder.execute = async () => {
+            await prepareValidatedItemAsync();
+            return await originalExecute.call(builder);
+          };
+          const originalWithTransaction = builder.withTransaction;
+          if (originalWithTransaction) {
+            builder.withTransaction = wrapMethodWithPreparation(
+              originalWithTransaction,
+              prepareValidatedItemSync,
+              builder
+            );
+          }
+          const originalWithBatch = builder.withBatch;
+          if (originalWithBatch) {
+            builder.withBatch = wrapMethodWithPreparation(originalWithBatch, prepareValidatedItemSync, builder);
+          }
+          return createEntityAwarePutBuilder(builder, config.name);
+        },
+        upsert: (data) => {
+          const builder = table.put({});
+          const prepareValidatedItemAsync = async () => {
+            const validatedData = await config.schema["~standard"].validate(data);
+            if ("issues" in validatedData && validatedData.issues) {
+              throw EntityErrors.validationFailed(config.name, "upsert", validatedData.issues, data);
+            }
+            const dataForKeyGeneration = {
+              ...validatedData.value,
+              ...generateTimestamps(["createdAt", "updatedAt"], validatedData.value)
+            };
+            let primaryKey;
+            try {
+              primaryKey = config.primaryKey.generateKey(dataForKeyGeneration);
+              if (primaryKey.pk === void 0 || primaryKey.pk === null) {
+                throw EntityErrors.keyInvalidFormat(config.name, "upsert", dataForKeyGeneration, primaryKey);
+              }
+            } catch (error) {
+              if (error instanceof DynoTableError) throw error;
+              throw EntityErrors.keyGenerationFailed(
+                config.name,
+                "upsert",
+                dataForKeyGeneration,
+                extractRequiredAttributes(error),
+                error instanceof Error ? error : void 0
+              );
+            }
+            const indexes = buildIndexes2(dataForKeyGeneration, table, false);
+            const validatedItem = {
+              [table.partitionKey]: primaryKey.pk,
+              ...table.sortKey ? { [table.sortKey]: primaryKey.sk } : {},
+              ...dataForKeyGeneration,
+              [entityTypeAttributeName]: config.name,
+              ...indexes
+            };
+            Object.assign(builder, { item: validatedItem });
+            return validatedItem;
+          };
+          const prepareValidatedItemSync = () => {
+            const validationResult = config.schema["~standard"].validate(data);
+            if (validationResult instanceof Promise) {
+              throw EntityErrors.asyncValidationNotSupported(config.name, "upsert");
+            }
+            if ("issues" in validationResult && validationResult.issues) {
+              throw EntityErrors.validationFailed(config.name, "upsert", validationResult.issues, data);
+            }
+            const dataForKeyGeneration = {
+              ...validationResult.value,
+              ...generateTimestamps(["createdAt", "updatedAt"], validationResult.value)
+            };
+            let primaryKey;
+            try {
+              primaryKey = config.primaryKey.generateKey(dataForKeyGeneration);
+              if (primaryKey.pk === void 0 || primaryKey.pk === null) {
+                throw EntityErrors.keyInvalidFormat(config.name, "upsert", dataForKeyGeneration, primaryKey);
+              }
+            } catch (error) {
+              if (error instanceof DynoTableError) throw error;
+              throw EntityErrors.keyGenerationFailed(
+                config.name,
+                "upsert",
+                dataForKeyGeneration,
+                extractRequiredAttributes(error),
+                error instanceof Error ? error : void 0
+              );
+            }
+            const indexes = buildIndexes(dataForKeyGeneration, table, config.indexes, false);
+            const validatedItem = {
+              [table.partitionKey]: primaryKey.pk,
+              ...table.sortKey ? { [table.sortKey]: primaryKey.sk } : {},
+              ...dataForKeyGeneration,
+              [entityTypeAttributeName]: config.name,
+              ...indexes
+            };
+            Object.assign(builder, { item: validatedItem });
+            return validatedItem;
+          };
+          const originalExecute = builder.execute;
+          builder.execute = async () => {
+            const validatedItem = await prepareValidatedItemAsync();
+            await originalExecute.call(builder);
+            return validatedItem;
+          };
+          const originalWithTransaction = builder.withTransaction;
+          if (originalWithTransaction) {
+            builder.withTransaction = wrapMethodWithPreparation(
+              originalWithTransaction,
+              prepareValidatedItemSync,
+              builder
+            );
+          }
+          const originalWithBatch = builder.withBatch;
+          if (originalWithBatch) {
+            builder.withBatch = wrapMethodWithPreparation(originalWithBatch, prepareValidatedItemSync, builder);
+          }
+          return createEntityAwarePutBuilder(builder, config.name);
+        },
+        get: (key) => {
+          const builder = table.get(config.primaryKey.generateKey(key));
+          return createEntityAwareGetBuilder(builder, config.name);
+        },
+        update: (key, data) => {
+          const primaryKeyObj = config.primaryKey.generateKey(key);
+          const builder = table.update(primaryKeyObj);
+          builder.condition(eq(entityTypeAttributeName, config.name));
+          const entityAwareBuilder = createEntityAwareUpdateBuilder(builder, config.name);
+          entityAwareBuilder.configureEntityLogic({
+            data,
+            key,
+            table,
+            indexes: config.indexes,
+            generateTimestamps: () => generateTimestamps(["updatedAt"], data),
+            buildIndexUpdates
+          });
+          return entityAwareBuilder;
+        },
+        delete: (key) => {
+          const builder = table.delete(config.primaryKey.generateKey(key));
+          builder.condition(eq(entityTypeAttributeName, config.name));
+          return createEntityAwareDeleteBuilder(builder, config.name);
+        },
+        query: Object.entries(config.queries || {}).reduce(
+          (acc, [key, inputCallback]) => {
+            acc[key] = (input) => {
+              const queryEntity = {
+                scan: repository.scan,
+                get: (key2) => createEntityAwareGetBuilder(table.get(key2), config.name),
+                query: (keyCondition) => {
+                  return table.query(keyCondition);
+                }
+              };
+              const queryBuilderCallback = inputCallback(input);
+              const builder = queryBuilderCallback(queryEntity);
+              if (builder && typeof builder === "object" && "filter" in builder && typeof builder.filter === "function") {
+                builder.filter(eq(entityTypeAttributeName, config.name));
+              }
+              if (builder && typeof builder === "object" && "execute" in builder) {
+                const originalExecute = builder.execute;
+                builder.execute = async () => {
+                  const queryFn = config.queries[key];
+                  if (queryFn && typeof queryFn === "function") {
+                    const schema = queryFn.schema;
+                    if (schema?.["~standard"]?.validate && typeof schema["~standard"].validate === "function") {
+                      const validationResult = schema["~standard"].validate(input);
+                      if ("issues" in validationResult && validationResult.issues) {
+                        throw EntityErrors.queryInputValidationFailed(config.name, key, validationResult.issues, input);
+                      }
+                    }
+                  }
+                  const result = await originalExecute.call(builder);
+                  if (!result) {
+                    throw OperationErrors.queryFailed(config.name, { queryName: key }, void 0);
+                  }
+                  return result;
+                };
+              }
+              return builder;
+            };
+            return acc;
+          },
+          {}
+        ),
+        scan: () => {
+          const builder = table.scan();
+          builder.filter(eq(entityTypeAttributeName, config.name));
+          return builder;
+        }
+      };
+      return repository;
+    }
+  };
+}
+function createQueries() {
+  return {
+    input: (schema) => ({
+      query: (handler) => {
+        const queryFn = (input) => (entity) => handler({ input, entity });
+        queryFn.schema = schema;
+        return queryFn;
+      }
+    })
+  };
+}
+function createIndex() {
+  return {
+    input: (schema) => {
+      const createIndexBuilder = (isReadOnly = false) => ({
+        partitionKey: (pkFn) => ({
+          sortKey: (skFn) => {
+            const index = {
+              name: "custom",
+              partitionKey: "pk",
+              sortKey: "sk",
+              isReadOnly,
+              generateKey: (item) => {
+                const data = schema["~standard"].validate(item);
+                if ("issues" in data && data.issues) {
+                  throw ValidationErrors.indexSchemaValidationFailed(data.issues, "both");
+                }
+                const validData = "value" in data ? data.value : item;
+                return { pk: pkFn(validData), sk: skFn(validData) };
+              }
+            };
+            return Object.assign(index, {
+              readOnly: (value = false) => ({
+                ...index,
+                isReadOnly: value
+              })
+            });
+          },
+          withoutSortKey: () => {
+            const index = {
+              name: "custom",
+              partitionKey: "pk",
+              isReadOnly,
+              generateKey: (item) => {
+                const data = schema["~standard"].validate(item);
+                if ("issues" in data && data.issues) {
+                  throw ValidationErrors.indexSchemaValidationFailed(data.issues, "partition");
+                }
+                const validData = "value" in data ? data.value : item;
+                return { pk: pkFn(validData) };
+              }
+            };
+            return Object.assign(index, {
+              readOnly: (value = true) => ({
+                ...index,
+                isReadOnly: value
+              })
+            });
+          }
+        }),
+        readOnly: (value = true) => createIndexBuilder(value)
+      });
+      return createIndexBuilder(false);
+    }
+  };
+}
+
+export { createIndex, createQueries, defineEntity };