Skip to content

Support ReturnValuesOnConditionCheckFailure on write operations #551

@anatolzak

Description

@anatolzak

DynamoDB supports ReturnValuesOnConditionCheckFailure on PutItem, UpdateItem, and DeleteItem operations. When a conditional expression fails, DynamoDB can return the existing item as part of the error response instead of just throwing an error.

Currently, ElectroDB uses this capability internally for transactions, but it's not exposed for regular write operations (create, put, update, patch, delete, remove, upsert). Users who want to inspect the existing item when a condition fails must catch the error and manually extract/unmarshall the item data.

Proposed API:

Add a returnOnConditionCheckFailure: "all_old" option to go() on write operations. When set, instead of throwing on a condition check failure, the result includes a rejected discriminant:

// Condition passed — normal success
{ rejected: false, data: { /* normal response */ } }

// Condition failed — returns the existing item
{ rejected: true, data: { /* existing item */ } | null }

When the option is not provided, behavior is unchanged ({ data: ... } with no rejected field).

Example usage:

const result = await MyEntity
  .create({ id: "123", name: "Alice" })
  .go({ returnOnConditionCheckFailure: "all_old" });

if (result.rejected) {
  console.log("Item already exists:", result.data);
} else {
  console.log("Created:", result.data);
}

This is useful for optimistic locking, upsert-with-check patterns, and any workflow where you need to know why a condition failed without a separate read.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions