DEV Community: Chris Rodriguez

Design accessible form success states: status, navigation, Undo, and confirmation

Chris Rodriguez — Sat, 14 Nov 2026 21:55:04 +0000

Successful submission is a distinct UI state

A completed form needs to answer two questions: did the action finish, and can the user recover if it was accidental? Treating success as an error-summary variant or relying on a visual toast makes those answers harder to discover.

Start by choosing the announcement channel from the page transition.

If submission navigates to a new page or a clearly different view, put the result in the new document context: update the page title and expose a clear main heading such as “Task submitted.” This makes the destination state explicit rather than leaving the user to infer success from a changed screen.

If submission remains on the same page, keep the user in context and return a concise status message. The message should say what completed, not repeat a long explanation. The inserted example models this as a dedicated status result, separate from validation output.

Keep recovery and validation honest

Validation failures need a correction path: field errors identify what must change before submission can continue. They are not success feedback, and a successful result should not be inferred merely because an error summary is absent. Model these as separate states so the rendering layer cannot accidentally present success through an error pattern.

Next, choose the safeguard based on reversibility. For reversible work, return an Undo control after success and restore the prior item when the user activates it. Once restoration has happened, Undo should no longer be available. For permanent or otherwise critical work, do not offer a recovery promise that the system cannot keep. Require confirmation before committing the action instead.

Expected behavior is straightforward: a valid reversible submission produces a completion announcement and Undo; a page-style completion produces a title and heading instead of an in-place status; invalid input produces validation feedback; irreversible work pauses for confirmation and exposes no Undo control.

One important limitation remains: this flow can model the semantic contract, but it cannot prove the exact announcement order or behavior of every browser and assistive-technology combination. Verify the rendered markup and interaction in the environments you support.

Working example

export const proofBoundary =
  'This model verifies the flow’s presentation contract. It does not prove how a particular browser or assistive technology announces a live region, title, or heading.';

function successPresentation(presentation, task) {
  const message = `Task “${task}” submitted successfully.`;

  if (presentation === 'page') {
    return {
      title: `Task submitted – Task manager`,
      heading: 'Task submitted',
      status: null,
      message,
    };
  }

  return {
    title: null,
    heading: null,
    status: { role: 'status', text: message },
    message,
  };
}

/**
 * Models a form submission UI. A real page can render `title` and `heading`
 * after navigation, or render the `status` live region after an in-page submit.
 */
export function createTaskFormFlow({ presentation = 'status', reversible = true } = {}) {
  if (!['status', 'page'].includes(presentation)) {
    throw new RangeError('presentation must be "status" or "page"');
  }

  let pendingSubmission = null;

  return {
    submit({ task, confirmed = false } = {}) {
      const normalizedTask = typeof task === 'string' ? task.trim() : '';

      if (!normalizedTask) {
        return {
          ok: false,
          kind: 'validation',
          fieldErrors: { task: 'Enter a task.' },
          // Success is not represented as a server-style error summary.
          errorSummary: null,
        };
      }

      if (!reversible && !confirmed) {
        return {
          ok: false,
          kind: 'confirmation-required',
          message: 'Confirm this permanent submission before continuing.',
        };
      }

      pendingSubmission = { task: normalizedTask };
      const feedback = successPresentation(presentation, normalizedTask);

      return {
        ok: true,
        kind: 'submitted',
        ...feedback,
        undoControl: reversible
          ? { action: 'undo', label: 'Undo submission', accessibleName: 'Undo submission' }
          : null,
      };
    },

    undo() {
      if (!reversible || pendingSubmission === null) {
        return {
          ok: false,
          kind: 'undo-unavailable',
          status: null,
        };
      }

      const { task } = pendingSubmission;
      pendingSubmission = null;
      return {
        ok: true,
        kind: 'undone',
        restoredTask: task,
        status: { role: 'status', text: `Submission of “${task}” was undone.` },
      };
    },
  };
}

Read the full article: https://chriseugenerodriguez.com/blog/successful-form-submission-undo-accessibly

Build dashboard card grids that reduce columns before cards get cramped

Chris Rodriguez — Sat, 14 Nov 2026 00:10:03 +0000

Responsive dashboard grids should usually change their column count before their cards become too narrow. A fixed track list, such as four fractional columns, keeps four columns even when the container no longer has room for four readable cards. The result is cramped content or horizontal overflow.

The implementation uses a repeating Grid track definition with auto-fit and a minimum-to-flexible range. The minimum is 180px, which represents the narrowest acceptable card in this fixture. The flexible maximum allows the tracks that remain on a row to share leftover space evenly.

The important decision is to put the readability threshold in the grid’s track sizing rule. auto-fit asks the browser to create as many tracks as fit. When another minimum-width track plus its gap no longer fits, Grid reduces the number of columns and reflows the same cards into another row. No card-specific breakpoint is needed for that transition.

With six cards, a wide container can resolve to four columns and two rows. At a middle width, it can resolve to two columns and three rows. At the narrow boundary, two 180px tracks and the gap fit at 376px but not at 375px, so the layout becomes one column. The markup and card count stay the same; only the track count changes.

Choose the minimum from the card’s real content, not from a generic device breakpoint. Short labels and values may work in a narrower card than summaries with supporting text, controls, or long localized labels.

This pattern solves an outer-layout problem. It does not make an unbreakable string, an oversized control, or poorly designed card internals shrink correctly. Those need their own content and overflow rules. It is also not the best fit for a strict comparison matrix or table where column alignment must remain fixed across rows.

Use this approach when cards are independent units that can move between rows without changing meaning. It keeps the responsive decision alongside the Grid sizing rule and lets available inline space, rather than a guessed viewport breakpoint, determine when a column disappears.

Working example

export const MIN_CARD_WIDTH = 180;

const defaultCards = [
  'Revenue',
  'Active users',
  'Open tickets',
  'Conversion',
  'Deployments',
  'Uptime',
];

function escapeHtml(value) {
  return String(value)
    .replaceAll('&', '&amp;')
    .replaceAll('<', '&lt;')
    .replaceAll('>', '&gt;')
    .replaceAll('"', '&quot;')
    .replaceAll("'", '&#39;');
}

export function dashboardHtml(cards = defaultCards) {
  const cardMarkup = cards
    .map(
      (title, index) => `
        <article class="card" data-card="${index}">
          <h2>${escapeHtml(title)}</h2>
          <p>Dashboard metric ${index + 1}</p>
        </article>`,
    )
    .join('');

  return `<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <style>
      * { box-sizing: border-box; }
      html, body { margin: 0; }
      body {
        font-family: system-ui, sans-serif;
        background: #e2e8f0;
      }
      .dashboard {
        display: grid;
        grid-template-columns: repeat(auto-fit, minmax(${MIN_CARD_WIDTH}px, 1fr));
        gap: 16px;
        width: 100%;
      }
      .card {
        min-height: 72px;
        padding: 12px;
        border: 1px solid #94a3b8;
        border-radius: 8px;
        background: white;
      }
      h2 { margin: 0; font: 600 16px system-ui, sans-serif; }
      p { margin: 8px 0 0; font: 14px system-ui, sans-serif; }
    </style>
  </head>
  <body>
    <main class="dashboard" aria-label="Dashboard cards">${cardMarkup}</main>
  </body>
</html>`;
}

Read the full article: https://chriseugenerodriguez.com/blog/grid-auto-fit-minmax-dashboard

Reuse a Cached App Shell Without Blurring Query-Driven Responses

Chris Rodriguez — Thu, 12 Nov 2026 23:25:03 +0000

A cached app shell may fail to load offline when a navigation adds a tracking or cosmetic query parameter. A request for /app and one for /app?utm_source=newsletter are different URLs under default cache matching, even when both should receive the same shell document.

The safe fix is route-scoped rather than global. First classify the request: allow only GET requests for a canonical shell path such as /app. For that one lane, use a cache lookup that ignores the URL search component. The cached shell can then satisfy navigations with campaign tags or other parameters that do not alter the shell response. The request still carries its full URL; only cache comparison changes.

Leave every other request on exact matching. API endpoints, searches, filtered results, user profiles, reports, and locale-specific content often use query parameters to select the response. In those cases, ignoring search could make one request receive a response intended for another query. Non-GET requests should bypass this shell-cache policy and continue to the network.

Expected behavior is intentionally limited. Two shell navigations with harmlessly different query strings can use one cached shell entry. If that entry is absent, the request falls back to the network. A query-sensitive request remains keyed by its complete URL and cannot select another query’s cached response.

Keep the decision function separate from service-worker event wiring. A controlled fixture can verify that application code selects the intended lookup option, preserves exact matching elsewhere, and bypasses non-GET requests. It cannot prove browser Cache API behavior, secure-context requirements, or the service-worker lifecycle; those require browser integration verification.

Ignoring search does not normalize different paths, reorder parameters, or establish a caching strategy for every route. Use it only where the path identifies a reusable shell and the search string does not change what that response means.

Working example

// This module contains no service-worker side effects on import.
// Proof boundary: the route selection below is application code. A real browser
// service worker is still required to prove Cache.match()'s own cache semantics.

export const APP_SHELL_PATH = "/app";

export function isAppShellRequest(request) {
  const url = new URL(request.url);
  return request.method === "GET" && url.pathname === APP_SHELL_PATH;
}

/**
 * Handles an already-intercepted service-worker fetch request.
 *
 * Only GET requests are eligible for cache lookup. Within that set, only the
 * chosen app-shell route ignores its query string; API endpoints and other
 * query-driven routes use Cache.match()'s default exact matching.
 */
export async function handleAppShellFetch(request, { cache, networkFetch }) {
  // Cache.match() normally only matches GET and HEAD requests, but this policy
  // intentionally does not involve the cache for any non-GET operation.
  if (request.method !== "GET") {
    return networkFetch(request);
  }

  const cached = isAppShellRequest(request)
    ? await cache.match(request, { ignoreSearch: true })
    : await cache.match(request);

  return cached ?? networkFetch(request);
}

/**
 * Optional service-worker wiring. Call this from the service-worker script
 * after opening the intended Cache instance.
 */
export function registerAppShellFetchHandler(scope, dependencies) {
  scope.addEventListener("fetch", (event) => {
    event.respondWith(handleAppShellFetch(event.request, dependencies));
  });
}

Read the full article: https://chriseugenerodriguez.com/blog/cache-match-ignore-search-app-shell

Restart a dependent Compose app after an explicit backend restart

Chris Rodriguez — Thu, 12 Nov 2026 00:40:04 +0000

A Compose stack can be correct at startup yet become stale after maintenance. If an operator deliberately restarts a backend, the dependent app may continue running with an old socket, connection pool, cached credential, or other backend-facing process state. More startup delays do not address that later lifecycle event.

The implementation decision is to place restart propagation on the dependency edge. Configure the app with long-form depends_on for its backend and enable the dependency restart option there. Keep that setting separate from each service’s restart policy. A policy such as always or unless-stopped controls whether a service returns after its own container exits; it does not tell Compose to restart downstream services when a backend is intentionally restarted.

The inserted example models a backend and an app, then validates two pieces of declared intent: the requested operation is an explicit Compose restart of an existing dependency, and at least one dependent opts into restart propagation. It also rejects the common but incomplete configuration where both services have restart policies but the dependency relationship has no propagation setting.

Expected behavior is deliberately narrow. When Compose explicitly restarts the backend, it can restart the dependent app so the app gets a fresh process and can recreate backend-facing state. If the application also needs to wait for real readiness on first boot, configure a health-based startup condition independently. Readiness answers when an app may begin; restart propagation answers what follows a later operator action.

There is an important limitation: this is not a crash cascade. A backend that exits and is restarted automatically by the container runtime is not the same as an explicit Compose-managed restart. The rule also cannot be assumed when containers are restarted directly or by another tool. Coordinated restarts are useful when needed, but resilient reconnect behavior inside the application remains the stronger long-term defense.

The example validates configuration and command intent only. Observing actual container lifecycle behavior requires a real Docker Compose engine.

Working example

export function buildBackendAppCompose() {
  return {
    services: {
      backend: {
        image: 'example/backend:1',
        restart: 'unless-stopped',
      },
      app: {
        image: 'example/app:1',
        restart: 'unless-stopped',
        depends_on: {
          backend: {
            condition: 'service_started',
            restart: true,
          },
        },
      },
    },
  };
}

/**
 * Validates the configuration and operation needed for Compose's documented
 * dependency-restart feature. This is a configuration check only: it does not
 * invoke Docker or prove that a live Compose engine restarted a container.
 */
export function validateExplicitDependencyRestart(compose, command) {
  if (!compose || typeof compose !== 'object' || !compose.services) {
    throw new TypeError('compose.services is required');
  }

  if (!Array.isArray(command) || command.length !== 4) {
    throw new TypeError('command must be: docker compose restart <dependency>');
  }

  const [docker, composeCommand, restart, dependency] = command;
  if (docker !== 'docker' || composeCommand !== 'compose' || restart !== 'restart') {
    throw new TypeError('command must be: docker compose restart <dependency>');
  }

  if (!compose.services[dependency]) {
    throw new RangeError(`dependency service "${dependency}" does not exist`);
  }

  const dependents = Object.entries(compose.services)
    .filter(([, service]) => service.depends_on?.[dependency]?.restart === true)
    .map(([name]) => name);

  if (dependents.length === 0) {
    throw new Error(
      `No service declares depends_on.${dependency}.restart: true; a container restart policy alone does not configure dependency restart propagation`,
    );
  }

  return {
    operation: 'explicit-compose-restart',
    dependency,
    dependents,
    proofBoundary:
      'This validates declared Compose configuration only. Run Docker Compose against a real engine to observe container restarts.',
  };
}

Read the full article: https://chriseugenerodriguez.com/blog/restart-compose-app-when-dependency-restarted

Use @layer + low-specificity selectors so site overrides don’t turn into selector wars

Chris Rodriguez — Wed, 11 Nov 2026 00:10:06 +0000

Problem

Component libraries simplify UI work—until their styles start winning every time. Product tweaks become an arms race: nested selectors, extra classes, and the occasional !important to force a visual change. That creates brittle overrides and long-term maintenance pain.

Implementation (what to do)

1) Declare a stable @layer order and keep it explicit in your imports or build. Make sure the library layer is declared earlier and the site (product) layer declared later.
2) Wrap or import third-party library CSS into the earlier layer. Keep product/theme overrides and page-specific rules in the later layer.
3) When authoring site rules, prefer short, descriptive selectors (type, single class) or use :where() to scope matches without increasing specificity.

Expected behavior

For normal (non-!important) declarations, layer precedence is evaluated before selector specificity. That means a low-specificity selector in the later site layer can override a more-specific selector in the earlier library layer. The result: concise site overrides that don’t require escalating selector strength and clearer ownership in code.

What the included fixture proves

The article ships a minimal cascade evaluator plus tests demonstrating three points: (1) a site rule in a later layer wins even if the library selector is more specific; (2) :where() matches without adding specificity so site selectors stay easy to override later; (3) tests can assert selector specificity to detect accidental increases that would make future maintenance harder.

Limitations

Layers make ownership legible but don’t enforce it: teams must still agree which styles belong to the library versus the site. The included evaluator is intentionally simplified to demonstrate the migration contract; it does not replicate every browser quirk and should not replace cross-browser verification.

Why this is useful

The approach is incremental: wrap existing library CSS into a layer and migrate site overrides into the later layer gradually. Add a small test that asserts both the visual winner and the selector specificity to prevent silent drift back into selector wars. The article contains a compact, testable evaluator and concrete test cases you can adopt as guardrails during refactors.

(The server will append the verified implementation example below.)

Working example

// Minimal CSS cascade evaluator focused on demonstrating @layer ordering and specificity
// Exports a pure function evaluateCascade(rules, element) with no side effects.
// rules: array of {layer: string, selector: string, declarations: {prop: value}}. The order of first appearance of layer names
// determines layer precedence: later-declared layers win over earlier ones for normal (non-!important) declarations.
// element: {tag: 'div', id: 'x', classes: ['a','b']}

function normalizeLayerOrder(rules) {
  // Determine first-seen order of layers
  const order = new Map();
  let idx = 0;
  for (const r of rules) {
    if (!order.has(r.layer)) order.set(r.layer, idx++);
  }
  return order; // map layer -> index (lower = declared earlier = lower precedence)
}

function splitCompound(compound) {
  // Split a compound like "div.btn#id" into tokens: ['div', '.btn', '#id']
  return compound.split(/(?=[.#])/g).filter(Boolean);
}

function matchesSelector(selector, element) {
  // Support simple selectors used in examples: tag, .class, #id, and :where(...)
  selector = selector.trim();
  // If selector contains descendant spaces (e.g. '.toolbar .btn'), the evaluator used in tests
  // models only the target element, not the ancestor chain. To match the intent of the tests,
  // consider a selector with spaces to match if its last compound (the rightmost sequence)
  // matches the element. This preserves counting of specificity across the full selector.

  // handle top-level :where() wrappers by delegating to inner selector for matching
  if (selector.startsWith(':where(') && selector.endsWith(')')) {
    const inner = selector.slice(7, -1).trim();
    return matchesSelector(inner, element);
  }

  // Split by whitespace to tokens (descendant combinator); we match only against the last token
  const tokens = selector.split(/\s+/).filter(Boolean);
  const last = tokens[tokens.length - 1];
  // If last is a :where() wrapper, test its inner selector(s)
  if (last.startsWith(':where(') && last.endsWith(')')) {
    const inner = last.slice(7, -1).trim();
    // inner may be a selector list, but tests use simple cases, so just test inner against element
    return matchesSelector(inner, element);
  }

  const parts = splitCompound(last);
  // first part might be tag (no prefix)
  let idx = 0;
  if (parts[0] && !parts[0].startsWith('.') && !parts[0].startsWith('#')) {
    const tag = parts[0].toLowerCase();
    if (element.tag && element.tag.toLowerCase() !== tag) return false;
    idx = 1;
  }
  for (; idx < parts.length; idx++) {
    const p = parts[idx];
    if (p.startsWith('.')) {
      const cls = p.slice(1);
      if (!element.classes || !element.classes.includes(cls)) return false;
    } else if (p.startsWith('#')) {
      const id = p.slice(1);
      if (!element.id || element.id !== id) return false;
    } else {
      // unsupported token, be conservative and return false
      return false;
    }
  }
  return true;
}

function specificityOf(selector) {
  // Return tuple [a,b,c] following MDN: a = #ids, b = classes/attrs/pseudo-classes, c = type/pseudo-elements
  selector = selector.trim();
  // We must account for selectors with descendant combinators and :where() which contributes 0
  let a = 0, b = 0, c = 0;
  const tokens = selector.split(/\s+/).filter(Boolean);
  for (const token of tokens) {
    // If token is :where(...), its parameters do NOT add specificity. Still, those parameters
    // are used for matching; here we intentionally skip adding any specificity for :where.
    if (token.startsWith(':where(') && token.endsWith(')')) {
      // skip adding specificity for :where(...) entirely
      continue;
    }
    // For other tokens, break into compound parts like "div.btn#id"
    const parts = splitCompound(token);
    if (parts[0] && !parts[0].startsWith('.') && !parts[0].startsWith('#')) {
      // type selector
      c += 1;
    }
    for (const p of parts) {
      if (p.startsWith('#')) a += 1;
      else if (p.startsWith('.')) b += 1;
      // else it's a type already counted
    }
  }
  return [a, b, c];
}

function compareSpecificity(s1, s2) {
  for (let i = 0; i < 3; i++) {
    if (s1[i] > s2[i]) return 1;
    if (s1[i] < s2[i]) return -1;
  }
  return 0;
}

function evaluateCascade(rules, element) {
  // rules is an array where layer names' declaration order is the order of appearance.
  // For simplicity we only evaluate a single property key at a time in examples; here we return a map prop->value
  const layerOrder = normalizeLayerOrder(rules);
  // for each rule that matches the element, consider each declaration
  const wins = new Map(); // prop -> {value, layerIndex, specificity, ruleIndex}
  rules.forEach((r, idx) => {
    if (!matchesSelector(r.selector, element)) return;
    const layerIndex = layerOrder.get(r.layer);
    for (const [prop, value] of Object.entries(r.declarations)) {
      const spec = specificityOf(r.selector);
      const existing = wins.get(prop);
      if (!existing) {
        wins.set(prop, {value, layerIndex, specificity: spec, ruleIndex: idx});
        continue;
      }
      // Compare by layer precedence (higher layerIndex wins). If same layer index, compare specificity.
      if (layerIndex > existing.layerIndex) {
        wins.set(prop, {value, layerIndex, specificity: spec, ruleIndex: idx});
      } else if (layerIndex < existing.layerIndex) {
        // losing by layer order -> ignore
      } else {
        // same layer: compare specificity
        const cmp = compareSpecificity(spec, existing.specificity);
        if (cmp > 0) {
          wins.set(prop, {value, layerIndex, specificity: spec, ruleIndex: idx});
        } else if (cmp === 0) {
          // same specificity: later rule (higher ruleIndex) wins
          if (idx > existing.ruleIndex) {
            wins.set(prop, {value, layerIndex, specificity: spec, ruleIndex: idx});
          }
        }
      }
    }
  });
  // return plain object of properties to values
  const out = {};
  for (const [k, v] of wins.entries()) out[k] = v.value;
  return out;
}

export { evaluateCascade, matchesSelector, specificityOf };

Read the full article: https://chriseugenerodriguez.com/blog/layered-library-overrides

Designing stable pagination in PostgreSQL

Chris Rodriguez — Mon, 09 Nov 2026 23:40:17 +0000

Problem: a user navigates a paginated list and finds items moved between pages after concurrent inserts or deletes. That surprising behavior usually stems from underspecified ordering in the query.

Implementation summary (no code here — server injects the verified example):

Always define a complete ORDER BY. Use your primary business column (for example created_at DESC) and add a unique tie-breaker (usually the primary key) so each row has a deterministic position.
If users need numbered-page random access and the dataset is small or rarely changing, OFFSET + LIMIT with a deterministic ORDER BY is acceptable.
If rows are inserted or removed frequently and users browse forward/backward from the newest items, use keyset (seek) pagination. The client stores the last-seen row values (the cursor) and requests the next block after that anchor.

Expected behavior:

Deterministic ORDER BY guarantees the same logical ordering every time the same snapshot of data is queried. That prevents inconsistent tie-breaking across planner or scan variations.
OFFSET counts positions. When items are inserted ahead of an offset, later pages shift and can show duplicates or gaps.
Keyset pagination anchors on real row values, so continuing from a cursor returns the next items after that anchor even if new items were added before it.

Limitations and tradeoffs:

Keyset pagination does not support arbitrary “go to page N” navigation easily. It’s designed for sequential traversal.
OFFSET with large offsets is inefficient because the database still computes and discards the skipped rows; it’s also fragile for changing lists.
You must include the same columns in the cursor that define the ORDER BY; otherwise the continuation point won’t match the ordering.

Use this rule-of-thumb for team docs: never paginate without ORDER BY; always add a unique tie-breaker when equal values are possible; treat OFFSET as positional convenience, not a stability guarantee; prefer keyset when row churn would make page numbers misleading.

(The server will append the canonical article link and insert the verified example implementation.)

Working example

// main.mjs
// Provides small, pure functions that demonstrate LIMIT/ORDER BY behavior for pagination
// Works on in-memory arrays of {id: number|string, created_at: ISOString, ...}
// No side effects on import.

// Sort helper: accepts an array of sort specifiers like [{key:'created_at', dir:'desc'}, {key:'id','dir':'asc'}]
// If no tie-breaker provided, the sort only uses the provided keys.
export function sortRows(rows, orderSpecs = [{key: 'created_at', dir: 'desc'}]) {
  const cmp = (a, b) => {
    for (const spec of orderSpecs) {
      const {key, dir = 'asc'} = spec;
      const av = a[key];
      const bv = b[key];
      if (av === bv) continue;
      // handle ISO date strings naturally by string comparison (ISO sorts chronologically)
      if (av == null) return dir === 'asc' ? -1 : 1;
      if (bv == null) return dir === 'asc' ? 1 : -1;
      if (av < bv) return dir === 'asc' ? -1 : 1;
      return dir === 'asc' ? 1 : -1;
    }
    return 0; // equal on all provided keys
  };
  // slice to avoid mutating input
  return rows.slice().sort(cmp);
}

// OFFSET + LIMIT pagination: mimic SQL's ORDER BY ... LIMIT ... OFFSET ...
// rows: array, orderSpecs: as above, limit: number, offset: number
export function paginateOffset(rows, orderSpecs, limit, offset) {
  if (!Number.isInteger(limit) || limit < 0) throw new TypeError('limit must be non-negative integer');
  if (!Number.isInteger(offset) || offset < 0) throw new TypeError('offset must be non-negative integer');
  const sorted = sortRows(rows, orderSpecs);
  return sorted.slice(offset, offset + limit);
}

// Keyset (seek) pagination: return the first `limit` rows strictly before/after a cursor value
// direction: 'after' for newer -> older navigation with created_at DESC; 'before' for the reverse
// cursor is an object with the same keys as the leading orderSpecs, e.g. {created_at: '2026-01-01T00:00:00Z', id: 42}
// This function assumes orderSpecs is non-empty and that cursor provides values for the leading keys.
// It returns {rows: [...], nextCursor: {...}|null}
export function paginateKeyset(rows, orderSpecs, limit, cursor = null, direction = 'after') {
  if (!orderSpecs || orderSpecs.length === 0) throw new TypeError('orderSpecs must be provided');
  if (!Number.isInteger(limit) || limit <= 0) throw new TypeError('limit must be positive integer');
  // Build comparator for orderSpecs so we can test row vs cursor
  const compareRowToCursor = (row, cur) => {
    for (const spec of orderSpecs) {
      const key = spec.key;
      const dir = spec.dir || 'asc';
      const rv = row[key];
      const cv = cur[key];
      if (rv === cv) continue;
      if (rv == null) return dir === 'asc' ? -1 : 1;
      if (cv == null) return dir === 'asc' ? 1 : -1;
      if (rv < cv) return dir === 'asc' ? -1 : 1;
      return dir === 'asc' ? 1 : -1;
    }
    return 0;
  };

  // For keyset, we must sort the whole set in the same ORDER BY direction
  const sorted = sortRows(rows, orderSpecs);

  let filtered;
  if (!cursor) {
    filtered = sorted;
  } else {
    if (direction === 'after') {
      // For 'after', we want rows that come after the cursor in the sorted array.
      // compareRowToCursor returns negative when row sorts before cursor, positive when after.
      filtered = sorted.filter(r => compareRowToCursor(r, cursor) > 0);
    } else {
      // 'before' -> rows that come before cursor
      filtered = sorted.filter(r => compareRowToCursor(r, cursor) < 0);
    }
  }

  const page = filtered.slice(0, limit);
  const nextCursor = page.length === 0 ? null : Object.fromEntries(orderSpecs.map(s => [s.key, page[page.length - 1][s.key]]));
  return {rows: page, nextCursor};
}

Read the full article: https://chriseugenerodriguez.com/blog/stable-postgresql-pagination

Pick secrets by lifetime: Docker build mounts for builds, Compose files for runtime

Chris Rodriguez — Sun, 08 Nov 2026 01:25:08 +0000

Problem summarized

Docker offers multiple ways to supply credentials during CI, image build, and runtime. The labels overlap — "secrets", "args", "env" — but the correct choice depends on the lifetime you intend for the credential, not convenience.

Implementation overview

1) Build-time needs: Use docker build --secret (RUN --mount=type=secret) for temporary credentials and --ssh (RUN --mount=type=ssh) for SSH agent/socket access. These mounts are scoped to the instruction that uses them and are not meant to persist in resulting image layers or configuration.

2) Runtime needs: Use Docker Compose secrets. Define the secret at the Compose file top level, grant it only to the service that needs it, and read the file from /run/secrets/ inside the container. This keeps the secret out of image content and out of broad environment-variable exposure.

3) Don’t use ARG or ENV for secrets you expect to keep out of images. Build args and ENV become part of image history or config and are the usual cause of accidental leakage.

Expected behavior

A build using --secret or --ssh should complete without leaving the secret string in image history or image configuration when the Dockerfile and builder follow the documented pattern.
A Compose service that declares a secret should receive the secret as a mounted file at /run/secrets/. Services that don’t list the secret will not receive it.

Verification and limits

Always inspect the resulting image with docker history and docker image inspect to ensure the secret text is not present in command history or environment values.
These Docker mechanisms ensure Docker itself does not bake secrets into images, but they do not prevent your application from leaking values at runtime (logging, copying files, exposing via debug endpoints). Application-level handling remains your responsibility.

Why this choice matters

The decision is small but strict: choose the mechanism that matches the credential lifetime. Splitting responsibilities when a credential is needed both at build and at runtime avoids forcing one API to do both jobs and reduces accidental persistence.

(Verified implementation example inserted by the server.)

Working example

export function chooseDockerSecretMechanism({ needsDuringBuild, needsDuringRuntime, credentialType = 'file' } = {}) {
  if (needsDuringBuild && needsDuringRuntime) {
    return {
      recommendation: 'split',
      reason: 'Use a build secret or SSH mount during image construction, and a Compose secret at runtime.',
    };
  }

  if (needsDuringBuild) {
    if (credentialType === 'ssh') {
      return {
        recommendation: 'build-ssh-mount',
        reason: 'SSH credentials used during a build should use --ssh and RUN --mount=type=ssh.',
      };
    }

    return {
      recommendation: 'build-secret',
      reason: 'Temporary build-time credentials should use --secret and RUN --mount=type=secret.',
    };
  }

  if (needsDuringRuntime) {
    return {
      recommendation: 'compose-secret',
      reason: 'A running container should read a file-backed secret mounted by Docker Compose at /run/secrets/<name>.',
    };
  }

  return {
    recommendation: 'plain-config',
    reason: 'If the value is not sensitive and is not needed for build or runtime secret access, use ordinary configuration instead.',
  };
}

export function classifyDockerfileLine(line) {
  const text = String(line).trim();

  if (/\bRUN\b.*--mount=type=secret\b/.test(text)) {
    return 'build-secret-mount';
  }
  if (/\bRUN\b.*--mount=type=ssh\b/.test(text)) {
    return 'build-ssh-mount';
  }
  if (/^\s*(ENV|ARG)\b/i.test(text) && /(TOKEN|PASSWORD|SECRET|KEY)/i.test(text)) {
    return 'persistent-secret-risk';
  }
  return 'other';
}

Read the full article: https://chriseugenerodriguez.com/blog/docker-build-vs-compose-secrets

How to keep server-side validation errors and screen readers in sync

Chris Rodriguez — Fri, 06 Nov 2026 23:10:13 +0000

When the server validates a form, the UX requirement is different from client-only validation: the server’s response is authoritative and may contain many errors. The pattern I recommend uses three cooperating pieces: a structured server payload, a page-level summary announced in a live region, and short inline messages attached to each control.

Implementation summary

Server payload: return an array of field errors in the shape { name: 'email', message: 'Enter a valid email.' } and a separate representation for non-field errors (quota, upstream failures). Avoid opaque banners like “Please fix the form.”
UI presentation: render a concise summary at the top (heading + list). Each summary item should reference the field label and link to the control. For each errored control, render a nearby message element with a deterministic id and set aria-describedby on the input so assistive tech reads the explanation when focus lands.
Focus policy: if there are field errors, focus the first errored control to place the user at the next editable target. If the server returns only non-field errors, announce the summary via a live region but do not move focus to a control. Avoid forcing focus when there’s nothing for the user to repair.

Expected behavior

Screen reader users hear the summary announcement (role=alert or similar) and can use the linked summary items to jump to specific controls.
When focus lands on an errored input, assistive tech reads the label plus the inline message supplied via aria-describedby, keeping context local to the edit.
If the user repairs one field locally, the UI clears only that field’s inline message while preserving other server errors. After the next submit, the server’s canonical list replaces the summary so stale errors do not accumulate.

Limitations and gotchas

Live-region noise: mixing frequent client-side validation with an always-alert summary can become noisy for screen reader users. Throttle or scope live announcements for incremental checks.
Server rewrites: if the server rewrites values on validation, the app must explain what changed and preserve the user’s editing context rather than silently replacing content.
Partial repair tests: your test plan should verify that repairing one field clears just that field’s message and that remaining errors persist until fixed.

This approach follows W3C guidance: treat server validation as structured data, present overview + detail, and keep focus movement purposeful so users—especially keyboard and screen reader users—keep their place while fixing the form.

Working example

// Exports a small, deterministic model of applying server-side validation results
// to an accessible form state. This is a pure, side-effect-free implementation
// suitable for unit testing. It is NOT a browser DOM manipulation library; it
// models the minimal pieces needed for accessibility decisions (ids, labels,
// inline messages, aria-describedby relationships, the summary, and focus
// recommendation).

// FormState: {
//   fields: { [id]: { id, name, label, value, errorId?: string, errorMessage?: string } },
//   prevFocusedId?: string // id that had focus before submit (optional)
// }
// Server error payloads are expected as arrays of:
// { name: <field name>, message: <string> } for field errors
// and/or { type: 'non-field', message: <string> } for global errors.

export function makeEmptyFormState(fields) {
  // fields: array of { id, name, label, value }
  const map = Object.fromEntries(fields.map(f => [f.id, { ...f }]));
  return { fields: map };
}

export function applyServerErrors(formState, serverErrors, options = {}) {
  // options:
  //  - focusFirstError: true|false (default true) : whether to set focus to the first field error
  //  - liveRegionRole: 'alert'|'polite' (default 'alert') : how summary should be announced
  // Returns new state object: { formState, summary, liveMessage, focusTargetId }

  const focusFirstError = options.focusFirstError !== false;
  const liveRegionRole = options.liveRegionRole || 'alert';

  // clone formState
  const fs = { fields: {} };
  for (const id of Object.keys(formState.fields)) {
    fs.fields[id] = { ...formState.fields[id] };
    // clear previous inline errors (server has new canonical list)
    delete fs.fields[id].errorMessage;
    delete fs.fields[id].errorId;
  }

  const fieldErrors = [];
  const nonFieldErrors = [];

  for (const e of serverErrors) {
    if (e && e.type === 'non-field') nonFieldErrors.push(e.message);
    else if (e && e.name && typeof e.message === 'string') fieldErrors.push(e);
    else if (e && !e.name && typeof e.message === 'string') nonFieldErrors.push(e.message);
    // ignore malformed entries silently (could be logged in real app)
  }

  // Map field errors to fields by name. If multiple errors target same name,
  // concatenate messages (server could choose first only, but concatenation is deterministic here).
  const byFieldName = {};
  for (const fe of fieldErrors) {
    (byFieldName[fe.name] = byFieldName[fe.name] || []).push(fe.message);
  }

  // Assign inline error ids and messages
  for (const id of Object.keys(fs.fields)) {
    const f = fs.fields[id];
    const msgs = byFieldName[f.name];
    if (msgs && msgs.length) {
      f.errorId = `${id}-error`; // deterministic id for aria-describedby
      f.errorMessage = msgs.join(' ');
    }
  }

  // Build summary: list of { fieldId?, message, linkId? }
  const summaryItems = [];
  // Field errors in document order (fields keys order)
  for (const id of Object.keys(fs.fields)) {
    const f = fs.fields[id];
    if (f.errorMessage) {
      summaryItems.push({ fieldId: id, message: `${f.label}: ${f.errorMessage}` });
    }
  }
  // Non-field errors appended
  for (const m of nonFieldErrors) summaryItems.push({ message: m });

  const summary = summaryItems.length
    ? { heading: 'There was a problem with your submission', items: summaryItems }
    : null;

  // Live region message: concise summary text (used for screen reader announcement)
  const liveMessage = summary ? `${summary.heading}. ${summary.items.length} problem(s)` : null;

  // Focus decision
  let focusTargetId = null;
  if (summary && focusFirstError) {
    // If there is at least one field error, focus first field with an error.
    const firstFieldError = summary.items.find(i => i.fieldId);
    if (firstFieldError) focusTargetId = firstFieldError.fieldId;
    else focusTargetId = null; // summary-only errors should not move focus to a form control
  } else if (summary && !focusFirstError) {
    focusTargetId = null; // policy: announce summary only (no focus jump)
  }

  // Attach aria-describedby linking: for each field with errorId, include that id in a
  // returned mapping so an applicator can set input.setAttribute('aria-describedby', errorId).
  const describedBy = {};
  for (const id of Object.keys(fs.fields)) {
    const f = fs.fields[id];
    if (f.errorId) describedBy[id] = f.errorId;
  }

  return {
    formState: fs,
    summary,
    liveRegion: summary ? { role: liveRegionRole, message: liveMessage } : null,
    focusTargetId,
    describedBy
  };
}

export function repairField(formState, fieldId, newValue) {
  // Simulates user repairing one field locally and clears its server error only.
  // Does NOT re-run server validation. Deterministic: remove errorMessage+errorId for that field.
  const fs = { fields: {} };
  for (const id of Object.keys(formState.fields)) {
    fs.fields[id] = { ...formState.fields[id] };
  }
  if (!fs.fields[fieldId]) throw new Error('unknown field id');
  fs.fields[fieldId].value = newValue;
  delete fs.fields[fieldId].errorMessage;
  delete fs.fields[fieldId].errorId;
  return fs;
}

Read the full article: https://chriseugenerodriguez.com/blog/server-side-validation-errors-screen-readers

Stale-while-revalidate with Cache.match(): fast answers, safe refreshes

Chris Rodriguez — Fri, 06 Nov 2026 12:55:07 +0000

Summary

Use Cache.match() (or an equivalent cacheStore.match) to return the last known response immediately, refresh the resource in the background, and only tell the client after the new copy is safely written. That preserves responsiveness and prevents the UI from claiming freshness before the cache actually changes.

Implementation overview (server will insert verified code)

Fast path: call cacheStore.match(url). If a value exists, return it immediately and kick off a background update. Expose the background task as a promise so tests or diagnostics can await it without delaying the UI.
Miss path: when the cache has no entry, fetch from the network, store the result, notify clients after the write, and return the network response.
Background update: fetch the candidate, re-read the current cached entry, compare freshness (timestamp, ETag, or version), and only write the candidate when it is at least as fresh. If it’s older, skip the write and emit a skipped notification. Notify clients only after successful writes.

Expected behavior

Immediate rendering when cache entry exists.
Non-blocking refresh so future navigations see a fresher copy.
Notifications are trustworthy: the client receives an “updated” signal only after the write completes.
No last-writer-wins surprises: the compare-and-set rule prevents older network responses from replacing newer cached copies.

Limitations

The runtime models one canonical cached response per URL. It doesn’t merge multiple candidates or provide full HTTP validation semantics.
It’s a small, testable object model; it does not exercise browser-specific APIs like event.respondWith(), Response.clone(), or worker activation and lifecycle. Those require real browser integration tests.
Freshness checks are application-specific. The example uses a synthetic timestamp; in production, use version headers, ETags, or application metadata to decide writes.

Why read the full article

It explains the exact ordering you must preserve, shows a minimal runtime that makes ownership and replacement rules visible, and includes focused tests proving the three core behaviors: immediate cache returns, network fallback storing, and refusing to overwrite newer cache entries with older network responses.

(Verified implementation will be inserted below by the server.)

Working example

export function createMemoryCache() {
  const store = new Map();

  return {
    async match(url) {
      const value = store.get(url);
      return value ? { ...value } : undefined;
    },
    async put(url, response) {
      store.set(url, { ...response });
    },
    async delete(url) {
      return store.delete(url);
    },
    async keys() {
      return [...store.keys()];
    },
  };
}

export function createSwRuntime({ cacheStore, fetchFn, notifyClients }) {
  if (!cacheStore || typeof cacheStore.match !== 'function' || typeof cacheStore.put !== 'function') {
    throw new TypeError('cacheStore must provide async match(url) and put(url, response)');
  }
  if (typeof fetchFn !== 'function') {
    throw new TypeError('fetchFn must be a function');
  }
  if (typeof notifyClients !== 'function') {
    throw new TypeError('notifyClients must be a function');
  }

  async function backgroundUpdate(url) {
    try {
      const networkResponse = await fetchFn(url);
      const existing = await cacheStore.match(url);
      if (!existing || networkResponse.ts >= existing.ts) {
        await cacheStore.put(url, networkResponse);
        notifyClients({ url, type: 'updated', response: { ...networkResponse } });
      } else {
        notifyClients({ url, type: 'skipped-old', response: { ...networkResponse } });
      }
    } catch (error) {
      notifyClients({ url, type: 'update-failed', error: String(error) });
    }
  }

  async function handleFetch(url, { offlineFallback } = {}) {
    const cached = await cacheStore.match(url);
    if (cached) {
      const background = backgroundUpdate(url);
      return {
        source: 'cache',
        response: { ...cached },
        background,
      };
    }

    try {
      const networkResponse = await fetchFn(url);
      await cacheStore.put(url, networkResponse);
      notifyClients({ url, type: 'updated', response: { ...networkResponse } });
      return {
        source: 'network',
        response: { ...networkResponse },
      };
    } catch {
      if (offlineFallback) {
        const fallback = await cacheStore.match(offlineFallback);
        if (fallback) {
          return {
            source: 'fallback',
            response: { ...fallback },
          };
        }
      }

      return {
        source: 'error',
        response: { body: 'offline', ts: Date.now(), offline: true },
      };
    }
  }

  return { handleFetch };
}

Read the full article: https://chriseugenerodriguez.com/blog/service-worker-stale-while-revalidate-cache-match

Confirm a missing index with EXPLAIN ANALYZE and index inspection

Chris Rodriguez — Wed, 04 Nov 2026 21:25:06 +0000

When a listing or search query feels slow, adding an index is an attractive immediate step. The safer, more reliable workflow starts with EXPLAIN (ANALYZE) and a careful comparison of planner estimates to actual execution. This short guide explains an implementation-focused approach and what you can expect.

Implementation

Capture the exact slow query with realistic parameters and run EXPLAIN (ANALYZE, FORMAT JSON). Use the JSON form for deterministic parsing and automated checks.
Read the plan node by node. Compare estimated rows to actual rows; identify the slow child node. Nested loop inner scans, Sort nodes, and Seq Scans on large tables are common hotspots.
Inspect existing indexes (pg_indexes or pg_catalog). Read the column order and any included columns; match the index’s leading columns against equality/range predicates and check whether the index ordering satisfies ORDER BY to avoid Sort.

Expected behavior

Seq Scan on a selective predicate over a large table is a strong signal an index could help — but only after you run ANALYZE. Stale statistics can mislead the planner.
Index-only scans with nonzero Heap Fetches indicate the index is not covering: adding included columns or changing the projection may reduce heap visits.
Large mismatches between estimated and actual rows often point to statistics problems. Updating statistics or tuning statistics targets can be more effective than adding an index.

Limitations

EXPLAIN ANALYZE executes the statement; for data-modifying queries run it inside a rollbackable transaction if you must avoid persistence.
This guidance focuses on index shape (column order + ordering) and statistics. It does not automatically generate production-ready DDL for functional, expression, or partial indexes.
Application-level latency (client rendering, network) is outside server-side EXPLAIN's scope — always combine server-side plans with before-and-after measurements in the app context.

Use the article’s small JSON-plan analyzer as a checklist: it flags sequential scans, index presence, Heap Fetches, and large estimate mismatches so you can prioritize ANALYZE, a covering index, or a query rewrite — then re-run EXPLAIN ANALYZE to confirm the result.

(Example implementation is inserted by the site as a verified code block.)

Working example

export function analyzeExplainAnalyze(planJson, {rowEstimateTolerance = 3, heapFetchThreshold = 1} = {}){
  // planJson: a parsed EXPLAIN (ANALYZE, FORMAT JSON) output: array with one plan object
  // Returns a diagnostics object describing signs that a missing or wrong index is slowing the query
  if (!Array.isArray(planJson) || planJson.length === 0) throw new TypeError('planJson must be a non-empty array (EXPLAIN JSON output)')
  const root = planJson[0].Plan ?? planJson[0]

  const findings = []
  let totalEstimated = 0
  let totalActual = 0

  function walk(node){
    if (!node) return

    // Normalize node type
    const nodeTypeRaw = node['Node Type'] || node['Node-Type'] || node['Plan Node Type'] || ''
    const nodeType = (typeof nodeTypeRaw === 'string') ? nodeTypeRaw.toLowerCase() : ''

    // Detect sequential scan or index scans (cover common variations)
    if (nodeType.includes('seq scan')){
      findings.push({type: 'seq_scan', message: `Sequential scan detected: ${nodeTypeRaw}`, node})
    }
    if (nodeType.includes('index scan') || nodeType.includes('index only') || nodeType.includes('index-only') || nodeType.includes('index-only scan') || nodeType.includes('indexonly') || nodeType.includes('bitmap index') || nodeType.includes('bitmap heap') ){
      findings.push({type: 'index_scan_present', message: `Index scan node present: ${nodeTypeRaw}`, node})
    }

    // Detect heap fetches
    // Common EXPLAIN JSON uses 'Heap Fetches' or 'Heap Fetches' exactly; be defensive about key name
    const heapFetchKeys = ['Heap Fetches', 'HeapFetches', 'Heap_Fetches', 'heap_fetches']
    for (const k of heapFetchKeys){
      const v = node[k]
      if (typeof v === 'number' && v > heapFetchThreshold){
        findings.push({type: 'heap_fetches', message: `Heap fetches: ${v}`, node})
        break
      }
    }

    // Compare planner estimates and actuals when available under common keys
    const estRows = (typeof node['Plan Rows'] === 'number' ? node['Plan Rows'] : (typeof node['PlanRows'] === 'number' ? node['PlanRows'] : undefined))
    const actRows = (typeof node['Actual Rows'] === 'number' ? node['Actual Rows'] : (typeof node['ActualRows'] === 'number' ? node['ActualRows'] : undefined))

    if (typeof estRows === 'number' && typeof actRows === 'number'){
      totalEstimated += estRows
      totalActual += actRows
      if (estRows === 0 && actRows > 0){
        findings.push({type: 'zero_estimate', message: `Planner estimated 0 rows but ${actRows} were returned (bad stats)`, node})
      } else if (estRows > 0 && actRows / estRows > rowEstimateTolerance){
        findings.push({type: 'estimation_mismatch', message: `Actual rows (${actRows}) exceed estimate (${estRows}) by > ${rowEstimateTolerance}x`, node, ratio: actRows/estRows})
      }
    }

    // Recurse into children
    const children = node.Plans || node['Plans'] || node['plan nodes'] || []
    if (Array.isArray(children)) for (const c of children) walk(c)
  }

  walk(root)

  // Summarize
  const hasSeq = findings.some(f => f.type === 'seq_scan')
  const hasIndex = findings.some(f => f.type === 'index_scan_present')
  const hasHeapFetches = findings.some(f => f.type === 'heap_fetches')
  const hasEstimation = findings.some(f => f.type === 'estimation_mismatch' || f.type === 'zero_estimate')

  const suggestions = []
  if (hasSeq && !hasIndex){
    suggestions.push('No index usage found in the plan. Consider creating an index that matches WHERE and ORDER BY patterns (create an index), or ensure ANALYZE has been run so planner statistics are current.')
  }
  if (hasHeapFetches){
    suggestions.push('Heap fetches are present. Consider a covering (multi-column) index or include needed columns so an index-only scan can be used.')
  }
  if (hasEstimation){
    suggestions.push('Planner row estimates disagree with actuals. Run ANALYZE on the table and consider increasing statistics targets for relevant columns.')
  }
  if (!hasSeq && hasIndex && !hasHeapFetches && !hasEstimation){
    suggestions.push('Plan shows index usage and no obvious heap fetches or estimation errors. Index-related issue is unlikely.')
  }

  return {
    findings,
    summary: {
      hasSeq,
      hasIndex,
      hasHeapFetches,
      hasEstimation,
      totalEstimated: totalEstimated || null,
      totalActual: totalActual || null
    },
    suggestions
  }
}

export function suggestIndexFromQuery({whereColumns = [], orderBy = []}, existingIndexes = []){
  // Very small helper to recommend an index key order: leading columns from predicates then ordering columns
  // existingIndexes: array of {name, columns: ['a','b']} — we only compare simple equality
  const needed = [...new Set([...whereColumns, ...orderBy])]
  const matches = existingIndexes.find(idx => {
    if (!Array.isArray(idx.columns)) return false
    // good match if idx.columns startsWith needed
    for (let i=0;i<needed.length;i++){
      if (idx.columns[i] !== needed[i]) return false
    }
    return needed.length > 0
  })
  if (matches) return {found: true, index: matches}
  return {found: false, suggestion: needed.length ? `CREATE INDEX ON table (${needed.join(', ')})` : 'No predicate/order columns provided; review query.'}
}

Read the full article: https://chriseugenerodriguez.com/blog/postgresql-explain-index-inspection

Diagnose slow LCP on phones: field-first, split into subparts, and prove user-visible impact

Chris Rodriguez — Wed, 04 Nov 2026 03:40:05 +0000

When phones report slow LCP, the practical question is not “how do I speed up the site” but “which visible element are users waiting for, and which stage of its load path dominates?”

Implementation (overview)

Start with field data (CrUX, Search Console, or your RUM) to confirm the complaint on phones and to identify the affecting URL and likely LCP element. Field data answers whether real users see a problem; don’t skip it.
Reproduce the same phone-sized viewport and content state in a lab trace to gather navigation and resource timings that explain why the field signal exists.
Break LCP into four subparts: Time to First Byte (TTFB), resource discovery/load delay, resource download duration, and element render delay. Each subpart points at a different ownership domain (server, markup/priority, asset size/network, or client rendering).
Map the dominant subpart to the smallest useful fix: server or CDN work for TTFB; preload or earlier markup for discovery delay; file format/size or CDN for download duration; reduce render-blocking CSS/JS or avoid hidden-state logic for render delay.
Apply a single, targeted change and re-measure the same element on the same phone state. Compare subpart distributions, not just the headline LCP number.

Expected behavior

You’ll get a clear diagnosis explaining which part of the load path caused the visible delay on phones. A well-targeted change should shorten the dominant subpart in lab traces and, when broadly rolled out, align with field improvements for the tested page.
The article includes a small helper that computes the breakdown and returns a recommendation tied to the dominant subpart.

Limitations

This workflow is page- and content-shape specific. A fix for a hero-image landing page may not apply to a text-heavy page with the same LCP score but a different dominant subpart.
Lab traces explain causality but are sensitive to device, CPU contention, and network variability. Always anchor claims to field evidence when possible.

The server will insert a verified implementation example that computes the breakdown and chooses a recommendation for the dominant subpart.

Working example

export function analyzeLCP({ navigationTiming, lcpEntry, resourceTiming } = {}) {
  if (!navigationTiming || typeof navigationTiming.responseStart !== 'number') {
    throw new TypeError('navigationTiming with numeric responseStart required');
  }
  if (typeof lcpEntry?.renderTime !== 'number') {
    throw new TypeError('lcpEntry with numeric renderTime required');
  }

  const navigationStart = typeof navigationTiming.navigationStart === 'number'
    ? navigationTiming.navigationStart
    : 0;

  const ttfb = Math.max(0, navigationTiming.responseStart - navigationStart);

  const hasResource = Boolean(
    resourceTiming &&
    typeof resourceTiming.startTime === 'number' &&
    typeof resourceTiming.responseEnd === 'number'
  );

  let resourceLoadDelay = 0;
  let resourceLoadDuration = 0;
  let elementRenderDelay = 0;

  if (hasResource) {
    resourceLoadDelay = Math.max(0, resourceTiming.startTime - navigationTiming.responseStart);
    resourceLoadDuration = Math.max(0, resourceTiming.responseEnd - resourceTiming.startTime);
    elementRenderDelay = Math.max(0, lcpEntry.renderTime - resourceTiming.responseEnd);
  } else {
    elementRenderDelay = Math.max(0, lcpEntry.renderTime - navigationTiming.responseStart);
  }

  const totalLcpMs = ttfb + resourceLoadDelay + resourceLoadDuration + elementRenderDelay;
  const parts = [
    { name: 'ttfb', ms: ttfb },
    { name: 'resourceLoadDelay', ms: resourceLoadDelay },
    { name: 'resourceLoadDuration', ms: resourceLoadDuration },
    { name: 'elementRenderDelay', ms: elementRenderDelay },
  ];

  // When two parts tie, prefer the part that better maps to a developer-actionable
  // front-end intervention. In practice we want elementRenderDelay to win ties
  // with ttfb so that zero-resource LCPs attribute dominance to rendering.
  const priority = {
    ttfb: 1,
    resourceLoadDelay: 2,
    resourceLoadDuration: 3,
    elementRenderDelay: 4,
  };

  const dominant = parts.reduce((a, b) => {
    if (a.ms > b.ms) return a;
    if (b.ms > a.ms) return b;
    // tie: choose higher priority
    return priority[a.name] >= priority[b.name] ? a : b;
  });

  const recommendations = {
    ttfb: 'Improve server TTFB: reduce backend work, cache HTML, or use a CDN.',
    resourceLoadDelay: 'Start loading the LCP resource earlier: improve discovery or preload it.',
    resourceLoadDuration: 'Reduce the resource size or use a more efficient format.',
    elementRenderDelay: 'Reduce render-blocking CSS/JS and avoid hiding the LCP element.',
  };

  return {
    totalLcpMs,
    breakdown: parts,
    dominantSubpart: dominant.name,
    recommendation: recommendations[dominant.name],
  };
}

Read the full article: https://chriseugenerodriguez.com/blog/diagnose-slow-lcp-on-phones

Prevent leaked asyncio workers by making task ownership explicit

Chris Rodriguez — Tue, 03 Nov 2026 01:25:05 +0000

When an asyncio child fails, observing its exception is only half the problem: decide who owns the remaining tasks and waits for their cleanup. The linked Python documentation describes gather as an aggregation primitive and TaskGroup as a structured lifetime for related tasks. A TaskGroup normally cancels its remaining children after a non-cancellation failure and waits for them before leaving the scope. Do not treat a raised exception from gather as proof that every sibling stopped.

The runnable example below is a JavaScript conceptual analogy, executed with Node.js. It uses Promise.all, AbortController and Promise.allSettled to illustrate cooperative cancellation and waiting for cleanup. It is not Python code and its tests do not execute or verify asyncio.gather(), TaskGroup, CancelledError or TimeoutError. The Python recommendations in this article come from the linked Python documentation, not from those JavaScript test results.

The fixture exports runNaive and runSafe. runNaive returns Promise.all without signalling its sibling workers after a failure. runSafe creates an AbortController, signals its cooperative workers, waits with Promise.allSettled, and then reports the original error. This demonstrates an application-owned JavaScript cleanup pattern, not a reimplementation of TaskGroup. The tests cover ordered successful results, continued sibling progress in the naive case, and stopped progress after the safe runner returns.

For a Python service, separately test a successful group, a child exception while another child is waiting, and an enclosing cancellation or timeout with the real I/O library. The JavaScript checks cannot establish Python exception-group behavior, CancelledError handling or TimeoutError conversion. Swallowing cancellation and deliberately shielding work also change the native lifetime; inspect those choices before relying on cleanup.

Working example

export class AbortError extends Error {
  constructor(message = 'Aborted') {
    super(message);
    this.name = 'AbortError';
  }
}

function sleep(ms, signal) {
  return new Promise((resolve, reject) => {
    const timer = setTimeout(done, ms);

    function done() {
      cleanup();
      resolve();
    }

    function onAbort() {
      cleanup();
      reject(new AbortError());
    }

    function cleanup() {
      clearTimeout(timer);
      signal?.removeEventListener('abort', onAbort);
    }

    if (signal?.aborted) {
      cleanup();
      reject(new AbortError());
      return;
    }

    if (signal) signal.addEventListener('abort', onAbort, { once: true });
  });
}

export async function worker(id, {
  steps = 5,
  stepMs = 10,
  signal,
  failAtStep = null,
  progress = {},
} = {}) {
  for (let i = 1; i <= steps; i++) {
    if (signal?.aborted) throw new AbortError();
    await sleep(stepMs, signal);
    progress[id] = (progress[id] ?? 0) + 1;
    if (failAtStep === i) {
      throw new Error(`worker:${id} failed at step ${i}`);
    }
  }
  return `done:${id}`;
}

export async function runNaive(numWorkers, opts = {}) {
  const { failingWorker = null, progress = {}, steps = 5, stepMs = 10 } = opts;
  const tasks = Array.from({ length: numWorkers }, (_, id) => worker(id, {
    steps,
    stepMs,
    progress,
    failAtStep: id === failingWorker ? 2 : null,
  }));
  return Promise.all(tasks);
}

export async function runSafe(numWorkers, opts = {}) {
  const { failingWorker = null, progress = {}, steps = 5, stepMs = 10 } = opts;
  const controller = new AbortController();
  const tasks = Array.from({ length: numWorkers }, (_, id) => worker(id, {
    signal: controller.signal,
    steps,
    stepMs,
    progress,
    failAtStep: id === failingWorker ? 2 : null,
  }));

  try {
    return await Promise.all(tasks);
  } catch (error) {
    if (!(error instanceof AbortError)) controller.abort();
    await Promise.allSettled(tasks);
    throw error;
  }
}

Read the full article: https://chriseugenerodriguez.com/blog/asyncio-failing-task-does-not-leak-workers