dyna-record
    Preparing search index...

    Type Alias WriteCondition<T>

    WriteCondition: {
        [K in keyof EntityFilterRecord<T>]?:
            | WriteConditionValue<T, K>
            | ForeignKeyGuardForKey<T, K>
    } & { $or?: SelfCondition<T>[] } & RelationshipConditions<T>

    The condition an update or delete accepts. The write happens only if every part holds, checked in the same transaction as the write. A condition only decides whether the write happens: it never changes which items are written, and when it fails nothing is written.

    One object holds three kinds of key, mirroring the entity's own shape:

    • Its own attributes, in the full query-filter vocabulary, guarding the entity's own row. null on a nullable attribute means "not set". $or combines blocks of these, and only these: DynamoDB evaluates a condition against one row, so OR never spans rows.
    • Its relationships, by property name. A BelongsTo or HasOne takes a TargetCondition on the related row, which the library resolves. A HasMany or HasAndBelongsToMany takes RelatedEntityCondition entries.
    • Its foreign keys that do not back a BelongsTo, which may guard the row they reference through a ForeignKeyTargetGuard. Such a key holds either a condition on its own value or a target guard, never both; the value condition goes in an $or branch.

    Unlike a query filter, an undefined operand is a FilterError rather than a dropped condition, because dropping part of a guard would loosen it; an empty $or is a FilterError too. So is a $or branch that holds no conditions: an empty branch always holds, so the whole $or would check nothing, and dropping the branch would tighten the $or to the others. A dot path or list-index path naming a field the schema does not declare is a FilterError naming the path.

    A failed condition is reported as a WriteConditionFailedError inside the TransactionWriteFailedError the write throws.

    Type Parameters

    • T extends default

      The entity being written.

    Type Declaration

    • Optional$or?: SelfCondition<T>[]

      Condition blocks on this entity's own row, combined with OR. A block names the entity's own attributes only: OR never spans rows.

    // Update an Order only while its total is under 100 and its Customer is Jane
    const condition: WriteCondition<Order> = {
      total: { $lt: 100 },
      customer: { name: "Jane" }
    };

    // Delete a Customer only if one of its Orders predates 2026
    const guard: WriteCondition<Customer> = {
      orders: [{ id: "order-1", condition: { orderDate: { $lt: new Date("2026-01-01") } } }]
    };

    // Ship an Order that has no tracking number yet, while it is pending or
    // under 50, and while its Store is open
    await Order.update(
      "order-1",
      { status: "shipped", trackingNumber: "1Z999" },
      {
        condition: {
          trackingNumber: null,
          $or: [{ status: "pending" }, { total: { $lt: 50 } }],
          storeId: { target: { status: "open" } }
        }
      }
    );

    // Close a Store only while it is in Springfield and its first contact,
    // compared whole, is Jane with no phone
    await Store.update(
      "store-1",
      { status: "closed" },
      {
        condition: {
          "address.city": "Springfield",
          "address.contacts[0]": { name: "Jane", phone: null }
        }
      }
    );

    Settings

    Member Visibility