DEV Community: Chris Rodriguez

Serializable vs SELECT FOR UPDATE vs advisory locks — pick the boundary, not the loudest tool

Chris Rodriguez — Fri, 23 Oct 2026 04:10:04 +0000

When two sessions can read the same state and then both write, the root issue is an unclear ownership boundary, not a missing lock. This article helps you decide between three PostgreSQL approaches by focusing on what owns the conflict and how each option fails.

Implementation summary

The article ships a tiny decision helper that takes a conflict description and returns one of three strategies plus a retry hint. That helper is deliberately small: it encodes the architectural decision rather than attempting to simulate PostgreSQL behavior. A companion routine emits a client-side retry sketch for SERIALIZABLE transactions. The server inserts the verified implementation example below.

Expected behavior

SERIALIZABLE: Choose this when the invariant is set-shaped or multi-row and the only safe guarantee is equivalence to some serial order. PostgreSQL enforces the serial-order rule and surfaces serialization failures as SQLSTATE 40001; your application must treat those as retryable errors and implement a retry loop on the client.
SELECT ... FOR UPDATE: Use when a single row owns the conflict. The waiting point is explicit and visible: acquire the row lock when you read and then update. This is often easier to reason about, but it only protects the rows you lock and can introduce blocking and deadlocks if transactions lock rows in inconsistent orders.
Transaction-scoped advisory locks: Choose when the protected unit is application-defined (tenant shard, workflow, job key) rather than row-shaped. Advisory locks are powerful because you name the resource, but they rely on every participant using the same convention; if some code path skips the lock or uses a different key, the protection silently fails.

Limitations and the practical decision rule

Failure shapes: SERIALIZABLE aborts and pushes complexity to retry handling; row locks block and can deadlock; advisory locks fail via protocol drift. Pick the mechanism whose failure you can reliably operate.
Edge cases: a conflict that looks row-shaped might actually be set-shaped; advisory locks can be the wrong abstraction if the logic naturally lives inside one transaction and you want the database to reject unsafe interleavings.
Operational constraints: keep critical sections short. Long transactions increase overhead and contention for every approach.

Read the article for the decision checklist, the small helper that encodes it, and clear guidance on where retry logic belongs (on the client, not hidden inside a fake in-database wrapper).

Working example

export function chooseConcurrencyControl({ conflictShape, canRetry, ownsRow, applicationScoped }) {
  if (!conflictShape || typeof conflictShape !== 'string') {
    throw new TypeError('conflictShape must be a non-empty string');
  }

  const shape = conflictShape.trim().toLowerCase();
  if (!shape) throw new TypeError('conflictShape must be a non-empty string');

  if (shape === 'serializable' || shape === 'set' || shape === 'multi-row') {
    return {
      strategy: 'SERIALIZABLE',
      reason: 'The invariant depends on a set or multi-row decision, so the database should detect non-serializable outcomes and the application must retry serialization failures.',
      retry: canRetry !== false
    };
  }

  if (shape === 'row' || ownsRow === true) {
    return {
      strategy: 'SELECT ... FOR UPDATE',
      reason: 'One row owns the conflict, so explicit row locking makes the waiting point direct and predictable.',
      retry: false
    };
  }

  if (shape === 'application' || applicationScoped === true) {
    return {
      strategy: 'TX_ADVISORY_LOCK',
      reason: 'The resource is application-defined rather than row-shaped, so a transaction-scoped advisory lock is a better fit.',
      retry: false
    };
  }

  return {
    strategy: 'SERIALIZABLE',
    reason: 'Default to serializable when the conflict boundary is unclear, because the database can enforce the serial-order rule and reject unsafe interleavings.',
    retry: canRetry !== false
  };
}

export function buildSerializableRetryLoop({ statement, maxAttempts = 3 }) {
  if (typeof statement !== 'string' || statement.trim() === '') {
    throw new TypeError('statement must be a non-empty string');
  }
  if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
    throw new RangeError('maxAttempts must be a positive integer');
  }

  return [
    'for attempt in 1..maxAttempts:',
    '  BEGIN ISOLATION LEVEL SERIALIZABLE;',
    `  ${statement.trim()}`,
    "  COMMIT;",
    "  if commit succeeds: return success",
    "  if SQLSTATE is '40001': retry",
    '  otherwise: rethrow'
  ].join('\n');
}

export function summarizeTradeoffs() {
  return {
    serializable: 'Use for set-shaped invariants that need database-enforced retry semantics.',
    rowLock: 'Use when a single row is the conflict owner and waiting is acceptable.',
    advisory: 'Use when the protected resource is application-scoped and not naturally a row.'
  };
}

Read the full article: https://chriseugenerodriguez.com/blog/serializable-vs-select-for-update-advisory-locks

Make Docker Compose wait for a backend that’s actually ready

Chris Rodriguez — Wed, 21 Oct 2026 23:25:04 +0000

Problem summary

Docker Compose guarantees startup order but not readiness. A dependency can be “running” long before it’s able to answer the queries or complete the bootstrap your app needs. People often patch this with sleeps or shallow probes — fragile approaches that pass locally and fail in the field.

Implementation approach (high level)

1) Define a healthcheck on the service that knows how to prove it’s truly ready. The check must exercise the actual boundary your dependent relies on (example: a simple query, a bootstrap-complete flag, or an authentication handshake), not merely an open port.

2) Make the dependent wait using depends_on with condition: service_healthy. That moves the readiness contract into the dependency and asks Compose to gate the dependent start on the dependency’s own proof.

Expected behavior

If the backend is running and its healthcheck reports healthy, the dependent is allowed to start.
If the backend is running but has no healthcheck (or the check fails), Compose cannot honor service_healthy and will block the dependent. This makes the missing signal visible instead of hiding it behind timing guesses.
If the backend is still in a starting state, the dependent remains blocked until the backend transitions to healthy.

Limitations and caveats

A healthcheck is only effective when it actually verifies the work the dependent needs. Superficial probes (e.g., “is port open?”) can still return success too early and recreate the race.
service_healthy is a startup gating mechanism. It reduces early-launch races but does not replace application-level error handling and retry logic for transient failures after startup.
This pattern depends on honest healthcheck design. If you’re unable to add meaningful checks to a third-party image, consider a lightweight init wrapper or a sidecar that verifies readiness on that service’s behalf.

Why this is better than sleep loops

Sleep loops are guesses about time and hide the contract. Health-based gating expresses the contract explicitly: the backend must prove readiness. That makes startup behavior observable, debuggable, and consistent across environments.

The article includes a tiny deterministic fixture (no Docker required) that proves the decision boundary between “running” and “healthy” and a checklist for what to put in a real Compose file. The server will append the verified Compose example immediately after this content.

