Skip to main content

Migration Guide: v1.2.0

This guide helps you upgrade from v1.1.x to v1.2.0. Version 1.2.0 includes one breaking change that requires code updates.

Release Date​

2026-04-02

Breaking Changes Summary​

ChangeImpactAction Required
publishSync / publishPartialUpdateSync return null on no-opReturn type is now Promise<CommandModel | null>Add null check before using the result

Pre-Migration Checklist​

Before upgrading, verify the following:

  • Search for publishSync() and publishPartialUpdateSync() calls and add null checks
  • Run the full test suite after upgrading

Breaking Change 1: publishSync Returns null on No-op​

What Changed​

publishSync() and publishPartialUpdateSync() now return null when the command is not dirty (the payload is identical to the existing version). This aligns with the behavior of publishAsync() and publishPartialUpdateAsync().

// Before (v1.1.x) — return type: Promise<CommandModel>
const result = await commandService.publishSync(input, options);
console.log(result.pk); // Always safe

// After (v1.2.0) — return type: Promise<CommandModel | null>
const result = await commandService.publishSync(input, options);
if (result) {
  console.log(result.pk); // Only access after null check
}

Migration Steps​

Step 1: Find all usages​

grep -rn "publishSync\|publishPartialUpdateSync" --include="*.ts" src/

Step 2: Add null checks​

For each call site, wrap the result in a null check before accessing any properties:

// Pattern 1: Early return on no-op
const result = await commandService.publishSync(input, options);
if (!result) return; // No-op — data was not dirty
// ... use result

// Pattern 2: Conditional processing
const result = await commandService.publishSync(input, options);
if (result) {
  await notifyUser(result.pk, result.sk);
}

Why This Change​

publishSync was previously inconsistent with publishAsync — the async variants already returned null on no-op. This change makes all four publish methods consistent and avoids confusing behavior where publishSync returned the existing record even when no write occurred.

Upgrade Steps​

Step 1: Update Dependencies​

npm install \
  @mbc-cqrs-serverless/core@^1.2.0 \
  @mbc-cqrs-serverless/tenant@^1.2.0 \
  @mbc-cqrs-serverless/master@^1.2.0 \
  @mbc-cqrs-serverless/sequence@^1.2.0 \
  @mbc-cqrs-serverless/task@^1.2.0 \
  @mbc-cqrs-serverless/cli@^1.2.0

Step 2: Apply Code Fixes​

  1. Add null checks for publishSync and publishPartialUpdateSync results (see above)

Step 3: Run Tests​

npm run test:cov

New Features in v1.2.0​

  • Read-Your-Writes (RYW) consistency — after publishAsync, subsequent reads by the same user return pending command data before DynamoDB Stream sync completes. Opt-in via RYW_SESSION_TTL_MINUTES environment variable. See CommandService: Read-Your-Writes for setup.

Support​

If you encounter issues during migration: