DynamoDB Update Item With AWS SDK v3: Conditions and Counters

// dynamodb-updates.ts
// UpdateItem patterns with AWS SDK for JavaScript v3 and the DynamoDB Document Client:
// SET/REMOVE, atomic counters, set ADD/DELETE, conditions, optimistic locking and a transaction.
import { ConditionalCheckFailedException, DynamoDBClient, TransactionCanceledException } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, TransactWriteCommand, UpdateCommand } from "@aws-sdk/lib-dynamodb";
import { unmarshall } from "@aws-sdk/util-dynamodb";

const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}), {
  marshallOptions: { removeUndefinedValues: true },
});
const TABLE = process.env.TABLE_NAME ?? "app";

export interface Product {
  pk: string; // "PRODUCT#<id>"
  sk: string; // "META"
  name: string;
  price: number;
  stock: number;
  views?: number;
  tags?: Set<string>;
  discontinuedAt?: string;
  version: number;
}

const productKey = (id: string) => ({ pk: `PRODUCT#${id}`, sk: "META" });

/** SET some attributes and REMOVE another in one call; fails instead of creating a new item. */
export async function renameProduct(id: string, name: string, price: number): Promise<Product> {
  const res = await ddb.send(new UpdateCommand({
    TableName: TABLE,
    Key: productKey(id),
    UpdateExpression: "SET #name = :name, price = :price, updatedAt = :now REMOVE discontinuedAt",
    ConditionExpression: "attribute_exists(pk)", // without this, UpdateItem upserts a new item
    ExpressionAttributeNames: { "#name": "name" }, // NAME is a DynamoDB reserved word
    ExpressionAttributeValues: { ":name": name, ":price": price, ":now": new Date().toISOString() },
    ReturnValues: "ALL_NEW",
  }));
  return res.Attributes as Product;
}

/** Atomic counter: no read first, safe under concurrency, but a retried call can count twice. */
export async function incrementViews(id: string, by = 1): Promise<number> {
  const res = await ddb.send(new UpdateCommand({
    TableName: TABLE,
    Key: productKey(id),
    UpdateExpression: "ADD #views :by",
    ExpressionAttributeNames: { "#views": "views" },
    ExpressionAttributeValues: { ":by": by },
    ReturnValues: "UPDATED_NEW",
  }));
  return Number(res.Attributes?.views ?? 0);
}

/** Add and remove members of a string set. A JavaScript Set marshals to a DynamoDB String Set. */
export async function retag(id: string, add: string[], remove: string[]): Promise<void> {
  const parts: string[] = [];
  const values: Record<string, Set<string>> = {};
  if (add.length) { parts.push("ADD tags :add"); values[":add"] = new Set(add); }
  if (remove.length) { parts.push("DELETE tags :remove"); values[":remove"] = new Set(remove); } // empty sets are invalid
  if (!parts.length) return;
  await ddb.send(new UpdateCommand({
    TableName: TABLE,
    Key: productKey(id),
    UpdateExpression: parts.join(" "),
    ExpressionAttributeValues: values,
  }));
}

/** Decrement stock only if enough is left. Returns false instead of going negative. */
export async function reserveStock(id: string, qty: number): Promise<boolean> {
  try {
    await ddb.send(new UpdateCommand({
      TableName: TABLE,
      Key: productKey(id),
      UpdateExpression: "SET stock = stock - :qty",
      ConditionExpression: "attribute_exists(pk) AND stock >= :qty",
      ExpressionAttributeValues: { ":qty": qty },
    }));
    return true;
  } catch (err) {
    if (err instanceof ConditionalCheckFailedException) return false;
    throw err;
  }
}

export class VersionConflictError extends Error {
  readonly current: Record<string, unknown> | undefined; // the item as it is now, if DynamoDB returned it
  constructor(current: Record<string, unknown> | undefined) {
    super("The item was changed by someone else since you read it");
    this.current = current;
  }
}

/** Optimistic locking: write only if the version is still the one you read, then bump it. */
export async function updatePrice(id: string, price: number, expectedVersion: number): Promise<Product> {
  try {
    const res = await ddb.send(new UpdateCommand({
      TableName: TABLE,
      Key: productKey(id),
      UpdateExpression: "SET price = :price, version = version + :one",
      ConditionExpression: "version = :expected",
      ExpressionAttributeValues: { ":price": price, ":one": 1, ":expected": expectedVersion },
      ReturnValues: "ALL_NEW",
      ReturnValuesOnConditionCheckFailure: "ALL_OLD",
    }));
    return res.Attributes as Product;
  } catch (err) {
    if (err instanceof ConditionalCheckFailedException) {
      // Item is in the low-level AttributeValue format, even with the Document Client.
      throw new VersionConflictError(err.Item ? unmarshall(err.Item) : undefined);
    }
    throw err;
  }
}

/** All-or-nothing: take stock and create the order, or do neither. */
export async function placeOrder(orderId: string, productId: string, qty: number): Promise<"ok" | "out-of-stock" | "duplicate"> {
  try {
    await ddb.send(new TransactWriteCommand({
      ClientRequestToken: orderId, // makes retries within 10 minutes idempotent
      TransactItems: [
        {
          Update: {
            TableName: TABLE,
            Key: productKey(productId),
            UpdateExpression: "SET stock = stock - :qty",
            ConditionExpression: "stock >= :qty",
            ExpressionAttributeValues: { ":qty": qty },
          },
        },
        {
          Put: {
            TableName: TABLE,
            Item: { pk: `ORDER#${orderId}`, sk: "META", productId, qty, createdAt: new Date().toISOString() },
            ConditionExpression: "attribute_not_exists(pk)",
          },
        },
      ],
    }));
    return "ok";
  } catch (err) {
    if (err instanceof TransactionCanceledException) {
      const [stock, order] = err.CancellationReasons ?? [];
      if (order?.Code === "ConditionalCheckFailed") return "duplicate";
      if (stock?.Code === "ConditionalCheckFailed") return "out-of-stock";
    }
    throw err;
  }
}

// run-updates.ts
// Usage: AWS_REGION=us-east-1 TABLE_NAME=app npx tsx run-updates.ts
import { incrementViews, placeOrder, renameProduct, reserveStock, retag, updatePrice, VersionConflictError } from "./dynamodb-updates.js";

const renamed = await renameProduct("p-100", "Trail Running Shoe", 129);
console.log(`renamed: ${renamed.name}, version ${renamed.version}`);

console.log(`views: ${await incrementViews("p-100")}`);
await retag("p-100", ["trail", "sale"], ["new"]);
console.log(`reserve 3: ${await reserveStock("p-100", 3)}`);

try {
  await updatePrice("p-100", 119, renamed.version); // succeeds and bumps the version
  await updatePrice("p-100", 109, renamed.version); // stale version: fails
} catch (err) {
  if (err instanceof VersionConflictError) console.log(`conflict: item is now at version ${String(err.current?.version)}`);
  else throw err;
}

console.log(`order o-9001: ${await placeOrder("o-9001", "p-100", 2)}`);
console.log(`order o-9001 again: ${await placeOrder("o-9001", "p-100", 2)}`);

npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb @aws-sdk/util-dynamodb
npm install --save-dev tsx typescript @types/node
npm pkg set type=module

AWS_PROFILE=dev AWS_REGION=us-east-1 TABLE_NAME=app npx tsx run-updates.ts
# renamed: Trail Running Shoe, version 3
# views: 1
# reserve 3: true
# conflict: item is now at version 4
# order o-9001: ok
# order o-9001 again: ok

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "UpdateProductsAndCreateOrders",
      "Effect": "Allow",
      "Action": [
        "dynamodb:UpdateItem",
        "dynamodb:PutItem",
        "dynamodb:ConditionCheckItem"
      ],
      "Resource": "arn:aws:dynamodb:us-east-1:123456789012:table/app"
    }
  ]
}