Working example

export function evaluateStartability(services, targetServiceName) {
  if (!services || typeof services !== 'object' || Array.isArray(services)) {
    throw new TypeError('services must be an object')
  }

  const target = services[targetServiceName]
  if (!target) throw new Error(`service not found: ${targetServiceName}`)

  const deps = target.depends_on ?? {}
  const normalizedDeps = {}

  if (Array.isArray(deps)) {
    for (const name of deps) normalizedDeps[name] = { condition: 'service_started' }
  } else {
    for (const [name, val] of Object.entries(deps)) {
      if (val == null || val === 'short') {
        normalizedDeps[name] = { condition: 'service_started' }
      } else if (typeof val === 'string') {
        normalizedDeps[name] = { condition: val }
      } else {
        normalizedDeps[name] = { condition: val.condition ?? 'service_started' }
      }
    }
  }

  const reasons = []
  for (const [depName, opts] of Object.entries(normalizedDeps)) {
    const dep = services[depName]
    if (!dep) {
      reasons.push({ dep: depName, ok: false, why: 'missing' })
      continue
    }

    if (dep.state !== 'running') {
      reasons.push({ dep: depName, ok: false, why: `not running (${dep.state})` })
      continue
    }

    if (opts.condition === 'service_healthy') {
      if (!Object.prototype.hasOwnProperty.call(dep, 'health') || dep.health == null) {
        reasons.push({ dep: depName, ok: false, why: 'no healthcheck defined' })
        continue
      }
      if (dep.health !== 'healthy') {
        reasons.push({ dep: depName, ok: false, why: `health=${String(dep.health)}` })
        continue
      }
    }

    reasons.push({ dep: depName, ok: true, why: 'satisfied' })
  }

  return { ok: reasons.every((r) => r.ok), reasons }
}

export function makeService(state = 'running', health = null, depends_on = undefined) {
  return { state, health, depends_on }
}

Read the full article: https://chriseugenerodriguez.com/blog/compose-wait-for-ready-service

Make IndexedDB upgrades atomic and recoverable

Chris Rodriguez — Mon, 19 Oct 2026 01:10:04 +0000

Why this matters

IndexedDB schema changes aren’t just “make a new store” — they usually also move existing records into the new shape. If the browser aborts an upgrade after the destination is created but before every record is copied, your app can be left with a database that’s neither the old nor the new schema.

What this pattern does

Keep all structural work (create target store, copy records, remove source) inside the onupgradeneeded/versionchange callback so the browser’s versionchange transaction owns the entire move.
Before copying records, write a durable migration marker that survives an abort. The marker is a recovery hint, not the migration itself.
On next open, inspect the marker and the presence of source/target stores and choose the smallest recovery action: rerun the move, clear a stale marker, or remove a redundant source.

Expected behavior

Successful upgrade: the versionchange transaction commits, the target store exists with all records, and the marker is removed.
Simulated abort during move: the transaction aborts, the source remains intact, the marker persists. On next open, the recovery logic detects the marker and either retries the move to completion or clears the marker if the target already exists.
Edge cases: if both source and target exist, the conservative policy treats the target as canonical, removes the source, and clears the marker.

Limitations and when not to use it

This pattern assumes migrations are deterministic and repeatable using only local data. If the migration touches external services or non-idempotent transforms, retries may produce incorrect results and you’ll need a stronger reconciliation approach.
The example models browser behavior but cannot prove every real-world failure path (OS-level crashes, device power loss, or browser-specific flush timing). It proves the application-side recovery contract, not absolute cross-browser durability.

What you get from the repository

A small, honest simulator that models versionchange transactions, a durable migration marker, and recovery checks.
Tests that assert the recovery policy (marker cleared after success, marker present after abort, recovery re-applies the migration).

Working example

// Simulation of an IndexedDB-style versionchange migration that is
// atomic and recoverable. THIS IS A NODE-IN-MEMORY SIMULATOR, not
// real IndexedDB. It models the important behaviors (versionchange
// transaction, onabort/oncomplete, durable migration marker) so the
// article can demonstrate detection of partial upgrades and a retry
// path that either completes or rolls back the migration.
//
// Public API:
// - createFixture(stores): returns an in-memory DB object { stores, meta }
// - migrateMove(db, fromName, toName, { shouldAbortDuringMove })
//     Performs a versionchange-style migration that moves all records
//     from `fromName` to `toName` atomically. It writes a durable
//     marker (meta._migration) to indicate progress; if aborted, the
//     marker persists to simulate a partially-applied upgrade.
// - detectAndRecover(db, fromName, toName): looks for partial
//     migration and either rolls back or completes the move so the DB
//     ends up consistent.
//
// This simulator intentionally exposes the metadata needed by the
// recovery algorithm so tests can assert the exact recovery behavior.

export function createFixture(stores = {}) {
  // stores: { name: { [key]: value } }
  const clone = JSON.parse(JSON.stringify(stores));
  return {
    stores: clone,
    // meta simulates on-disk migration markers that survive an abort.
    meta: {}
  };
}

// Internal helper to deep clone store contents
function cloneStore(store) {
  return JSON.parse(JSON.stringify(store));
}

// Perform a migration that moves all records from an existing store
// `fromName` into a new store `toName` inside a single "versionchange"
// transaction. The transaction can be forced to abort mid-transfer by
// setting shouldAbortDuringMove to true. When the transaction starts
// we write a durable meta marker { migrating: { from,to } } before
// starting to move records to simulate on-disk progress visibility.
// If the transaction aborts, the stores must be left as if the
// transaction never happened (rolled back), but the durable marker
// may remain to indicate partial progress — this models a browser
// crash between steps. A real IndexedDB upgrade should ensure the
// onupgradeneeded handler leaves a detectable and recoverable state.
export function migrateMove(db, fromName, toName, options = {}) {
  const { shouldAbortDuringMove = false } = options;

  if (!db.stores[fromName]) {
    throw new Error('source store not found: ' + fromName);
  }
  if (db.stores[toName]) {
    throw new Error('target store already exists: ' + toName);
  }

  // Begin "versionchange transaction"
  const tx = {
    aborted: false,
    onabort: null,
    oncomplete: null
  };

  // Durable marker written at the start of upgrade, visible across
  // crashes/aborts in this simulation.
  db.meta._migration = { state: 'in-progress', from: fromName, to: toName };

  // Create the new store but buffer its contents locally (not yet
  // committed) to simulate transaction-local writes.
  const stagedTo = {};

  try {
    const source = db.stores[fromName];
    const keys = Object.keys(source);

    for (let i = 0; i < keys.length; i++) {
      const k = keys[i];
      // copy value into staged target
      stagedTo[k] = cloneStore(source[k]);

      // Optionally abort mid-transfer to simulate a thrown exception
      if (shouldAbortDuringMove && i === Math.floor(keys.length / 2)) {
        throw new Error('simulated mid-migration crash');
      }
    }

    // If we reach here, commit the staged writes atomically.
    db.stores[toName] = stagedTo;
    // Remove source store to model a move
    delete db.stores[fromName];

    // Clear durable marker and mark transaction complete
    delete db.meta._migration;
    tx.aborted = false;
    if (tx.oncomplete) tx.oncomplete();
    return { committed: true };
  } catch (err) {
    tx.aborted = true;
    if (tx.onabort) tx.onabort(err);

    // On abort, we must leave the logical stores as if transaction
    // never happened — rollback staged changes. We intentionally
    // keep db.meta._migration to simulate a partially applied
    // on-disk marker that recovery must inspect.
    // Note: we do NOT delete db.meta._migration here to simulate a
    // crash that occurred after the marker was written but before
    // the migration completed.

    return { committed: false, error: err };
  }
}

// Detect a partially-applied migration and recover it. Recovery policy:
// - If meta indicates an in-progress migration from->to and the target
//   store exists, assume commit succeeded and remove the marker.
// - If meta indicates in-progress but target doesn't exist, it means
//   the migration didn't finish. In that case, we rollback any remnants
//   and retry the migration to complete it atomically.
// This function returns an object describing what it did.
export function detectAndRecover(db, fromName, toName, options = {}) {
  const m = db.meta._migration;
  if (!m || m.from !== fromName || m.to !== toName) {
    return { recovered: false, reason: 'no-migration-marker' };
  }

  const targetExists = Boolean(db.stores[toName]);
  const sourceExists = Boolean(db.stores[fromName]);

  if (targetExists && !sourceExists) {
    // Looks like commit succeeded but marker wasn't cleared.
    delete db.meta._migration;
    return { recovered: true, action: 'cleared-marker' };
  }

  if (!targetExists && sourceExists) {
    // Partial: migration marker exists but nothing committed. Retry
    // the migration but ensure it completes atomically.
    const retry = migrateMove(db, fromName, toName, options);
    if (retry.committed) return { recovered: true, action: 'reapplied' };
    return { recovered: false, action: 'retry-failed', error: retry.error };
  }

  // Edge case: both exist (duplicate). Prefer target as canonical
  // (assume it committed), remove source and marker.
  if (targetExists && sourceExists) {
    delete db.stores[fromName];
    delete db.meta._migration;
    return { recovered: true, action: 'removed-source-presumed-commit' };
  }

  return { recovered: false, reason: 'unknown-state' };
}

Read the full article: https://chriseugenerodriguez.com/blog/indexeddb-atomic-recoverable-migration

Version the wire schema, normalize at the boundary, and keep failures visible

Chris Rodriguez — Sat, 17 Oct 2026 22:10:06 +0000

Problem statement

When you change a function-calling or Structured Outputs schema after users have active conversations, older turns and replayed tool calls may still emit the previous wire shape. A simple rename or a newly required field can break the next turn of a conversation that began under the old contract.

Implementation approach (high level)

1) Version the wire schema the model sees. Keep a v1, v2, etc. definition for the JSON the model is encouraged to emit.

2) Validate strictly at the server boundary. Use additionalProperties:false and explicit required lists to make drift visible — failures should be loud and explainable.

3) Normalize into one canonical internal object. Implement an adapter that recognizes known wire versions and translates them into the single canonical shape your application consumes.

4) Keep adapter policy explicit. The adapter is where you decide how to treat renames, nulls-as-optional stand-ins, defaults, and other compatibility choices. Treat unknown shapes as a closed failure.

Expected behavior

New conversations can be guided toward the newest wire schema without immediately invalidating older ones.
Replayed or still-in-flight conversations that emit older shapes can be accepted during the compatibility window because the adapter knows how to read them and normalize them into the canonical object.
Invalid payloads still fail loudly at the validation boundary, making it clear whether the failure is: a model proposal outside the schema, a missing required field for that wire version, or an unrecognized payload that needs policy work.

Limitations and operational notes

This pattern does not provide infinite backward compatibility. You must decide how long to accept old wire versions and when to remove adapter logic.
The Structured Outputs and Function Calling guides restrict certain schema features (root-level anyOf, permissive keywords). If compatibility needs rely on unsupported JSON Schema constructs, implement that logic in the adapter rather than the schema.
Policy decisions matter: renames, null for optional, defaulting, and whether adapters synthesize missing data are organizational choices. Make them explicit and test them.

Why this matters

Separating the model-facing contract from the server adapter keeps downstream code simple and stable while letting the model-facing schema evolve. It makes rollouts reversible, migration windows explicit, and failures actionable.

(Implementation example is inserted by the server.)

Working example

export const v1FunctionSchema = {
  type: 'object',
  additionalProperties: false,
  required: ['orderId', 'items'],
  properties: {
    orderId: { type: 'string' },
    items: {
      type: 'array',
      items: {
        type: 'object',
        additionalProperties: false,
        required: ['id', 'qty'],
        properties: {
          id: { type: 'string' },
          qty: { type: 'number' }
        }
      }
    }
  }
};

export const v2FunctionSchema = {
  type: 'object',
  additionalProperties: false,
  required: ['order_id', 'items', 'priority'],
  properties: {
    order_id: { type: 'string' },
    items: {
      type: 'array',
      items: {
        type: 'object',
        additionalProperties: false,
        required: ['id', 'qty'],
        properties: {
          id: { type: 'string' },
          qty: { type: 'number' }
        }
      }
    },
    priority: { type: ['boolean', 'null'] }
  }
};

function matchesType(value, typeDef) {
  if (Array.isArray(typeDef)) return typeDef.some((t) => matchesType(value, t));
  if (typeDef === 'null') return value === null;
  if (typeDef === 'string') return typeof value === 'string';
  if (typeDef === 'number') return typeof value === 'number' && Number.isFinite(value);
  if (typeDef === 'boolean') return typeof value === 'boolean';
  if (typeDef === 'array') return Array.isArray(value);
  if (typeDef === 'object') return value !== null && typeof value === 'object' && !Array.isArray(value);
  return false;
}

function checkObject(value, schema, path) {
  if (!matchesType(value, schema.type)) {
    return { ok: false, reason: `${path || 'root'} must be ${Array.isArray(schema.type) ? schema.type.join('|') : schema.type}` };
  }

  const properties = schema.properties || {};
  const required = schema.required || [];

  if (schema.additionalProperties === false) {
    for (const key of Object.keys(value)) {
      if (!Object.hasOwn(properties, key)) {
        return { ok: false, reason: `${path || 'root'} additional property: ${key}` };
      }
    }
  }

  for (const key of required) {
    if (!Object.hasOwn(value, key)) {
      return { ok: false, reason: `${path || 'root'} missing required: ${key}` };
    }
  }

  for (const [key, propSchema] of Object.entries(properties)) {
    if (!Object.hasOwn(value, key)) continue;
    const child = value[key];
    const childPath = path ? `${path}.${key}` : key;

    if (propSchema.type === 'array') {
      if (!Array.isArray(child)) return { ok: false, reason: `${childPath} must be array` };
      for (let i = 0; i < child.length; i++) {
        const item = child[i];
        if (propSchema.items?.type === 'object') {
          const result = checkObject(item, propSchema.items, `${childPath}[${i}]`);
          if (!result.ok) return result;
        } else if (!matchesType(item, propSchema.items?.type)) {
          return { ok: false, reason: `${childPath}[${i}] wrong type` };
        }
      }
      continue;
    }

    if (propSchema.type === 'object') {
      const result = checkObject(child, propSchema, childPath);
      if (!result.ok) return result;
      continue;
    }

    if (!matchesType(child, propSchema.type)) {
      return { ok: false, reason: `${childPath} wrong type` };
    }
  }

  return { ok: true };
}

export function validateStrict(args, schema) {
  return checkObject(args, schema, '');
}

export function isRejectedBySchema(args, schema) {
  const result = validateStrict(args, schema);
  return result.ok ? { rejected: false } : { rejected: true, reason: result.reason };
}

export function adaptToCanonical(args) {
  if (args && typeof args === 'object' && !Array.isArray(args)) {
    if (Object.hasOwn(args, 'orderId')) {
      return {
        orderId: String(args.orderId),
        items: Array.isArray(args.items)
          ? args.items.map((item) => ({ id: String(item.id), qty: Number(item.qty) }))
          : [],
        priority: false
      };
    }

    if (Object.hasOwn(args, 'order_id')) {
      return {
        orderId: String(args.order_id),
        items: Array.isArray(args.items)
          ? args.items.map((item) => ({ id: String(item.id), qty: Number(item.qty) }))
          : [],
        priority: args.priority === null ? false : Boolean(args.priority)
      };
    }
  }

  throw new Error('unrecognized argument shape: cannot adapt');
}

export function vetModelFunctionCall(argumentsJSON, schema) {
  let parsed;
  try {
    parsed = JSON.parse(argumentsJSON);
  } catch {
    return { accepted: false, reason: 'invalid JSON' };
  }

  const validation = validateStrict(parsed, schema);
  if (!validation.ok) return { accepted: false, reason: validation.reason };

  return { accepted: true, canonical: adaptToCanonical(parsed) };
}

Read the full article: https://chriseugenerodriguez.com/blog/evolving-function-schemas-without-breaking-live-conversations

Nested popovers: keyboard order and two light-dismiss boundaries

Chris Rodriguez — Fri, 16 Oct 2026 05:40:06 +0000

Test the boundary, not an assumed focus trap

Nested popovers have two different light-dismiss boundaries: a click inside the parent closes the child; a click outside the entire stack closes both. Popovers remain non-modal. Use showPopover({ source }) for the invocation relationship, and test application-owned selection focus separately from native dismissal.

A small browser fixture

The panels are labeled groups of buttons, not a complete ARIA menu. The child is a DOM sibling opened from a source inside the parent. Tab enters the child after that source. Clicking an option explicitly restores source focus.

Save as main.mjs:

// Two sibling auto popovers. The source establishes their logical nesting.
export const fixture = `<!doctype html>
<html lang="en"><head><meta charset="utf-8"><title>Nested popover checks</title>
<style>
body { font: 16px system-ui; padding: 24px; }
[popover] { position: fixed; inset: 120px auto auto 40px; margin: 0; width: 220px; padding: 16px; border: 1px solid; background: white; color: black; }
#subMenu { left: 320px; }
[popover] button { display: block; margin: 8px 0; }
</style></head><body>
<button id="menuToggle" popovertarget="parentMenu">Open options</button>
<button id="afterControl">Background action</button>
<div id="parentMenu" popover="auto" role="group" aria-label="Options">
  <button id="openSubProg" aria-expanded="false" aria-controls="subMenu" aria-details="subMenu">More options</button>
  <button id="parentOption2">Parent action</button>
</div>
<div id="subMenu" popover="auto" role="group" aria-label="More options">
  <button id="subItem1">Choose first option</button>
  <button id="subItem2">Choose second option</button>
</div>
<script>
const trigger = document.getElementById('openSubProg');
const sub = document.getElementById('subMenu');
function openSub() { sub.showPopover({ source: trigger }); }
trigger.addEventListener('click', openSub);
trigger.addEventListener('keydown', event => {
  if (event.key === 'ArrowRight') { event.preventDefault(); openSub(); }
});
sub.addEventListener('toggle', () => {
  trigger.setAttribute('aria-expanded', String(sub.matches(':popover-open')));
});
for (const button of sub.querySelectorAll('button')) {
  button.addEventListener('click', () => {
    sub.hidePopover();
    // Selection is an application action: explicitly return to its source.
    trigger.focus();
  });
}
</script></body></html>`;

Run and interpret the checks

With Node 22, run npm init -y, npm install --save-dev playwright@1.63.0, and npx playwright install chromium. Save the article's main.test.mjs beside the fixture and run node --test main.test.mjs.

The seven cases cover keyboard order, both click boundaries, sequential Escape, selection focus, non-modal background focus, and parent closure. waitForFunction receives one serialized argument, not multiple positional selectors.

Do not infer a focus trap or universal Escape focus restoration from the source option. The selection handler owns its explicit focus move. There is no generic microtask workaround for arbitrary toggle reentrancy. These Chromium checks do not replace cross-browser or screen-reader testing.

Full test file and explanation: https://chriseugenerodriguez.com/blog/accessible-nested-popovers-showpopover-focus-light-dismiss

Cancellable, backpressure-aware Transform streams (pattern and trade-offs)

Chris Rodriguez — Thu, 15 Oct 2026 01:40:04 +0000

When you accept async-iterator input and must both respect backpressure and stop promptly on cancel, treat the Transform as the single place that owns transformation logic and cancellation state. The producer (the async iterator) should write one item at a time and check write()'s boolean return. If write() returns false, await the stream's 'drain' event before continuing. That keeps the backlog bounded by Node's writable buffer, rather than by the source's speed.

Make cancellation visible: cancel() should be idempotent, record the first cancel reason, and destroy the Transform with that error so pipeline() surfaces the failure to callers. Distinguish an ordinary end (source finished) from an abort (user cancelled) — collapsing them loses the ability to assert why work stopped.

Expected behavior from this pattern:

Input order is preserved and each chunk is transformed exactly once.
A fast async-iterator producer cannot flood the stream because the helper waits for 'drain' when write() returns false.
cancel() aborts the pipeline with the supplied error and prevents further output; repeated cancels keep the first error as the canonical reason.

Limitations and when not to use it:

This pattern intentionally avoids hidden queues or parallel processing inside the Transform. If your application needs parallel transforms, retry policies, or smoothing over slow consumers, design those concerns separately.
It does not prove memory behavior for arbitrary payload sizes or replace integration testing with real sinks/sources (files, sockets, databases). Use this pattern as a clear contract for ownership, then add and test additional features as needed.

The article shows a minimal, test-backed implementation and a small test suite that verifies the three core properties above. The provided example is object-mode focused so the control flow remains visible; adapt and integration-test for your real data shapes before production use.

Working example

import { Transform, Writable } from 'node:stream';
import { finished } from 'node:stream/promises';

function waitForDrain(stream) {
  return new Promise((resolve, reject) => {
    const cleanup = () => {
      stream.off('drain', drained);
      stream.off('error', failed);
      stream.off('close', closed);
    };
    const drained = () => { cleanup(); resolve(); };
    const failed = (err) => { cleanup(); reject(err); };
    const closed = () => failed(stream.errored || Object.assign(new Error('Stream closed before drain'), {
      code: 'ERR_STREAM_PREMATURE_CLOSE',
    }));
    stream.once('drain', drained);
    stream.once('error', failed);
    stream.once('close', closed);
    if (stream.destroyed) closed();
  });
}

export class CancellableTransform extends Transform {
  constructor(opts = {}) {
    super({ ...opts, objectMode: true });
    this._cancelled = false;
    this._cancelError = null;
  }

  cancel(err = new Error('Cancelled')) {
    if (this._cancelled) return;
    this._cancelled = true;
    this._cancelError = err;
    this.destroy(err);
  }

  async _transform(chunk, _enc, callback) {
    try {
      await Promise.resolve();
      if (this._cancelled) throw this._cancelError;
      this.push({ ...chunk, processed: true });
      callback();
    } catch (err) {
      callback(err);
    }
  }

  async runFromAsyncIterable(iterable) {
    // Observe failure immediately, even while the producer is awaiting a value.
    // Keep the result as a value until we can rethrow it to the caller.
    const completion = finished(this, { readable: false, cleanup: true }).then(
      () => null, (err) => err,
    );
    try {
      if (this._cancelled) throw this._cancelError;
      for await (const item of iterable) {
        if (this._cancelled) throw this._cancelError;
        if (this.destroyed) throw this.errored || new Error('Stream closed');
        if (!this.write(item)) {
          // A close without an error must also settle the wait for drain.
          await waitForDrain(this);
        }
      }
      this.end();
      const error = await completion;
      if (error) throw error;
    } catch (err) {
      if (!this.destroyed) this.destroy(err);
      await completion;
      throw err;
    }
  }
}

export function createCollector() {
  const items = [];
  const writable = new Writable({
    objectMode: true,
    write(chunk, _enc, callback) {
      items.push(chunk);
      callback();
    },
  });
  // pipeline() is the single completion/error promise; no second, easily
  // forgotten rejection is created by this collector.
  return { writable, items };
}

Read the full article: https://chriseugenerodriguez.com/blog/cancellable-backpressure-transform-streams

Error ownership and cancellation boundary: Attach pipeline() and its rejection handler before calling cancel(), including when testing an already-cancelled transform. The collector exposes only its writable stream and items; pipeline() is the single completion/error promise. The feeder observes writable completion before ending input and handles close as well as error while waiting for drain. Cancellation cannot interrupt arbitrary work inside a producer that is awaiting its next value; that source must also accept a cooperative abort signal when prompt interruption of its I/O is required.

Reuse cache mounts reliably across multi-stage Dockerfiles

Chris Rodriguez — Tue, 13 Oct 2026 21:55:05 +0000

Problem summary

When a small source change makes a Docker build re-run dependency installs, many developers say “the cache didn’t work.” The clearer diagnosis is that Docker has at least two different cache mechanisms: instruction/layer cache (which can skip an instruction entirely) and cache mounts (which provide a persistent directory to a step when that step runs). They solve different problems and have different guarantees.

Implementation approach

This article keeps the implementation narrow and verifiable: create a helper that validates the fields Docker documents for RUN --mount=type=cache, emits the mount declaration exactly, and uses a sensible default identity. Concretely, the helper verifies that the mount target is a non-empty absolute path composed of safe characters, that an explicit id (if provided) is a non-empty safe string, and that sharing is one of the documented values (shared, private, locked). The helper then returns the canonical shape for the mount options and formats the --mount fragment you will paste into a Dockerfile instruction.

Expected behavior

Default id equals the mount target path. That mirrors Docker's documented default and gives a stable, readable identity in multi-stage builds.
When the install step runs, the mount provides the package manager's actual cache directory so downloads can be reused if the builder still holds the storage.
Choose sharing=locked when a tool expects exclusive access to the cache files (helps with file-locking semantics on CI with concurrent builds).

Limitations and practical notes

A correct mount declaration does not force persistence across fresh builder instances. Docker stores cache mounts in the builder’s local storage; if your CI creates a fresh builder each job or the builder garbage-collects storage, the mount will start empty.
Cache mounts make reruns cheaper by preserving downloaded artifacts, but they do not change Docker’s invalidation rules. If a dependency manifest changes, the install step should run again; the mount only reduces the download cost during that rerun.
The helper intentionally restricts allowable characters in target and id to avoid injection into the flag syntax. Projects that need broader naming schemes should provide a separate, reviewed configuration path.

Why this framing helps

By separating what the Dockerfile can guarantee (a valid, stable mount declaration) from what the environment must provide (builder-local persistence), you get a predictable place to reason about performance: fix the declaration first, then address your CI/builder topology if persistence is still missing.

(The server will insert the verified implementation example as a fenced code block below this explanation.)

Working example

const SHARING_VALUES = new Set(['shared', 'private', 'locked']);
const SAFE_COMPONENT = /^[A-Za-z0-9_./-]+$/;

export function validateCacheMountInput({ target, id, sharing = 'shared' } = {}) {
  if (typeof target !== 'string' || target.length === 0) {
    throw new TypeError('target must be a non-empty string');
  }
  if (!target.startsWith('/')) {
    throw new RangeError('target must be an absolute path');
  }
  if (!SAFE_COMPONENT.test(target)) {
    throw new RangeError('target must contain only letters, digits, slash, dot, underscore or hyphen');
  }

  if (id !== undefined) {
    if (typeof id !== 'string' || id.length === 0) {
      throw new TypeError('id must be a non-empty string when provided');
    }
    if (!SAFE_COMPONENT.test(id)) {
      throw new RangeError('id must contain only letters, digits, slash, dot, underscore or hyphen');
    }
  }

  if (!SHARING_VALUES.has(sharing)) {
    throw new RangeError('sharing must be one of shared, private, locked');
  }
}

export function buildCacheMountOptions({ target, id, sharing = 'shared' } = {}) {
  validateCacheMountInput({ target, id, sharing });
  return { type: 'cache', target, id: id ?? target, sharing };
}

export function formatRunMount(options) {
  const { type, target, id, sharing } = buildCacheMountOptions(options);
  return `--mount=type=${type},target=${target},id=${id},sharing=${sharing}`;
}

Read the full article: https://chriseugenerodriguez.com/blog/reuse-cache-mounts-multi-stage-dockerfiles

Why container queries stop matching when you switch container-type dynamically?

Chris Rodriguez — Tue, 13 Oct 2026 08:10:04 +0000

When a component flips classes at runtime, a container query can stop matching even when the DOM and sizes look fine. The root cause is often containment eligibility: the browser first finds an eligible container ancestor, then checks the axis or name your query uses. If the container’s container-type no longer supports the axis you ask for, there is simply no valid target and the query fails.

Implementation

Decide which axis your queries use. Width-based checks use the inline axis; height-based checks use the block axis. Use container-type: size when you need both axes, or container-type: inline-size when you only ever need inline-axis queries.
If you need to target a specific wrapper to avoid accidental matches, use container-name. Remember that naming preserves which container the browser will consider, but it does not add axis support.
When refactoring or toggling classes, inspect the container ancestor at the exact moment of the change: is there still a qualifying container, does it have the expected name (if you rely on names), and does it support the axis you query?

Expected behavior

With container-type: size, both inline (width) and block (height) queries can match the same container.
With container-type: inline-size, inline-axis queries continue to work but block-axis queries will report no eligible container.
Name-only queries can still resolve a named container regardless of axis, but axis-based checks still require the appropriate container-type.

Limitations

This diagnosis demonstrates container eligibility logic. It does not replace checking your real page for selector specificity, layout overrides, or browser rendering differences.
If a query fails because the container is too small, or because the element moved to a different ancestor chain, the correct fix is not always changing container-type.

The article includes a compact deterministic fixture that reproduces the toggle, shows the failing state, and demonstrates both repairs: keep an appropriate container-type for axis queries or use container naming for targeting problems. Use the fixture’s diagnostics to separate container discovery issues from axis-eligibility problems.

Working example

export function createElement({ tag = 'div', width = 0, height = 0 } = {}) {
  return {
    tag,
    width,
    height,
    parent: null,
    children: [],
    containerType: 'normal',
    containerName: undefined,
  };
}

export function appendChild(parent, child) {
  child.parent = parent;
  parent.children.push(child);
}

export function setContainerType(el, type) {
  el.containerType = type;
}

export function setContainerName(el, name) {
  el.containerName = name;
}

export function toggleContainerType(el, nextType) {
  setContainerType(el, nextType);
}

function compare(op, left, right) {
  switch (op) {
    case '>': return left > right;
    case '>=': return left >= right;
    case '<': return left < right;
    case '<=': return left <= right;
    default: throw new Error(`unsupported compare operator: ${op}`);
  }
}

function queryAxis(query) {
  if (query.kind === 'name-only') return null;
  if (query.axis) return query.axis;
  if (query.feature === 'width') return 'inline';
  if (query.feature === 'height') return 'block';
  return null;
}

export function findEligibleContainer(startEl, query) {
  let node = startEl.parent;
  const axis = queryAxis(query);

  while (node) {
    if (query.kind === 'name-only') {
      if (node.containerName === query.name) return node;
    } else if (axis) {
      if (node.containerType === 'size') return node;
      if (node.containerType === 'inline-size' && axis === 'inline') return node;
    }
    node = node.parent;
  }

  return null;
}

export function evaluateQuery(targetEl, query) {
  const container = findEligibleContainer(targetEl, query);
  if (!container) {
    return { matched: false, reason: 'no-eligible-container', container: null };
  }

  if (query.kind === 'name-only') {
    return { matched: true, container };
  }

  const axis = queryAxis(query);
  const size = axis === 'inline' ? container.width : container.height;
  return {
    matched: compare(query.compare, size, query.value),
    container,
    containerValue: size,
  };
}

Read the full article: https://chriseugenerodriguez.com/blog/why-do-container-queries-stop-matching-when-you-switch-container-type-dynamically

How AsyncLocalStorage.run() isolates request context across concurrent async calls

Chris Rodriguez — Sun, 11 Oct 2026 09:25:18 +0000

Implementation overview

Use a single AsyncLocalStorage instance and deterministic fixtures that exercise overlapping requests without timers. Each request calls asyncLocalStorage.run(store, callback) synchronously; inside the callback you create controlled awaits (manually resolved promises) and record asyncLocalStorage.getStore() at several checkpoints: immediately, after the first await, and after the second await. Run two requests concurrently and interleave the resolutions to prove each request keeps its own store even when their continuations mix.

Expected behavior

Each run(callback) establishes a store visible synchronously inside the callback and from any asynchronous work created there. Two overlapping runs each observe only their own store at every checkpoint, so logs or per-request values won’t be accidentally mixed.
Nested run(outerStore, ...) that starts an inner run(innerStore, ...) temporarily replaces the store for the inner callback; when the inner callback completes, the outer store is restored for the remainder of the outer work.
asyncLocalStorage.getStore() returns undefined outside any active run() and after a run() callback throws; the context does not leak.

Limitations

AsyncLocalStorage is not a security boundary. Any code already running in the process that can read the store has access to its values; do not rely on it to protect secrets.
The store doesn’t automatically cross process or service boundaries. If you dispatch work to another process, thread, or service, you must explicitly propagate the ID.
The API attaches values to the async chain created inside the run() callback. If your code creates asynchronous work elsewhere (not inside run()), that work will not automatically see the store.

Why use a deterministic fixture

Using manually resolved promises in the fixture removes timing flakiness: you don’t rely on slow timers or specific scheduler timings to provoke interleaving. The test explicitly drives the interleaving you want to prove, so you can demonstrate the broken shared-variable model and the correct AsyncLocalStorage behavior reliably.

Server will insert the verified implementation example below.

Working example

import { AsyncLocalStorage } from 'node:async_hooks';

// This module exports three factory functions that create controllable
// async scenarios using the real Node.js v22 AsyncLocalStorage API.
// Nothing runs on import.

// Helper: create an externally-resolvable promise
function makeDeferred() {
  let resolve, reject;
  const p = new Promise((res, rej) => { resolve = res; reject = rej; });
  return { promise: p, resolve, reject };
}

// Each spawn* function returns an object with
// - controllers: the external resolvers the test will call to drive progress
// - finished: a promise that resolves when the async scenario completes or rejects if it throws
// - records: a promise that resolves to an array of observed store values in sequence

export function spawnRequest(asyncLocalStorage, id) {
  // Two manual async hops controlled from the outside
  const step1 = makeDeferred();
  const step2 = makeDeferred();

  // The recorded values observed inside the async run
  // We record at three moments: immediately inside run, after awaiting step1, after awaiting step2.
  const records = [];

  const finished = asyncLocalStorage.run(id, async () => {
    // immediately visible
    records.push(asyncLocalStorage.getStore());

    // create two promise-based async hops; the test resolves them to control interleaving
    await step1.promise;
    records.push(asyncLocalStorage.getStore());

    await step2.promise;
    records.push(asyncLocalStorage.getStore());

    return records;
  });

  // run() returns the callback's return value (a Promise here) synchronously
  // but it executes the callback and the contained async-await chain inside the provided store.
  return {
    controllers: { resolveStep1: step1.resolve, resolveStep2: step2.resolve },
    finished, // Promise that resolves to records
  };
}

export function spawnRequestWithNested(asyncLocalStorage, outerId, innerId) {
  // Demonstrates nested run() and restoration of the outer context after inner finishes
  const innerDone = makeDeferred();
  const records = [];

  const finished = asyncLocalStorage.run(outerId, async () => {
    records.push(asyncLocalStorage.getStore()); // outer visible

    // start a nested run synchronously inside the outer run
    // nested run should temporarily replace the store for its callback
    const nestedResult = asyncLocalStorage.run(innerId, () => {
      // inside nested callback
      records.push(asyncLocalStorage.getStore()); // should be innerId
      // wait for external signal to finish nested part
      return innerDone.promise.then(() => asyncLocalStorage.getStore());
    });

    // nestedResult is a promise that resolves after innerDone.resolve() is called
    const innerObserved = await nestedResult;
    records.push(innerObserved); // snapshot returned from nested callback

    // After nested run completes, the outer store should be restored for the remainder
    records.push(asyncLocalStorage.getStore()); // should be outerId again

    return records;
  });

  return {
    controllers: { completeInner: innerDone.resolve },
    finished,
  };
}

export function spawnRequestThatThrows(asyncLocalStorage, id) {
  // Demonstrates that if callback throws, context is exited / restored and the exception propagates
  const step = makeDeferred();
  const records = [];

  const finished = asyncLocalStorage.run(id, async () => {
    records.push(asyncLocalStorage.getStore());
    // wait for external signal, then throw
    await step.promise;
    throw new Error('boom-' + id);
  });

  return { controllers: { trigger: step.resolve }, finished, recordsPromise: Promise.resolve(records) };
}

// Small helper to demonstrate the pitfall of a shared mutable variable
export function runWithSharedVariable(shared, id, stepPromise) {
  // This is not using AsyncLocalStorage. It mutates a shared object and performs async hops.
  // The test will show this approach can interleave and leak values between concurrent requests.
  return (async () => {
    shared.value = id; // overwrite shared state
    const seenBefore = shared.value;
    await stepPromise; // yield to the event loop / other tasks
    const seenAfter = shared.value; // may have been changed by another concurrent request
    return [seenBefore, seenAfter];
  })();
}

Read the full article: https://chriseugenerodriguez.com/blog/node-asynclocalstorage-run-request-context

What is the smallest fixture that still proves modal containment and focus movement in a native dialog?

Chris Rodriguez — Fri, 09 Oct 2026 20:55:03 +0000

A timeout is not always a focus leak

A native dialog can make the background inert without immediately wrapping every boundary Tab press between its first and last controls. Browser controls can participate in navigation. Test the page-level invariant directly, and keep positive assertions for movement between internal controls.

Small runnable fixture

Save this as main.mjs:

export const html = `<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>Native dialog focus fixture</title>
  </head>
  <body>
    <button id="background">Background action</button>
    <button id="opener">Open dialog</button>
    <dialog id="dlg" aria-labelledby="dialog-title">
      <h2 id="dialog-title">Example settings</h2>
      <form method="dialog">
        <button id="close" autofocus>Close</button>
      </form>
      <label for="in1">Display name</label>
      <input id="in1">
      <button id="in2">Another action</button>
    </dialog>
    <script>
      const dialog = document.getElementById('dlg');
      const opener = document.getElementById('opener');
      opener.addEventListener('click', () => dialog.showModal());
      // Native restoration handles a connected opener; the app owns this fallback.
      dialog.addEventListener('close', () => {
        if (!opener.isConnected) document.getElementById('background').focus();
      });
    </script>
  </body>
</html>`;

Close, the input, and the final button are three internal keyboard stops. Count Close when predicting the order. The accessible name and input label make the fixture understandable, but their presence is not a full accessibility audit.

What to verify

Open with Enter and check :modal and the declared autofocus target. Verify Tab moves Close to input to final button, and reverse navigation moves back through those controls. At the boundaries, exclude both the opener and the background button rather than requiring an immediate wrap. Challenge inertness with programmatic focus attempts too.

A separate show() case must allow background focus. That negative control exposes a background button that was accidentally unfocusable for some unrelated reason. Test both Escape and the Close button returning to a connected opener. When the opener is removed, wait for the application close listener to focus its explicit fallback; open=false alone is too early to establish that asynchronous result.

Reproduce and interpret

Use Node 22, npm init -y, npm install --save-dev playwright@1.63.0, and npx playwright install chromium. The full article supplies main.test.mjs; run node --test main.test.mjs. Tests load local HTML, block network requests, and close each browser in finally.

A Chromium result is not cross-browser or screen-reader certification. Keep the browser version with the evidence, and investigate assertion failures separately from installation errors.

Full test file and limitations: https://chriseugenerodriguez.com/blog/smallest-modal-focus-fixture

Why tests should verify runtime contracts, not inferred types

Chris Rodriguez — Thu, 08 Oct 2026 19:40:04 +0000

If your Node tests are green but callers still need casts, you’re mixing two different guarantees. A Node test proves what the function did when executed: the values returned, whether the input was mutated, and which inputs throw. It does not and cannot prove how the TypeScript compiler will narrow that result at a later use site.

Implementation summary

Keep the runtime contract explicit: the helper should validate inputs (e.g., reject non-arrays) and return a new array that removes only null and undefined (use a nullish check rather than truthiness). The server-inserted example shows a small function that performs exactly that behavior and does not mutate the input.

Expected behavior to test

Mixed-array case: the output contains the original non-nullish items in order and preserves falsy-but-valid values like 0, '', and false.
Empty input: returns a new empty array (not the same reference).
All-nullish input: returns an empty array.
Invalid input: throws a TypeError for non-array arguments.

Where static checking belongs

If you need the helper to provide compiler-level narrowing (so consumers can assign without casts), verify that with the TypeScript compiler or editor diagnostics. A minimal compile-time check is to write a small use-site that only accepts the narrowed type and run tsc to ensure it typechecks.

Limitations and pitfalls

Compiler inference changes across TypeScript versions (e.g., TypeScript 5.5 adds inferred predicates in some filter callbacks). Relying on runtime tests to encode compiler behavior makes tests brittle or misleading.
Truthiness-based filters (e.g., !!x) can silently drop legitimate falsy values — runtime tests must check exact outputs, not just lengths.

Practical rule

Tests: prove the runtime contract you actually depend on. Compiler: prove the static narrowing your consumers rely on. Keep them separate so failures point to the right fix: change JS behavior, adjust types, or update consumers.

The article includes a repaired example and concrete test cases that illustrate this split and avoid overclaiming what a JavaScript test can prove. The server will append the full code example and the article URL.

Working example

export const note = `This module demonstrates runtime removal of null and undefined from arrays.
Runtime tests (node:test) validate behavior at execution time but do NOT prove any TypeScript compile-time narrowing. To check static narrowing you must run the TypeScript compiler (tsc) or use editor/IDE type checks.`;

/**
 * Remove null and undefined from an array while preserving order and other falsy
 * values such as 0, '', and false.
 *
 * Runtime contract: returns a new array containing only elements that are not
 * null and not undefined. Throws a TypeError if the argument is not an Array.
 *
 * Note: This demonstrates runtime behavior only. TypeScript's ability to
 * narrow types (e.g. from (T | null | undefined)[] to T[]) is a compile-time
 * property checked by tsc / the language service and is not proven by these
 * runtime tests.
 */
export function filterNonNullish(arr) {
  if (!Array.isArray(arr)) {
    throw new TypeError('filterNonNullish expects an Array');
  }

  return arr.filter((x) => x != null);
}

Read the full article: https://chriseugenerodriguez.com/blog/tests-should-verify-runtime-contract-not-inferred-types

Model cancelled tool runs as preserved outcomes (commit:false + meta.kind:'cancelled')

Chris Rodriguez — Wed, 07 Oct 2026 19:25:04 +0000

Problem

When your app treats cancelled model/tool runs like generic failures, you risk wiping the last good UI: clearing screens, flipping loading flags incorrectly, or showing an alarming error banner for a user-initiated stop. That typically happens when non-ok outcomes are collapsed into one failure path.

Implementation (high level)

Use a small state-policy reducer that returns two orthogonal things: a commit boolean and a meta.kind describing the outcome. Map status values to behavior:

ok → commit: true, merge payload into state, meta.kind: 'ok'
cancelled → commit: false, preserve prevState, meta.kind: 'cancelled'
error → commit: false, preserve prevState, meta.kind: 'error'

Expected behavior

When a tool returns cancelled, the reducer explicitly refuses to commit changes and preserves the prior state. The UI can render a benign cancellation notice tied to meta.kind: 'cancelled' without implying the screen is broken. If the tool returns error, the UI surfaces an actionable failure. For ok, the UI adopts the payload.

Why this matters

Returning an explicit commit flag keeps the data-flow decision in the policy layer and out of the render layer. No-op commits (creating a new state object with the same values) or inferring behavior from messages forces the presentation layer to guess ownership, which can trigger rerenders, reset attached metadata, or hide the distinction between harmless stops and real failures.

Limitations

The example’s merge strategy is intentionally small (a shallow merge) and not a recommendation for nested stores, normalized caches, or immutable collections. This pattern does not address abort propagation, request ownership across multiple layers, stale responses, idempotency, or conflicting writes; those require additional orchestration. Also, if your orchestration layer collapses cancellation and error before the reducer sees them, preserve the distinction earlier in the stack.

Read the full article to see the reducer and tests that assert preserved state on cancellation and the boundaries this pattern does — and does not — cover.

Section IDs referenced:

why-cancellation-needs-its-own-outcome
how-the-tool-loop-creates-the-misclassification-risk
what-the-example-actually-guarantees
why-an-incomplete-fix-fails
what-the-tests-prove-and-do-not-prove
where-this-pattern-stops-being-enough

Working example

export function applyToolResult(prevState, toolResult) {
  // toolResult is expected to be one of:
  // { status: 'ok', payload: any }
  // { status: 'cancelled', reason?: string }
  // { status: 'error', error: any }
  // The function returns an object describing whether to commit the tool's
  // changes into the UI state and metadata to drive UI behavior.

  if (!toolResult || typeof toolResult !== 'object') {
    return {
      commit: false,
      state: prevState,
      meta: { kind: 'invalid_tool_result', message: 'Tool returned non-object' },
    };
  }

  switch (toolResult.status) {
    case 'ok':
      // Successful tool run: commit new state derived from payload.
      // For the example, we shallow-merge payload into prevState.
      return {
        commit: true,
        state: { ...prevState, ...(toolResult.payload || {}) },
        meta: { kind: 'ok' },
      };

    case 'cancelled':
      // Cancellation is not a UI-side error. We deliberately do NOT commit
      // changes and we surface a cancellation marker so the UI can preserve
      // prior state and optionally show a benign message.
      return {
        commit: false,
        state: prevState,
        meta: { kind: 'cancelled', reason: toolResult.reason ?? null },
      };

    case 'error':
      // Real tool error -- treat as actionable failure. Do not commit and
      // mark meta for UI error handling. (Different from cancellation.)
      return {
        commit: false,
        state: prevState,
        meta: { kind: 'error', error: toolResult.error ?? 'unknown' },
      };

    default:
      return {
        commit: false,
        state: prevState,
        meta: { kind: 'unknown_status', status: toolResult.status },
      };
  }
}

Read the full article: https://chriseugenerodriguez.com/blog/cancellation-from-a-tool-should-not-be-treated-as-a-ui-side-error