Andrew Usher's Blog

Handling Multiple Promises: Promise.all vs Promise.allSettled

Wed, 21 Jan 2026 00:00:00 GMT

When you're pulling data from multiple sources at once, JavaScript gives you two tools: Promise.all and Promise.allSettled. Pick the wrong one and things get ugly fast—one failed request takes down everything.

I'll break down when to use each.

Promise.all: Everything or Nothing

Promise.all stops dead the moment anything fails. If you're fetching three endpoints and one returns a 500 error, you get nothing back. Zilch.

const fetchUserData = async () => {
  const endpoints = [
    'https://api.example.com/users/1',
    'https://api.example.com/users/2',
    'https://api.example.com/users/3',
  ]

  try {
    const responses = await Promise.all(
      endpoints.map((url) => fetch(url).then((res) => res.json()))
    )
    console.log('All data fetched:', responses)
    return responses
  } catch (error) {
    console.error('One request failed:', error)
  }
}

This makes sense when your operations depend on each other. Picture a form submission where validations chain together, or a dashboard where missing user data means you can't render anything at all. If one piece missing breaks the whole flow, Promise.all is your friend.

Promise.allSettled: Let Everything Finish

allSettled doesn't care about failure—it waits for all promises to finish and reports back on each one individually.

const fetchUserProfiles = async () => {
  const requests = [
    fetch('/api/user/1'),
    fetch('/api/user/2'),
    fetch('/api/avatar/3'),
  ]

  const results = await Promise.allSettled(requests)

  results.forEach((result, index) => {
    if (result.status === 'fulfilled') {
      console.log(`Request ${index} succeeded:`, result.value)
    } else {
      console.log(`Request ${index} failed:`, result.reason)
    }
  })

  return results
}

Each result tells you whether it succeeded (status: "fulfilled") or failed (status: "rejected"). This is perfect for independent operations where partial data still has value.

When to Use Which

Go with Promise.all when partial results are useless. If you're loading critical data and can't proceed without all of it, this is the right call.

Go with Promise.allSettled when operations are independent and some data beats no data. Analytics, optional metadata, secondary UI elements—these don't need to bring down the whole page if one source is down.

Ask yourself: "If half these requests fail, is the result still useful?" Answer no? Promise.all. Answer yes? allSettled.

Quick Win: Extract Just the Successes

After allSettled, you often want the working values only:

const results = await Promise.allSettled(promises)

const successfulValues = results
  .filter((result) => result.status === 'fulfilled')
  .map((result) => result.value)

const errors = results
  .filter((result) => result.status === 'rejected')
  .map((result) => result.reason)

Clean data, full error picture, zero surprises.

The Bottom Line

Promise.all is all-or-nothing. Promise.allSettled plays the long game. The right choice keeps your app running when things go wrong—which they always do.

Cookie Store API: The Modern Way to Handle Cookies

Sun, 11 Jan 2026 00:00:00 GMT

Introduction

The Cookie Store API makes all of this possible. It's a modern, Promise-based alternative to the legacy document.cookie API that solves many of the problems developers have struggled with for years. In this article, we'll explore Cookie Store API from the ground up. We'll start with basics, progressively build up to advanced patterns, and create interactive demos you can play with. By the end, you'll have all the tools you need to modernize your cookie handling.

The Problem with `document.cookie`

Before diving into the Cookie Store API, let's understand why we need a new API. The traditional document.cookie approach has several limitations:

1. Synchronous and Blocking

// This blocks the main thread!
const cookies = document.cookie;

When you read document.cookie, the browser must serialize all cookies for the current domain into a single string. This is slow and blocks your JavaScript execution.

2. String Parsing is Error-Prone

// You have to manually parse this mess:
"session=abc123; user=john; theme=dark; analytics=enabled"

// Parse logic is tedious:
const cookies = document.cookie.split(';').reduce((acc, cookie) => {
  const [name, value] = cookie.trim().split('=');
  acc[name] = value;
  return acc;
}, {});

This parsing code is duplicated across projects and prone to bugs.

3. No Service Worker Access

Service workers can't access document.cookie because they don't have a DOM. This makes it impossible to read cookies in:

Offline-first apps
Background sync scenarios
Push notification handlers

4. No Type Safety

// Returns a string - what is this?
const value = document.cookie.split('=')[1];
// What if the cookie has an equals sign in its value?

No validation, no structure, just a string.

5. No Change Notifications

You can't listen for cookie changes. You have to poll (inefficient) or reload the page to see updates.

The Cookie Store API solves all of these problems.

Quick Start: Your First Cookie

The Cookie Store API is accessed via the cookieStore object, available in both windows and service workers.

Basic Usage:

// Get a cookie
const cookie = await cookieStore.get('session');
console.log(cookie); // { name: 'session', value: 'abc123', ... }

// Set a cookie
await cookieStore.set('theme', 'dark');

// Delete a cookie
await cookieStore.delete('session');

That's it! Three simple methods. But let's try it yourself:

Notice how much easier this is than document.cookie? No parsing, no string manipulation, just clean, promise-based operations.

Cookie Properties Deep Dive

The real power of the Cookie Store API is in the options you can pass when setting cookies. Let's explore each property:

expires vs maxAge

Two ways to control cookie lifetime:

// Using expires (absolute timestamp)
await cookieStore.set({
  name: 'session',
  value: 'abc123',
  expires: Date.now() + 3600000 // 1 hour from now
});

// Session cookie (no expiration)
await cookieStore.set({
  name: 'theme',
  value: 'dark'
  // No expires = session cookie, deleted when browser closes
});

domain

Controls which domains can receive the cookie:

// Only this exact domain
await cookieStore.set({
  name: 'cookie',
  value: 'value',
  domain: 'example.com'
});

// Subdomains too (note the leading dot)
await cookieStore.set({
  name: 'cookie',
  value: 'value',
  domain: '.example.com' // example.com, www.example.com, api.example.com
});

// Current domain only (default)
await cookieStore.set({
  name: 'cookie',
  value: 'value'
  // No domain = only set for current domain
});

path

Restricts cookie to a specific path:

// Only accessible from /dashboard and subpaths
await cookieStore.set({
  name: 'preferences',
  value: 'value',
  path: '/dashboard'
});

// Site-wide (default)
await cookieStore.set({
  name: 'session',
  value: 'value',
  path: '/'
});

Secure

Only send over HTTPS connections:

await cookieStore.set({
  name: 'session',
  value: 'abc123',
  secure: true // Only sent over HTTPS
});

Always set secure: true for authentication cookies and sensitive data.

SameSite

Controls when cookies are sent with cross-site requests:

// Strict: Only same-site requests
await cookieStore.set({
  name: 'token',
  value: 'abc123',
  sameSite: 'Strict'
});

// Lax: Allows some cross-site (navigation)
await cookieStore.set({
  name: 'token',
  value: 'abc123',
  sameSite: 'Lax' // Default for modern browsers
});

// None: Allows all cross-site (requires Secure)
await cookieStore.set({
  name: 'token',
  value: 'abc123',
  sameSite: 'None',
  secure: true // Required with SameSite=None
});

Partitioned

Creates a privacy-preserving partitioned cookie (more on this later):

await cookieStore.set({
  name: 'analytics',
  value: '123',
  domain: '.tracker.com',
  partitioned: true // Scoped to top-level site
});

Try configuring all these properties in the interactive builder:

Getting Cookies

The Cookie Store API provides two methods for reading cookies:

`get()` - Single Cookie

// Get by name
const theme = await cookieStore.get('theme');
console.log(theme); // { name: 'theme', value: 'dark', ... }

// Get by options
const cookie = await cookieStore.get({
  name: 'session',
  domain: 'example.com',
  path: '/api'
});

// Returns null if not found
const missing = await cookieStore.get('does-not-exist');
console.log(missing); // null

`getAll()` - Multiple Cookies

// Get all cookies
const allCookies = await cookieStore.getAll();
console.log(allCookies); // [{ name: 'a', value: '1' }, { name: 'b', value: '2' }]

// Filter by name
const sessionCookies = await cookieStore.getAll({ name: 'session' });

// Filter by path
const apiCookies = await cookieStore.getAll({ path: '/api' });

// Chain filters
const secureSessionCookies = await cookieStore.getAll({
  name: 'session',
  path: '/api',
  secure: true
});

Unlike document.cookie (which returns a string), these methods return structured objects with all cookie properties.

Cookie Change Events

One of the most powerful features of the Cookie Store API is the ability to subscribe to cookie changes. This means you can react to cookies being added, modified, or deleted in real-time.

Basic Event Listener:

cookieStore.addEventListener('change', (event) => {
  console.log('Cookies changed:', event);

  // event.type: 'changed' | 'deleted'
  // event.changed: Array of cookies that were added or modified
  // event.deleted: Array of cookies that were deleted
});

Real-World Example: Auto-Logout on Token Deletion:

cookieStore.addEventListener('change', (event) => {
  // Check if auth cookie was deleted
  const deletedSession = event.deleted.find(c => c.name === 'session');

  if (deletedSession) {
    // Redirect to login page
    window.location.href = '/login';
    // Clear app state
    logout();
  }
});

Sync State Across Tabs:

cookieStore.addEventListener('change', async (event) => {
  // Update theme when cookie changes
  const themeCookie = event.changed.find(c => c.name === 'theme');

  if (themeCookie) {
    // Update UI in all tabs
    document.documentElement.setAttribute('data-theme', themeCookie.value);
    // Update local state
    setTheme(themeCookie.value);
  }
});

Try it out in the interactive demo:

Partitioned Cookies (CHIPS)

Cookies Having Independent Partitioned State (CHIPS) is a privacy-preserving feature that's rapidly becoming essential for modern web development.

The Problem: Third-Party Cookies

Traditional third-party cookies can track users across sites:

User visits site-a.com → tracker.com cookie set
User visits site-b.com → Same tracker.com cookie read
Tracker knows user visited both sites

This is why browsers increasingly block third-party cookies (ITP, ETP, etc.).

The Solution: Partitioned Cookies

Partitioned cookies are scoped to the top-level site:

User visits site-a.com → tracker.com sets partitioned cookie
User visits site-b.com → Different tracker.com cookie (different partition!)
Each site gets its own tracker.com cookie → No cross-site tracking

Legitimate Use Cases:

Partitioned cookies still enable legitimate third-party functionality:

Embedded login buttons (Google, Facebook, Twitter OAuth)
Embedded payments (Stripe, PayPal)
Embedded services (maps, analytics)

Each embedding site gets its own isolated cookie.

Service Worker Integration

One of the biggest advantages of the Cookie Store API is that it works in service workers. This opens up powerful new patterns:

Background Sync with Cookies:

// In service worker
self.addEventListener('sync', async (event) => {
  const session = await cookieStore.get('session');

  if (session) {
    // Sync user data to server
    await fetch('/api/sync', {
      headers: {
        'Authorization': `Bearer ${session.value}`
      }
    });
  }
});

Push Notifications with Personalization:

// In service worker
self.addEventListener('push', async (event) => {
  const preferences = await cookieStore.get('notifications');

  if (preferences) {
    // Personalize based on user preferences
    const data = await event.data.json();
    data.theme = JSON.parse(preferences.value).theme;

    await self.registration.showNotification('Update', data);
  }
});

Offline-First Authentication:

// In service worker
self.addEventListener('fetch', async (event) => {
  if (event.request.url.includes('/api/')) {
    const session = await cookieStore.get('session');

    if (session) {
      // Add auth header to all API requests
      const modifiedRequest = new Request(event.request, {
        headers: {
          ...event.request.headers,
          'Authorization': `Bearer ${session.value}`
        }
      });

      return fetch(modifiedRequest);
    }
  }

  return event.respondWith(fetch(event.request));
});

Note: Service workers can only access cookies via self.cookieStore, not window.cookieStore.

Async Patterns & Error Handling

Promise Chaining

// Chain multiple operations
await cookieStore.set('step1', 'value1');
await cookieStore.set('step2', 'value2');
await cookieStore.set('step3', 'value3');

// Parallel operations (faster!)
await Promise.all([
  cookieStore.set('cookie1', 'value1'),
  cookieStore.set('cookie2', 'value2'),
  cookieStore.set('cookie3', 'value3')
]);

Error Handling

try {
  await cookieStore.set({
    name: 'session',
    value: token,
    secure: true,
    sameSite: 'None' // ❌ Will throw without secure!
  });
} catch (error) {
  console.error('Failed to set cookie:', error);
  // Handle error (show message to user, fallback, etc.)
}

Common errors:

Secure context required: Only works on HTTPS (or localhost)
Invalid SameSite: SameSite='None' requires Secure=true
Cookie size exceeded: Cookies limited to ~4KB
Invalid domain: Can't set cookies for other domains

Retry Logic

async function setCookieWithRetry(name, value, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      await cookieStore.set({ name, value, ...options });
      return true;
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      // Exponential backoff
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 100));
    }
  }
}

Migration Guide: From `document.cookie` to Cookie Store API

Reading Cookies

Old way:

const cookies = document.cookie.split(';').reduce((acc, cookie) => {
  const [name, value] = cookie.trim().split('=');
  acc[name] = value;
  return acc;
}, {});
console.log(cookies.theme);

New way:

const theme = await cookieStore.get('theme');
console.log(theme.value);

Setting Cookies

Old way:

document.cookie = 'session=abc123; Path=/; Secure; SameSite=Strict';

New way:

await cookieStore.set({
  name: 'session',
  value: 'abc123',
  path: '/',
  secure: true,
  sameSite: 'Strict'
});

Deleting Cookies

Old way:

document.cookie = 'session=; Path=/; Expires=Thu, 01 Jan 1970 00:00:00 GMT';

New way:

await cookieStore.delete('session');

Conditional Implementation

// Feature detection
if ('cookieStore' in window) {
  // Use Cookie Store API
  const cookie = await cookieStore.get('session');
} else {
  // Fallback to document.cookie
  const cookies = document.cookie;
  // Parse cookie string...
}

Performance Considerations

Batch Operations

// Slow (multiple network round-trips)
for (const [name, value] of Object.entries(cookies)) {
  await cookieStore.set(name, value);
}

// Fast (batched)
await Promise.all(
  Object.entries(cookies).map(([name, value]) =>
    cookieStore.set(name, value)
  )
);

Debounce Change Handlers

let timeoutId: number;

cookieStore.addEventListener('change', () => {
  clearTimeout(timeoutId);
  timeoutId = window.setTimeout(() => {
    // Debounced logic (e.g., re-render UI)
    updateCookieUI();
  }, 100);
});

Cache Frequently Accessed Cookies

const cookieCache = new Map<string, ExtendedCookieListItem>();

async function getCachedCookie(name: string) {
  // Check cache first
  if (cookieCache.has(name)) {
    return cookieCache.get(name);
  }

  // Fetch from cookie store
  const cookie = await cookieStore.get(name);
  if (cookie) {
    cookieCache.set(name, cookie);
  }

  return cookie;
}

// Invalidate cache on changes
cookieStore.addEventListener('change', (event) => {
  event.changed.forEach(cookie => cookieCache.set(cookie.name, cookie));
  event.deleted.forEach(cookie => cookieCache.delete(cookie.name));
});

Real-World Use Cases

1. Session Management

// Set session on login
async function login(credentials) {
  const response = await fetch('/api/login', {
    method: 'POST',
    body: JSON.stringify(credentials)
  });

  const { token } = await response.json();

  await cookieStore.set({
    name: 'session',
    value: token,
    expires: Date.now() + 3600000 * 24 * 7, // 7 days
    secure: true,
    sameSite: 'Strict',
    httpOnly: false // Can't set via JavaScript for server-only cookies
  });
}

// Check session on load
async function checkAuth() {
  const session = await cookieStore.get('session');

  if (!session) {
    window.location.href = '/login';
    return false;
  }

  return true;
}

2. A/B Testing

async function getVariant() {
  let variant = await cookieStore.get('ab_variant');

  if (!variant) {
    // Assign random variant
    variant = Math.random() < 0.5 ? 'A' : 'B';

    await cookieStore.set({
      name: 'ab_variant',
      value: variant,
      expires: Date.now() + 3600000 * 24 * 30 // 30 days
    });
  }

  return variant.value;
}

3. User Preferences

async function setTheme(theme: 'light' | 'dark') {
  await cookieStore.set({
    name: 'theme',
    value: theme,
    expires: Date.now() + 3600000 * 24 * 365 // 1 year
  });

  document.documentElement.setAttribute('data-theme', theme);
}

async function loadTheme() {
  const theme = await cookieStore.get('theme');
  if (theme) {
    document.documentElement.setAttribute('data-theme', theme.value);
  }
}

4. Cross-Domain Authentication

// Set SSO token across domains (with CORS)
async function setSSOToken(token: string, domains: string[]) {
  await Promise.all(
    domains.map(domain =>
      fetch(`https://${domain}/api/set-token`, {
        method: 'POST',
        body: JSON.stringify({ token }),
        credentials: 'include'
      })
    )
  );
}

// In server endpoint (not shown):
// await cookieStore.set({ name: 'sso_token', value: token, domain });

Best Practices

1. Always Use Secure Cookies

// ❌ Bad
await cookieStore.set('session', 'token');

// ✅ Good
await cookieStore.set({
  name: 'session',
  value: 'token',
  secure: true
});

2. Set Expiration

// ❌ Bad (session cookie when not needed)
await cookieStore.set('preferences', 'value');

// ✅ Good (explicit expiration)
await cookieStore.set({
  name: 'preferences',
  value: 'value',
  expires: Date.now() + 3600000 * 24 * 365 // 1 year
});

3. Use SameSite Appropriately

// Authentication: Strict
await cookieStore.set({
  name: 'session',
  value: token,
  sameSite: 'Strict',
  secure: true
});

// Analytics: Lax
await cookieStore.set({
  name: 'analytics_id',
  value: 'abc123',
  sameSite: 'Lax'
});

// Third-party: None (with Secure)
await cookieStore.set({
  name: 'third_party',
  value: 'value',
  sameSite: 'None',
  secure: true
});

4. Handle Errors Gracefully

async function setCookieSafe(options) {
  try {
    await cookieStore.set(options);
    return true;
  } catch (error) {
    console.warn('Failed to set cookie:', error);

    // Fallback or alternative
    localStorage.setItem(options.name, options.value);
    return false;
  }
}

5. Use Partitioned Cookies for Third-Party Contexts

// Embedded service
await cookieStore.set({
  name: 'analytics',
  value: 'id123',
  domain: '.analytics.com',
  partitioned: true // Privacy-preserving
});

Wrapping Up

We've covered a lot of ground! Here's what we explored:

The Problem: document.cookie is synchronous, error-prone, and unavailable in service workers
The Solution: Cookie Store API is async, Promise-based, and works everywhere
Core Methods: get(), getAll(), set(), delete()
Advanced Features: Change events, partitioned cookies, service worker integration
Best Practices: Security, performance, error handling

The Cookie Store API represents a significant improvement in how we handle cookies on the web. It's:

Faster: Asynchronous, non-blocking operations
Safer: Better security controls (partitioned cookies, SameSite)
More Powerful: Works in service workers, supports change events
Easier: No string parsing, promise-based, type-safe

Resources

The code for all interactive demos in this article is available in this repository. Feel free to explore, fork, and build your own cookie-powered experiences!

Building Real-Time Dashboards with Cloudflare Durable Objects

Sun, 21 Dec 2025 00:00:00 GMT

Introduction

What if you could build a real-time analytics dashboard that scales to millions of concurrent users, handles persistent WebSocket connections, and costs almost nothing when idle? That's the promise of Cloudflare Durable Objects with Hibernation.

Traditional real-time architectures require dedicated servers that consume resources 24/7, even when mostly idle. Connection management becomes a nightmare at scale. Durable Objects flip this model on its head: they're serverless, globally distributed, and automatically hibernate when inactive - consuming zero CPU time while preserving all state.

In this article, we'll explore how to build real-time systems using Durable Objects. We'll understand the fundamentals, compare different connection types, visualize the architecture, and see how hibernation saves costs. Every concept comes with interactive demos you can experiment with right here in your browser.

What You'll Learn: By the end of this article, you'll understand Durable Objects, WebSocket vs SSE vs polling trade-offs, how hibernation works, and how to architect production-ready real-time dashboards.

What Are Durable Objects?

Durable Objects are Cloudflare's answer to stateful serverless computing. Think of them as single-threaded, globally distributed mini-servers that live at the edge. Unlike traditional serverless functions that are stateless and ephemeral, each Durable Object:

Has persistent state - In-memory data that survives between requests
Lives in one location - Provides strong consistency guarantees
Handles concurrent connections - Perfect for WebSockets and real-time data
Hibernates when idle - Automatically freezes to save costs
Routes by ID - Multiple clients can connect to the same object instance

The killer feature? They can maintain WebSocket connections while hibernating between messages. Your object wakes up when a message arrives, processes it, then goes back to sleep. No CPU billing during idle time.

The Perfect Use Case: Live Dashboards

Imagine building a live metrics dashboard where:

Multiple browser clients connect to see real-time data
Updates are broadcast to all connected clients instantly
The system scales from 10 to 10,000 concurrent viewers
You only pay for actual processing time, not idle connections

This is exactly what Durable Objects excel at. Let's build it.

Connection Types: Choosing Your Strategy

Before diving into Durable Objects, we need to understand the three main ways to stream data to browsers. Each has different trade-offs for real-time dashboards.

WebSockets: True Bidirectional Communication

WebSockets create a persistent, full-duplex connection between client and server. Both sides can send messages at any time.

How it works:

// Client-side
const ws = new WebSocket('wss://api.example.com/metrics/room-123');

ws.onopen = () => {
  ws.send(JSON.stringify({ type: 'subscribe', metric: 'cpu' }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  updateDashboard(data);
};

// Durable Object can send at any time
ws.send(JSON.stringify({ cpu: 85.3, timestamp: Date.now() }));

Pros:

Lowest latency for bidirectional communication
Efficient for high-frequency updates
Native browser support
Can send from both client and server

Cons:

More complex than HTTP
Requires sticky routing (perfect for Durable Objects)
May need protocol upgrade negotiation
Some corporate firewalls block WebSockets

Best for: Real-time dashboards, multiplayer games, collaborative editing, chat applications

Server-Sent Events (SSE): Simple Streaming

SSE is a simpler, HTTP-based protocol where the server streams events to the client. It's unidirectional - only the server can push data.

How it works:

// Client-side
const eventSource = new EventSource('/api/metrics/stream');

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  updateDashboard(data);
};

// Server streams events
eventSource.addEventListener('metric-update', (event) => {
  console.log('Received:', event.data);
});

Pros:

Simpler than WebSockets
Built on HTTP (better firewall compatibility)
Automatic reconnection handling
Native browser support

Cons:

Unidirectional only (server → client)
Limit of 6 concurrent connections per browser domain
Less efficient encoding than WebSockets
Client must use separate HTTP requests to send data

Best for: News feeds, stock tickers, server logs, one-way notifications

HTTP Polling: The Fallback

Polling is the simplest approach: the client repeatedly requests updates at a fixed interval.

How it works:

// Client polls every 2 seconds
setInterval(async () => {
  const response = await fetch('/api/metrics/latest');
  const data = await response.json();
  updateDashboard(data);
}, 2000);

Pros:

Extremely simple to implement
Works everywhere (just HTTP)
Easy to debug and understand
Stateless server architecture

Cons:

High latency (interval-dependent)
Wasteful (many empty responses)
Scales poorly (constant server requests)
Battery drain on mobile devices

Best for: Infrequent updates, simple MVPs, maximum compatibility, systems with unpredictable update timing

The Verdict for Dashboards

For real-time dashboards with Durable Objects, WebSockets are the clear winner. They provide:

Instant bidirectional updates
Efficient binary or JSON encoding
Perfect pairing with Durable Objects (they handle persistent connections natively)
Low overhead once connected

We'll use WebSockets for the rest of this article, but the concepts apply to SSE as well.

Architecture: How It All Fits Together

Now let's visualize how Durable Objects orchestrate real-time connections. This interactive demo simulates the full architecture:

Understanding the Flow

In this architecture:

Clients connect - Each browser establishes a WebSocket connection to the Durable Object
Durable Object coordinates - A single object instance manages all connections for a specific dashboard/room
Messages flow bidirectionally - Clients send metrics, server broadcasts updates
State persists - The object maintains connection state, message history, and application data
Hibernation kicks in - When no messages arrive for a while, the object freezes

Try adding multiple clients in the demo above. Notice how:

Each client connects through the Durable Object
When you send a message, it routes through the DO
Broadcasting reaches all connected clients simultaneously
The event log tracks every connection, message, and state change

The Code Structure

Here's how you'd structure a Durable Object for a metrics dashboard:

// worker.ts - Cloudflare Worker entrypoint

  async fetch(request: Request, env: Env) {
    const url = new URL(request.url);

    // Extract dashboard ID from URL
    const dashboardId = url.pathname.split('/')[2];

    // Get the Durable Object instance for this dashboard
    const id = env.METRICS_DASHBOARD.idFromName(dashboardId);
    const stub = env.METRICS_DASHBOARD.get(id);

    // Forward the request to the Durable Object
    return stub.fetch(request);
  }
}

// metrics-dashboard.ts - Durable Object class

  private sessions: Map<WebSocket, { id: string; name: string }>;
  private metrics: Map<string, any>;

  constructor(private state: DurableObjectState, private env: Env) {
    this.sessions = new Map();
    this.metrics = new Map();

    // Enable WebSocket hibernation
    this.state.blockConcurrencyWhile(async () => {
      // Load persisted state if needed
      const stored = await this.state.storage.get('metrics');
      if (stored) this.metrics = new Map(stored);
    });
  }

  async fetch(request: Request): Promise<Response> {
    // Upgrade to WebSocket
    const upgradeHeader = request.headers.get('Upgrade');
    if (upgradeHeader !== 'websocket') {
      return new Response('Expected WebSocket', { status: 426 });
    }

    const pair = new WebSocketPair();
    const [client, server] = Object.values(pair);

    // Accept the WebSocket connection
    this.state.acceptWebSocket(server);

    // Store session info
    const sessionId = crypto.randomUUID();
    this.sessions.set(server, { id: sessionId, name: `Client-${sessionId.slice(0, 8)}` });

    // Send welcome message
    server.send(JSON.stringify({
      type: 'connected',
      sessionId,
      currentMetrics: Object.fromEntries(this.metrics)
    }));

    // Notify others
    this.broadcast({
      type: 'user-joined',
      sessionId
    }, server);

    return new Response(null, { status: 101, webSocket: client });
  }

  // This method is called when a WebSocket message arrives
  async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer) {
    const session = this.sessions.get(ws);
    if (!session) return;

    try {
      const data = JSON.parse(message as string);

      // Handle different message types
      switch (data.type) {
        case 'metric-update':
          // Store the metric
          this.metrics.set(data.name, data.value);

          // Broadcast to all connected clients
          this.broadcast({
            type: 'metric-updated',
            name: data.name,
            value: data.value,
            timestamp: Date.now()
          });
          break;

        case 'subscribe':
          // Send current metrics to this client
          ws.send(JSON.stringify({
            type: 'snapshot',
            metrics: Object.fromEntries(this.metrics)
          }));
          break;
      }
    } catch (error) {
      console.error('Error processing message:', error);
      ws.send(JSON.stringify({ type: 'error', message: 'Invalid message format' }));
    }
  }

  // Called when a WebSocket closes
  async webSocketClose(ws: WebSocket, code: number, reason: string) {
    const session = this.sessions.get(ws);
    if (session) {
      this.sessions.delete(ws);

      // Notify others
      this.broadcast({
        type: 'user-left',
        sessionId: session.id
      });
    }

    // Clean up
    ws.close(code, reason);
  }

  // Helper to broadcast to all connected clients
  private broadcast(message: any, exclude?: WebSocket) {
    const payload = JSON.stringify(message);

    for (const [ws] of this.sessions) {
      if (ws !== exclude) {
        try {
          ws.send(payload);
        } catch (error) {
          console.error('Error broadcasting to client:', error);
        }
      }
    }
  }

  // Called when an error occurs on a WebSocket
  async webSocketError(ws: WebSocket, error: unknown) {
    console.error('WebSocket error:', error);
    ws.close(1011, 'Internal error');
  }
}

Key Patterns to Notice

1. Routing by ID

// Multiple clients connecting to "dashboard-123" get the SAME object instance
const id = env.METRICS_DASHBOARD.idFromName('dashboard-123');
const stub = env.METRICS_DASHBOARD.get(id);

2. WebSocket Lifecycle Management

// Accept connection
this.state.acceptWebSocket(server);

// Durable Objects automatically handle:
// - webSocketMessage() when messages arrive
// - webSocketClose() when connections close
// - webSocketError() when errors occur

3. Broadcasting Pattern

// Send to all connected clients except the sender
private broadcast(message: any, exclude?: WebSocket) {
  for (const [ws] of this.sessions) {
    if (ws !== exclude) ws.send(JSON.stringify(message));
  }
}

4. State Persistence

// Store in Durable Object storage (persists across hibernation)
await this.state.storage.put('metrics', Object.fromEntries(this.metrics));

// Load on wake-up
const stored = await this.state.storage.get('metrics');

The Magic of Hibernation

Here's where Durable Objects get really interesting. Traditional WebSocket servers consume CPU time continuously while connections are open. Durable Objects can hibernate - they freeze execution while keeping connections alive.

How Hibernation Works

The lifecycle has four states:

1. Active - Processing messages, executing code

Full CPU billing
Handling WebSocket messages, HTTP requests, or alarms
Object stays active for a timeout period after the last activity (default: ~30 seconds)

2. Idle - No active requests, waiting for hibernation timeout

Still billing for CPU (object is running)
Hibernation timer has started
If new activity arrives, resets to Active

3. Hibernating - Frozen state, consuming no CPU

✨ No CPU billing - This is where you save money
All WebSocket connections remain open
In-memory state is preserved
Waiting for wake event (message, alarm, HTTP request)

4. Resuming - Waking from hibernation

Brief CPU time for state restoration (~milliseconds)
webSocketMessage() or fetch() handlers execute
Returns to Active state

The Cost Savings

Let's do the math for a real-time dashboard with 1,000 connected users:

Traditional Server (always-on):

1,000 connections × 24 hours/day = 24,000 connection-hours
Assumes constant CPU usage even when idle
Estimated cost: ~$50-100/month for dedicated server

Durable Object with Hibernation:

Active time: ~1 second per message × 10 messages/hour = 10 seconds/hour active
Hibernating: 59 minutes 50 seconds per hour
CPU billing: Only the ~10 seconds of active time
Estimated cost: ~$0.50-2/month

That's 95%+ cost reduction for applications with bursty traffic.

Hibernation Best Practices

1. Design for resumption

// Don't rely on timers or intervals - they stop during hibernation
// ❌ Bad
setInterval(() => this.cleanup(), 60000);

// ✅ Good - use alarms instead
this.state.storage.setAlarm(Date.now() + 60000);

async alarm() {
  this.cleanup();
  // Schedule next alarm
  this.state.storage.setAlarm(Date.now() + 60000);
}

2. Keep in-memory state minimal

// Hibernation preserves in-memory state, but large objects slow wake-up
// ✅ Good - lean state
private sessions: Map<WebSocket, SessionInfo>;
private metrics: Map<string, number>;

// ❌ Bad - huge state slows resumption
private fullHistory: Array<{ timestamp: number; data: LargeObject }>;

3. Use storage for critical data

// In-memory state can be lost on rare occasions (object migration, errors)
// Persist critical data to Durable Object storage
async updateMetric(name: string, value: number) {
  this.metrics.set(name, value);

  // Persist to storage
  await this.state.storage.put(`metric:${name}`, value);
}

4. Handle wake-up gracefully

// The first message after hibernation takes slightly longer
// Don't assume instant processing
webSocketMessage(ws: WebSocket, message: string) {
  // Objects wake up automatically - no special handling needed
  // But avoid complex initialization in hot paths
  this.processMessage(message);
}

Monitoring Hibernation

You can track hibernation metrics in your Durable Object:


  private stats = {
    totalMessages: 0,
    hibernationCount: 0,
    lastActivityTime: Date.now()
  };

  async webSocketMessage(ws: WebSocket, message: string) {
    const now = Date.now();
    const timeSinceLastActivity = now - this.stats.lastActivityTime;

    // If more than 30 seconds passed, we probably hibernated
    if (timeSinceLastActivity > 30000) {
      this.stats.hibernationCount++;
      console.log(`Resumed from hibernation after ${timeSinceLastActivity}ms`);
    }

    this.stats.lastActivityTime = now;
    this.stats.totalMessages++;

    // Process the message
    this.handleMessage(ws, message);
  }

  // Expose stats via HTTP endpoint
  async fetch(request: Request) {
    const url = new URL(request.url);

    if (url.pathname === '/stats') {
      return new Response(JSON.stringify(this.stats), {
        headers: { 'Content-Type': 'application/json' }
      });
    }

    // ... WebSocket upgrade logic
  }
}

Stream Backpressure and Buffering

Real-time systems need to handle scenarios where data arrives faster than clients can consume it. This is where backpressure and buffering come in.

The Problem

Imagine your dashboard receives 1,000 metric updates per second, but a client on a slow connection can only process 10/second. What happens to the other 990 messages?

Option 1: Drop them - Client sees stale data Option 2: Buffer them - Risk memory overflow Option 3: Apply backpressure - Slow down the sender

Durable Objects support all three strategies.

Implementing Smart Buffering


  private buffers: Map<WebSocket, Array<any>>;
  private readonly MAX_BUFFER_SIZE = 100;

  constructor(state: DurableObjectState, env: Env) {
    this.buffers = new Map();
  }

  async webSocketMessage(ws: WebSocket, message: string) {
    const data = JSON.parse(message);

    // Broadcast with buffering
    this.broadcastWithBackpressure({
      type: 'metric-update',
      ...data
    });
  }

  private broadcastWithBackpressure(message: any) {
    const payload = JSON.stringify(message);

    for (const [ws] of this.sessions) {
      try {
        // Check WebSocket ready state
        if (ws.readyState === WebSocket.OPEN) {
          // Check if buffer exists for this socket
          const buffer = this.buffers.get(ws) || [];

          if (buffer.length >= this.MAX_BUFFER_SIZE) {
            // Buffer full - drop oldest messages (or apply other strategy)
            console.warn(`Buffer full for client, dropping old messages`);
            buffer.shift(); // Remove oldest
          }

          // Add to buffer
          buffer.push(payload);
          this.buffers.set(ws, buffer);

          // Try to flush buffer
          this.flushBuffer(ws);
        }
      } catch (error) {
        console.error('Error buffering message:', error);
      }
    }
  }

  private flushBuffer(ws: WebSocket) {
    const buffer = this.buffers.get(ws);
    if (!buffer || buffer.length === 0) return;

    try {
      // Send all buffered messages
      while (buffer.length > 0) {
        const message = buffer.shift();
        ws.send(message);
      }

      // Clear empty buffer
      if (buffer.length === 0) {
        this.buffers.delete(ws);
      }
    } catch (error) {
      console.error('Error flushing buffer:', error);
      // Keep messages in buffer for retry
    }
  }

  async webSocketClose(ws: WebSocket, code: number, reason: string) {
    // Clean up buffer
    this.buffers.delete(ws);
    this.sessions.delete(ws);
    ws.close(code, reason);
  }
}

Sampling Strategy

For high-frequency metrics, you might want to sample instead of sending everything:


  private lastBroadcast: Map<string, number>;
  private readonly MIN_BROADCAST_INTERVAL = 100; // ms

  constructor(state: DurableObjectState, env: Env) {
    this.lastBroadcast = new Map();
  }

  async webSocketMessage(ws: WebSocket, message: string) {
    const data = JSON.parse(message);

    if (data.type === 'metric-update') {
      const metricKey = data.name;
      const now = Date.now();
      const lastTime = this.lastBroadcast.get(metricKey) || 0;

      // Only broadcast if enough time has passed
      if (now - lastTime >= this.MIN_BROADCAST_INTERVAL) {
        this.broadcast({
          type: 'metric-update',
          name: data.name,
          value: data.value,
          timestamp: now
        });

        this.lastBroadcast.set(metricKey, now);
      } else {
        // Update internal state but don't broadcast
        this.metrics.set(data.name, data.value);
      }
    }
  }
}

This ensures clients receive updates at most once per 100ms per metric, preventing overwhelming slow clients.

Production Considerations

Building a production-ready real-time dashboard requires attention to several key areas.

Error Handling


  async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer) {
    try {
      // Always validate input
      if (typeof message !== 'string') {
        throw new Error('Expected string message');
      }

      const data = JSON.parse(message);

      // Validate message structure
      if (!data.type) {
        throw new Error('Message missing type field');
      }

      // Process message
      await this.handleMessage(ws, data);

    } catch (error) {
      console.error('Error processing WebSocket message:', error);

      // Send error to client
      try {
        ws.send(JSON.stringify({
          type: 'error',
          message: error instanceof Error ? error.message : 'Unknown error',
          code: 'PROCESSING_ERROR'
        }));
      } catch (sendError) {
        // Failed to send error - close connection
        console.error('Failed to send error to client:', sendError);
        ws.close(1011, 'Internal error');
      }
    }
  }

  async webSocketError(ws: WebSocket, error: unknown) {
    console.error('WebSocket error:', error);

    // Clean up session
    this.sessions.delete(ws);

    // Close with appropriate code
    try {
      ws.close(1011, 'Unexpected error');
    } catch (closeError) {
      console.error('Error closing WebSocket:', closeError);
    }
  }
}

Rate Limiting

Protect your Durable Object from abusive clients:


  private rateLimits: Map<WebSocket, { count: number; resetTime: number }>;
  private readonly MAX_MESSAGES_PER_MINUTE = 60;

  constructor(state: DurableObjectState, env: Env) {
    this.rateLimits = new Map();
  }

  async webSocketMessage(ws: WebSocket, message: string) {
    // Check rate limit
    if (!this.checkRateLimit(ws)) {
      ws.send(JSON.stringify({
        type: 'error',
        message: 'Rate limit exceeded',
        code: 'RATE_LIMIT'
      }));
      return;
    }

    // Process message normally
    this.handleMessage(ws, message);
  }

  private checkRateLimit(ws: WebSocket): boolean {
    const now = Date.now();
    let limit = this.rateLimits.get(ws);

    if (!limit || now > limit.resetTime) {
      // Create or reset limit
      limit = {
        count: 0,
        resetTime: now + 60000 // 1 minute window
      };
      this.rateLimits.set(ws, limit);
    }

    limit.count++;

    if (limit.count > this.MAX_MESSAGES_PER_MINUTE) {
      return false; // Rate limit exceeded
    }

    return true;
  }

  async webSocketClose(ws: WebSocket, code: number, reason: string) {
    // Clean up rate limit tracking
    this.rateLimits.delete(ws);
    this.sessions.delete(ws);
    ws.close(code, reason);
  }
}

Authentication

Secure your WebSocket connections:

// worker.ts - Validate auth before routing to Durable Object

  async fetch(request: Request, env: Env) {
    const url = new URL(request.url);

    // Extract and verify auth token
    const token = url.searchParams.get('token');
    if (!token) {
      return new Response('Unauthorized', { status: 401 });
    }

    // Verify JWT or session token
    const userId = await verifyAuthToken(token, env);
    if (!userId) {
      return new Response('Invalid token', { status: 403 });
    }

    // Check authorization for this dashboard
    const dashboardId = url.pathname.split('/')[2];
    if (!await canAccessDashboard(userId, dashboardId, env)) {
      return new Response('Forbidden', { status: 403 });
    }

    // Get Durable Object
    const id = env.METRICS_DASHBOARD.idFromName(dashboardId);
    const stub = env.METRICS_DASHBOARD.get(id);

    // Forward request with user context
    const modifiedRequest = new Request(request);
    modifiedRequest.headers.set('X-User-ID', userId);

    return stub.fetch(modifiedRequest);
  }
}

// metrics-dashboard.ts

  async fetch(request: Request): Promise<Response> {
    // Extract authenticated user
    const userId = request.headers.get('X-User-ID');
    if (!userId) {
      return new Response('Unauthorized', { status: 401 });
    }

    // Upgrade to WebSocket
    const pair = new WebSocketPair();
    const [client, server] = Object.values(pair);

    this.state.acceptWebSocket(server);

    // Store user ID with session
    this.sessions.set(server, {
      id: crypto.randomUUID(),
      userId,
      name: `User-${userId}`
    });

    return new Response(null, { status: 101, webSocket: client });
  }
}

Monitoring and Observability

Track key metrics:


  private metrics = {
    totalConnections: 0,
    currentConnections: 0,
    messagesProcessed: 0,
    errorCount: 0,
    hibernationEvents: 0
  };

  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);

    // Expose metrics endpoint
    if (url.pathname === '/metrics') {
      return new Response(JSON.stringify(this.metrics), {
        headers: { 'Content-Type': 'application/json' }
      });
    }

    // WebSocket upgrade
    if (request.headers.get('Upgrade') === 'websocket') {
      this.metrics.totalConnections++;
      this.metrics.currentConnections++;

      // ... handle WebSocket upgrade
    }
  }

  async webSocketClose(ws: WebSocket, code: number, reason: string) {
    this.metrics.currentConnections--;
    // ... cleanup
  }

  async webSocketMessage(ws: WebSocket, message: string) {
    this.metrics.messagesProcessed++;

    try {
      // ... process message
    } catch (error) {
      this.metrics.errorCount++;
      throw error;
    }
  }
}

You can then poll these metrics or integrate with Cloudflare Analytics Engine.

Wrapping Up

We've covered a lot of ground! From understanding Durable Objects to building production-ready real-time dashboards. Here's what we explored:

Durable Objects fundamentals - Stateful serverless computing at the edge
Connection strategies - WebSockets vs SSE vs polling trade-offs
Architecture patterns - How Durable Objects coordinate real-time connections
Hibernation magic - How to save 95%+ on costs with automatic sleep/wake
Production concerns - Error handling, rate limiting, auth, and monitoring

Durable Objects with WebSocket hibernation represent a paradigm shift in real-time architecture. You get:

Global distribution without infrastructure management
Strong consistency without coordination overhead
Persistent connections without constant CPU billing
Automatic scaling without capacity planning

The result? Real-time systems that are simpler to build, cheaper to run, and easier to scale than traditional approaches.

Next Steps

Ready to build your own? Here are some ideas:

Live Collaboration

Collaborative text editor (like Google Docs)
Shared whiteboard or drawing canvas
Multiplayer game state coordination

Real-Time Analytics

Server metrics dashboard (CPU, memory, requests)
Application performance monitoring
Live user activity tracking

Communication

Chat rooms with presence indicators
Live notifications and alerts
Streaming log viewers

Creative Projects

Live music jam sessions
Shared particle simulations
Multiplayer interactive art

The code for all the interactive demos in this article is available on GitHub. Feel free to explore, fork, and build your own real-time experiences!

Give Your Web App a Voice

Fri, 12 Dec 2025 00:00:00 GMT

Introduction

What if your website could literally talk to your users? Not through pre-recorded audio files or complicated audio libraries, but using the voices already built into their browser?

The Web Speech API makes this possible. With just a few lines of JavaScript, you can transform any text into spoken words, customize the voice, pitch, and speed, and even track which word is being spoken in real-time. Try it out:

Pretty cool, right? This technology opens up incredible possibilities: accessibility tools that read content aloud, language learning apps with pronunciation practice, interactive storytelling with character voices, and creative experiments you haven't even imagined yet.

In this article, we'll explore the Speech Synthesis API from the ground up. We'll start with the basics, progressively build up to advanced patterns, and create plenty of interactive demos you can play with along the way. By the end, you'll have all the tools you need to give your web apps a voice.

Browser Compatibility Note: The Speech Synthesis API is supported in modern browsers (Chrome, Safari, Edge, Firefox), but voice availability and behavior can vary significantly across platforms. iOS Safari, for example, has more limited voice options than desktop Chrome. We'll explore these differences throughout this article.

Your First Words: The Basics

The Speech Synthesis API consists of two main pieces: the speechSynthesis object (the controller) and SpeechSynthesisUtterance (the thing being spoken). Think of it like a music player: speechSynthesis is the play/pause/stop controls, while SpeechSynthesisUtterance is the track you want to play.

Here's the absolute simplest example:

// Your browser's built-in text-to-speech
const utterance = new SpeechSynthesisUtterance("Hello, world!");
speechSynthesis.speak(utterance);

That's it! Just two lines of code. Let's break down what's happening:

Create an utterance: new SpeechSynthesisUtterance("Hello, world!") creates a speech request containing the text you want spoken.
Speak it: speechSynthesis.speak(utterance) adds your utterance to the speech queue and starts speaking it.

The speech synthesis system uses a queue, which means if you call speak() multiple times, each utterance will be spoken in order. Think of it like a playlist - one finishes, then the next begins.

Go ahead, modify the text in the playground above and hear how it sounds. The default voice varies by platform, but we'll learn how to choose specific voices later.

Customizing the Voice: Parameters

The default voice is fine, but what if you want to make speech faster, slower, higher, or lower? The SpeechSynthesisUtterance object has three properties you can adjust to customize how the speech sounds.

Pitch

Controls how high or low the voice sounds. The value ranges from 0 to 2, with 1 being the default.

0.5 = Deep, low-pitched voice
1.0 = Normal pitch (default)
1.5 = Higher-pitched, squeakier voice

Rate

Controls the speed of speech. Values range from 0.1 to 10, though most useful values are between 0.5 and 2.

0.5 = Half speed (good for language learning)
1.0 = Normal speed (default)
1.5 = 1.5x speed (like a podcast on fast-forward)

Volume

Controls how loud the voice is. Values range from 0 (silent) to 1 (full volume).

0 = Silent
0.5 = Half volume
1.0 = Full volume (default)

Play with these parameters in the interactive demo below. Notice how different combinations can create wildly different effects:

Using Parameters in Code

Here's how you set these parameters in vanilla JavaScript:

const utterance = new SpeechSynthesisUtterance("I sound different now!");
utterance.pitch = 1.5;  // Higher pitched
utterance.rate = 0.8;   // Slower
utterance.volume = 0.9; // Slightly quieter
speechSynthesis.speak(utterance);

And here's a React component that lets users control these parameters:


function SpeechDemo() {
  const [pitch, setPitch] = useState(1);
  const [rate, setRate] = useState(1);
  const [volume, setVolume] = useState(1);

  const speak = (text: string) => {
    const utterance = new SpeechSynthesisUtterance(text);
    utterance.pitch = pitch;
    utterance.rate = rate;
    utterance.volume = volume;
    speechSynthesis.speak(utterance);
  };

  // UI controls here...
}

Browser Note: Most browsers support the full range of pitch and rate values, but some mobile browsers may clamp these values more aggressively. Safari on iOS, for example, limits how high or low the pitch can go compared to desktop Chrome.

Choosing Voices: The Voice Gallery

So far we've been using the browser's default voice. But most browsers actually provide multiple voices across different languages. Some sound robotic, some sound surprisingly natural, and the selection varies wildly depending on your operating system and browser.

You can get all available voices using speechSynthesis.getVoices():

// Get all available voices
const voices = speechSynthesis.getVoices();

voices.forEach(voice => {
  console.log(voice.name, voice.lang);
});

Try browsing through all the voices available on your device. The number and quality will vary - I get 80+ voices on macOS Chrome, but only a handful on iOS Safari:

Each SpeechSynthesisVoice object has several properties:

name: The voice's name (e.g., "Alex", "Samantha", "Google US English")
lang: The language code (e.g., "en-US", "es-ES", "ja-JP")
localService: Boolean indicating if the voice is on-device (true) or requires network (false)
default: Boolean indicating if this is the system's default voice

The voiceschanged Gotcha

Here's something that trips up a lot of developers: voices load asynchronously in most browsers. If you try to get voices immediately when your page loads, you'll often get an empty array:

// Wrong: voices might not be loaded yet!
const voices = speechSynthesis.getVoices(); // Often returns []
console.log(voices.length); // 0 😢

The solution is to wait for the voiceschanged event:

// Right: wait for the event
speechSynthesis.addEventListener('voiceschanged', () => {
  const voices = speechSynthesis.getVoices();
  console.log('Voices loaded:', voices.length); // 80 🎉
});

In React, you'd typically handle this in a useEffect:

useEffect(() => {
  const loadVoices = () => {
    const availableVoices = speechSynthesis.getVoices();
    setVoices(availableVoices);
  };

  // Load voices immediately (works in some browsers)
  loadVoices();

  // Also listen for the voiceschanged event (required in others)
  speechSynthesis.addEventListener('voiceschanged', loadVoices);

  return () => {
    speechSynthesis.removeEventListener('voiceschanged', loadVoices);
  };
}, []);

This approach covers both bases: it tries to load voices immediately (works in Firefox and Safari) and also listens for the event (required in Chrome and Edge).

Lifecycle Events: Controlling Playback

Speech isn't just fire-and-forget. The SpeechSynthesisUtterance object fires events throughout its lifecycle, allowing you to track when speech starts, ends, encounters errors, or even which word is currently being spoken.

The Event Lifecycle

Each utterance can emit several events:

onstart - Fired when speech begins
onend - Fired when speech completes
onerror - Fired if something goes wrong
onpause - Fired when speech is paused
onresume - Fired when speech resumes after pause
onboundary - Fired at word/sentence boundaries (not supported in all browsers)

Here's a basic example in vanilla JavaScript:

const utterance = new SpeechSynthesisUtterance("Track my lifecycle!");

utterance.onstart = () => console.log('Started speaking');
utterance.onend = () => console.log('Finished speaking');
utterance.onerror = (event) => console.error('Error:', event.error);

speechSynthesis.speak(utterance);

Interactive Demo

Try the interactive demo below. Click "Speak" and watch the event log populate in real-time. Try pausing and resuming to see how those events fire:

The onboundary event is particularly interesting - it fires at word boundaries, giving you the character index and length of each word. You can use this to highlight words as they're spoken, create karaoke-style effects, or track reading progress. Unfortunately, not all browsers support it (Firefox and Safari notably don't).

Building a Reusable Hook

Rather than wiring up all these events every time, let's create a reusable React hook. This is exactly what all the interactive demos in this article use:

// useSpeechSynthesis.ts

  const [voices, setVoices] = useState<SpeechSynthesisVoice[]>([]);
  const [speaking, setSpeaking] = useState(false);
  const [paused, setPaused] = useState(false);

  // Load voices (handling the async gotcha)
  useEffect(() => {
    const loadVoices = () => {
      setVoices(speechSynthesis.getVoices());
    };
    loadVoices();
    speechSynthesis.addEventListener('voiceschanged', loadVoices);
    return () => {
      speechSynthesis.removeEventListener('voiceschanged', loadVoices);
    };
  }, []);

  const speak = useCallback((text: string, options = {}) => {
    speechSynthesis.cancel(); // Clear queue
    const utterance = new SpeechSynthesisUtterance(text);

    // Apply options
    if (options.voice) utterance.voice = options.voice;
    if (options.pitch) utterance.pitch = options.pitch;
    if (options.rate) utterance.rate = options.rate;
    if (options.volume) utterance.volume = options.volume;

    // Attach event handlers
    utterance.onstart = () => {
      setSpeaking(true);
      options.onStart?.();
    };
    utterance.onend = () => {
      setSpeaking(false);
      options.onEnd?.();
    };
    utterance.onerror = (event) => {
      console.error('Speech error:', event);
      setSpeaking(false);
      options.onError?.(event);
    };

    speechSynthesis.speak(utterance);
  }, []);

  const cancel = useCallback(() => {
    speechSynthesis.cancel();
    setSpeaking(false);
  }, []);

  return { speak, cancel, voices, speaking, paused };
}

Now using speech synthesis becomes much simpler:

// In your component
const { speak, voices, speaking, cancel } = useSpeechSynthesis();

// Speak with custom options
speak("Hello!", {
  voice: voices[0],
  pitch: 1.2,
  rate: 1.0,
  onEnd: () => console.log('Done!')
});

This hook handles voice loading, state management, and provides a clean API for all our needs. All the interactive demos in this article use this same hook - we're not reinventing the wheel for each one!

Creative Use Cases

Now that you understand the fundamentals, let's explore some creative applications. The Speech Synthesis API opens up possibilities that go far beyond simple text-to-speech.

Interactive Storytelling

Imagine a choose-your-own-adventure story where different characters have distinct voices. By switching between voices and adjusting parameters, you can create immersive, dynamic narratives:

// Character voice switching example
const narrator = voices.find(v => v.name.includes('Alex'));
const character = voices.find(v => v.name.includes('Samantha'));

function speakDialogue(text, isNarrator) {
  const utterance = new SpeechSynthesisUtterance(text);
  utterance.voice = isNarrator ? narrator : character;
  utterance.pitch = isNarrator ? 1.0 : 1.3;
  speechSynthesis.speak(utterance);
}

// Usage
speakDialogue("Once upon a time...", true);
speakDialogue("Help! A dragon!", false);

You could take this further by:

Using the onboundary event to highlight text as it's spoken
Synchronizing animations with speech events
Letting users skip ahead by canceling the current utterance
Creating voice-activated choices using the Speech Recognition API

Language Learning

The Speech Synthesis API is perfect for language learning applications. By controlling the rate and selecting native voices for different languages, you can create pronunciation practice tools:

// Language learning helper
function pronunciationPractice(word, language = 'es-ES') {
  const voice = voices.find(v => v.lang === language);

  // Slow version for learning
  const slow = new SpeechSynthesisUtterance(word);
  slow.voice = voice;
  slow.rate = 0.6;

  // Normal speed version
  const normal = new SpeechSynthesisUtterance(word);
  normal.voice = voice;
  normal.rate = 1.0;

  // Speak slow first, then normal
  speechSynthesis.speak(slow);
  slow.onend = () => speechSynthesis.speak(normal);
}

// Try it
pronunciationPractice("¡Hola! ¿Cómo estás?", "es-ES");

This pattern works great for:

Vocabulary flashcards with audio
Accent comparison (compare English voice saying Spanish words vs native Spanish voice)
Pronunciation drills that repeat words at adjustable speeds
Interactive lessons that respond to user progress

Creative & Experimental

Speech synthesis can be an artistic medium. By randomizing parameters and using the event system creatively, you can create generative audio art:

// Generative poetry reader with random parameters
function readPoetically(text) {
  const lines = text.split('\n');

  lines.forEach((line, i) => {
    const utterance = new SpeechSynthesisUtterance(line);

    // Random voice parameters for artistic effect
    utterance.pitch = 0.8 + Math.random() * 0.8;  // 0.8-1.6
    utterance.rate = 0.7 + Math.random() * 0.6;   // 0.7-1.3

    // Add delay between lines
    setTimeout(() => {
      speechSynthesis.speak(utterance);
    }, i * 2000);
  });
}

// Read a poem with varying voice characteristics
const poem = `Roses are red
Violets are blue
This poem sounds weird
Because pitch is askew`;

readPoetically(poem);

Other creative ideas:

Voice-based games: Speak clues in a mystery game, or have enemies taunt players
Data sonification: "Speak" numbers from charts to make data more accessible
Generative music: Use speech as a rhythmic or melodic element
Interactive art: Create installations that respond to user input with synthesized speech

The key is experimentation. Try combining speech with other web APIs - like the Web Audio API for effects, Canvas for visualizations, or Gamepad API for voice-controlled games.

Browser Compatibility & Gotchas

The Speech Synthesis API is widely supported, but with significant differences in implementation quality and available features. Let's dig into the details so you know what to expect.

Support Matrix

Here's a breakdown of feature support across major browsers:

Feature	Chrome	Firefox	Safari	Edge	iOS Safari	Android Chrome
Basic synthesis	✅	✅	✅	✅	✅	✅
Voice selection	✅	✅	⚠️ Limited	✅	⚠️ Very Limited	✅
Full pitch/rate range	✅	✅	⚠️ Clamped	✅	⚠️ Clamped	✅
`onboundary` event	✅	❌	❌	✅	❌	✅
`pause()`/`resume()`	✅	✅	✅	✅	⚠️ Buggy	✅

✅ = Fully supported ⚠️ = Partially supported or has quirks ❌ = Not supported

Platform-Specific Quirks

iOS Safari

iOS Safari has the most limitations:

Very few voices: Often just 2-3 voices available (compared to 80+ on desktop)
Requires user interaction: Speech won't work until the user has interacted with the page (click, tap, etc.)
No background playback: Speech stops when the app is backgrounded
Parameter clamping: Pitch and rate values are more restricted than on desktop
Pause/resume issues: The pause() and resume() methods can be unreliable

// iOS-friendly pattern: trigger speech from a user event
button.addEventListener('click', () => {
  const utterance = new SpeechSynthesisUtterance("Hello!");
  speechSynthesis.speak(utterance);
});

Android

Android's implementation varies based on the system TTS engine:

System-dependent voices: Voice quality and selection depend on what TTS engines the user has installed
Google voices are common: Most Android devices have Google TTS pre-installed
Generally good support: Most features work as expected on modern Android versions

Desktop Browsers

Desktop browsers generally have the best support:

Chrome/Edge: Excellent support, extensive voice libraries (Google voices + system voices)
Firefox: Good support, but lacks onboundary event
Safari: Good support, but limited to system voices (high quality, but fewer options)

Common Gotchas

1. Voice Loading Timing

We covered this earlier, but it's worth repeating: voices load asynchronously in most browsers. Always use the voiceschanged event:

speechSynthesis.addEventListener('voiceschanged', () => {
  const voices = speechSynthesis.getVoices();
  // Now you can use voices
});

2. Queue Behavior

The speech queue can sometimes get stuck, especially when rapidly calling speak() multiple times. Always cancel before speaking new text:

// Clear the queue if things get stuck
speechSynthesis.cancel();

// Then speak your new text
const utterance = new SpeechSynthesisUtterance("New text");
speechSynthesis.speak(utterance);

3. User Interaction Requirements

Many mobile browsers (especially iOS Safari) require user interaction before allowing speech synthesis. This is similar to autoplay restrictions for video and audio:

// This might not work on page load
speechSynthesis.speak(new SpeechSynthesisUtterance("Hello!"));

// This will work after a user click
button.addEventListener('click', () => {
  speechSynthesis.speak(new SpeechSynthesisUtterance("Hello!"));
});

4. Long Text Truncation

Some browsers (notably Chrome on some platforms) may cut off text after ~200-300 characters. The workaround is to chunk your text:

// Workaround: chunk long text
function speakLongText(text) {
  // Split into ~200 character chunks at sentence boundaries
  const chunks = text.match(/.{1,200}/g) || [text];

  chunks.forEach((chunk, i) => {
    const utterance = new SpeechSynthesisUtterance(chunk);
    if (i === chunks.length - 1) {
      utterance.onend = () => console.log('Complete!');
    }
    speechSynthesis.speak(utterance);
  });
}

5. Rate Limits

Some browsers may rate-limit or restrict speech synthesis if called too frequently. Be mindful of how often you're triggering speech, especially in response to user input.

Feature Detection & Fallbacks

Always check for browser support before using the API:

if ('speechSynthesis' in window) {
  // Use speech synthesis
  const utterance = new SpeechSynthesisUtterance(text);
  speechSynthesis.speak(utterance);
} else {
  // Fallback: show text in a modal, use audio files, etc.
  showTextFallback(text);
}

You can also check for specific features:

// Check if onboundary is supported
const utterance = new SpeechSynthesisUtterance();
const hasBoundary = 'onboundary' in utterance;

if (hasBoundary) {
  // Use word highlighting features
} else {
  // Skip word-by-word tracking
}

The key takeaway: test your implementation across different platforms, especially if you're targeting mobile users. What works perfectly on desktop Chrome might need adjustments for iOS Safari.

Wrapping Up

We've covered a lot of ground! From the basics of creating your first utterance to advanced patterns with event handling, voice selection, and creative applications. Here's what we explored:

The fundamentals: How speechSynthesis and SpeechSynthesisUtterance work together
Customization: Adjusting pitch, rate, and volume to create different effects
Voice selection: Browsing and choosing from available voices (and handling the async loading quirk)
Events: Tracking speech lifecycle with onstart, onend, onboundary, and other events
Creative applications: Interactive storytelling, language learning, and experimental uses
Browser quirks: Platform-specific limitations and workarounds

The Speech Synthesis API is just one half of the Web Speech API. The other half is the Speech Recognition API, which does the opposite - it listens to spoken words and converts them to text. Combine both, and you can create fully voice-interactive applications.

This technology is mature enough for production use, but remember to:

Test across multiple browsers and devices
Provide fallbacks for unsupported browsers
Consider accessibility implications
Respect user preferences (some users may find unexpected speech jarring)

Resources

Want to dive deeper? Here are some helpful resources:

Adding Estimated Reading Time to an Astro Blog

Mon, 08 Dec 2025 00:00:00 GMT

Reading time estimates have become a standard UX feature on modern blogs. They set reader expectations, help people decide if they have time to read an article, and improve engagement. Adding this feature to an Astro blog is straightforward and can be done with a simple utility function and a reusable component.

The Core Algorithm

The foundation of reading time estimation is a utility function that counts words and calculates reading duration. The standard approach assumes readers process about 200 words per minute.

/**
 * Calculate estimated reading time for text content
 * @param content - Raw markdown or text content
 * @param wordsPerMinute - Reading speed (default: 200 wpm)
 * @returns Object with minutes and display string
 */

  content: string,
  wordsPerMinute = 200
): { minutes: number; display: string } {
  // Remove markdown syntax, code blocks, and extra whitespace
  const cleanContent = content
    .replace(/```[\s\S]*?```/g, '') // Remove code blocks
    .replace(/`[^`]*`/g, '') // Remove inline code
    .replace(/[#*_~[\]()]/g, '') // Remove markdown symbols
    .replace(/\s+/g, ' ') // Normalize whitespace
    .trim()

  // Count words
  const wordCount = cleanContent.split(/\s+/).length

  // Calculate reading time
  const minutes = Math.ceil(wordCount / wordsPerMinute)

  // Format display string
  const display = minutes < 1 ? '< 1 min read' : `${minutes} min read`

  return { minutes, display }
}

The function handles several important considerations:

Stripping Markdown: Code blocks and inline code shouldn't count toward word count since they're not prose. Similarly, markdown syntax characters are removed to get accurate word counts.

Whitespace Normalization: Multiple spaces or newlines are collapsed into single spaces to ensure consistent word splitting.

Rounding: Using Math.ceil rounds up, so even a 201-word article shows "2 min read" rather than "1 min read". This errs on the side of giving readers slightly more time than needed.

Return Format: The function returns both the numeric minutes and a formatted display string for flexibility in how you present the information.

The Display Component

With the calculation logic in place, a small Astro component handles rendering the reading time consistently across your blog:

---
interface Props {
  minutes: number
  display?: string
  className?: string
}

const { minutes, display, className = 'text-sm tracking-wide text-slate-700 dark:text-slate-500' } = Astro.props

// Generate display string if not provided
const readingTimeText = display ?? (minutes < 1 ? '< 1 min read' : `${minutes} min read`)
---

<span class={className}>{readingTimeText}</span>

This component is intentionally simple. It accepts:

minutes: The calculated reading time
display: Optional pre-formatted display string (useful if you want custom text)
className: Optional custom Tailwind classes for styling flexibility

By keeping the component minimal and reusable, you can drop it into any location in your blog layout without duplication.

Integration with Your Blog

The real benefit comes from integrating this into your Astro Content Collections. When you fetch blog posts using getCollection('blogPosts'), each entry includes the raw markdown content in its body property.

In your blog listing page, calculate reading time for each post:

const blogPostsWithReadingTime = blogPosts.map(post => ({
  ...post,
  readingTime: calculateReadingTime(post.body)
}))

Then display it alongside the publish date. On individual post pages, add the reading time to the hero header where you show the title and date.

The Benefits

This approach offers several advantages:

Build-time Calculation: Reading time is calculated once during the build, not on every page load. There's zero runtime overhead.
Accurate for Your Content: You can adjust the words-per-minute parameter for your audience if needed. Technical audiences might read slower, while shorter content might skew differently.
Flexible Presentation: The component accepts custom classes, so you can style reading time differently in various locations (subtle on listings, prominent on individual posts).
Accessible: The calculation is based on actual word count from your markdown, not arbitrary estimates, making it reliable and consistent across your blog.

Adding reading time to your blog is a small feature that makes a meaningful difference in reader experience. With Astro's content collections and a simple utility function, it requires surprisingly little code.

Advanced VSCode Search: Finding Function Calls While Excluding Variable Assignments

Thu, 06 Feb 2025 00:00:00 GMT

As developers, we often need to search through our codebase for specific patterns. One common scenario is finding function calls while filtering out variable assignments. In this post, I'll walk you through creating a powerful VSCode search query that finds prefetch function calls while excluding lines that contain assignments.

The Challenge

Imagine you're working on a large codebase and need to find all the places where prefetch functions are being called directly, but you want to exclude cases where the result is being assigned to a variable or an arrow function declaration..

You want to find lines like:

prefetchData()
await prefetchUser(userId)
this.prefetchCache()

But exclude lines like:

const data = prefetchData()
let user = await prefetchUser(userId)
this.cache = prefetchCache()

The Solution

Here's the regex pattern that accomplishes this:

^(?!.*=).*prefetch.*\(

Breaking Down the Pattern

Let's dissect this regex step by step:

^ - Anchors the pattern to the start of the line
(?!.*=) - This is a negative lookahead that ensures there's no equal sign (=) anywhere on the line
.* - Matches any characters (except newline) before "prefetch"
prefetch - Matches the literal text "prefetch"
.* - Matches any characters between "prefetch" and the opening parenthesis
\( - Matches a literal open parenthesis (escaped because ( has special meaning in regex)

How to Use It in VSCode

Open the search panel: Press Ctrl+Shift+F (Windows/Linux) or Cmd+Shift+F (Mac)
Enable regex mode: Click the regex icon (.*) in the search box or press Alt+R
Enter the pattern: Type ^(?!.*=).*prefetch.*\(
Search: Press Enter to find all matches

Understanding Negative Lookahead

The key component here is the negative lookahead (?!.*=). This is a powerful regex feature that:

Looks ahead in the string without consuming characters
Asserts that what follows doesn't match the specified pattern
In our case, it ensures that nowhere on the current line (.*=) there's an equal sign

Real-World Examples

This pattern will match:

// ✅ Direct function calls
prefetchData()
await prefetchUser(123)
component.prefetchResources()
this.prefetchCache()

// ✅ Function calls in conditions
if (prefetchData()) {
    // ...
}

// ✅ Function calls as arguments
doSomething(prefetchUser(id))

But will exclude:

// ❌ Variable assignments
const result = prefetchData()
let user = await prefetchUser(123)
this.data = prefetchCache()

// ❌ Object property assignments
obj.prop = prefetchSomething()

Extending the Pattern

You can easily modify this pattern for other use cases:

Find any function call (not just prefetch):

^(?!.*=).*\w+.*\(

Exclude multiple operators (assignment and comparison):

^(?!.*[=<>]).*prefetch.*\(

Case-insensitive search:

Add the i flag or use (?i) at the beginning:

^(?!.*=).*(?i)prefetch.*\(

Tips for Complex Searches

Test your regex: Use online regex testers like regex101.com to validate your patterns
Use word boundaries: Add \b around words to avoid partial matches
Escape special characters: Remember to escape characters like (, ), [, ], etc.
Save frequent searches: VSCode allows you to save search queries for reuse

Have you used similar search patterns in your development workflow? Share your favorite VSCode search tips in the comments below!

Simplifying VSCode

Sun, 11 Jun 2023 00:00:00 GMT

Introduction

As a long-time user of Visual Studio Code (VSCode), I've accumulated a vast array of extensions, settings, and files that have made my workspace cluttered and overwhelming. I found myself spending more time searching for files and navigating through menus than actually coding. It was time for a change.

In this blog post, I'll share my experience of cleaning up and simplifying my VSCode workspace. I'll discuss the steps I took to remove unused extensions, organize my files, customize settings, and use keyboard shortcuts and snippets to streamline my workflow. By the end of this post, you'll have a better understanding of how to optimize your workspace and improve your coding experience. So, let's dive in!

Extensions I Removed

codecrumbs-vs-code - Never used it after the first few weeks of installing
Codetour - Same as above
Import Cost - I use Bundlephobia for this instead
Playwright Test for VSCode - I use Playwright's UI mode for this functionality now
Polacode - I use ray.so instead now
ReacTree - Seemed cool when I looked at it, but I've never had a use case for it
Remove Non ASCII Chars - The linting tools I use already handles this

Status Bar Sections Removed

Workspace Trust
GitLens Commit Graph
Problems
Editor Selection
Editor Indentation
Editor Encoding
Editor End of Line
Editor Language Status
Editor Language
Prettier
Feedback
Notifications

Sidebar Icons Removed

After years of use, the sidebar in VSCode can become cluttered with icons, making it difficult to navigate and find what you need. To simplify my workspace, I recently removed the below sidebar icons:

Run and Debug
Extensions
GitLab Workflow
GitLens
TODOs
Bookmarks
Accounts

Conclusion

In conclusion, by removing unused extensions, status bar sections, and sidebar icons, as well as organizing files, customizing settings, and using keyboard shortcuts and snippets, I was able to simplify my VSCode workspace and improve my coding experience. It's important to regularly review and optimize your workspace to ensure that it remains efficient and clutter-free.

Updating from @sveltejs/kit@1.0.0-next.350 to @sveltejs/kit@1.0.0-next.403

Sat, 06 Aug 2022 00:00:00 GMT

TLDR: Here's the commit that I made all code changes in

I recently updated the version of sveltekit I'm using for qr-gen, and it was quite the experience :). There's not much documentation out there (at least that I could find), so I'm documenting what I needed to change here.

Update dependencies

yarn add @sveltejs/kit@latest @sveltejs/adapter-auto@latest --exact

Note: if you're using any other packages under the @sveltejs org, you'll likely need to update those as well.

Add vite.config.js

Next, I needed to create vite.config.js in the root of the repo and add the svelte-kit plugin to the config:


/** @type {import('vite').UserConfig} */
const config = {
  plugins: [sveltekit()]
}

You'll also need to remove any configuration you have under the kit.vite property in svelte.config.js. Consulting the vite configuration docs should be helpful here.

Update API Routes to Use Uppercase Method Names

Updating export const post to export const POST (and so forth for other request methods)

Resolving ERR_IMPORT_ASSERTION_TYPE_MISSING in Node.js

Sat, 04 Jun 2022 00:00:00 GMT

While working on a CLI, I ran into the below error when trying to import `package.json` to read the package name and version:

TypeError [ERR_IMPORT_ASSERTION_TYPE_MISSING]: Module "file:///Users/Andrew.Usher/code/gh/andrewusher/andrewusher.dev/package.json" needs an import assertion of type "json"


const { name, version } = pkgInfo


  name,
  version
}

To resolve the issue, we need to use the [import assertions syntax](https://github.com/tc39/proposal-import-assertions) to tell Node that this is a JSON module:

import pkgInfo from '../package.json' assert { type: 'json' }

const { name, version } = pkgInfo


  name,
  version
}

offsetHeight/scrollHeight/clientHeight: What's The Difference?

Sun, 22 May 2022 00:00:00 GMT

While working on a scrolling progress bar for my portfolio site, I ran into some issues trying to find out the small differences between offsetHeight, clientHeight, and scrollHeight on a given element. Here's a brief description of each one:

clientHeight

clientHeight can be calculated as: CSS height + CSS padding - height of horizontal scrollbar (if present)

scrollHeight

The scrollHeight value is equal to the minimum height the element would require in order to fit all the content in the viewport without using a vertical scrollbar. The height is measured in the same way as clientHeight: it includes the element's padding, but not its border, margin or horizontal scrollbar (if present)

offsetHeight

offsetHeight is a measurement in pixels of the element's CSS height, including any borders, padding, and horizontal scrollbars (if rendered). It does not include the height of pseudo-elements such as ::before or ::after

How To Use Default Function Parameter Values In JS

Sat, 07 May 2022 00:00:00 GMT

Function parameters are undefined by default in JavaScript. Sometimes, you want to define a default parameter in this case. Before ES6 (also known as ES2015), creating default paramaters was a little tedious:

function createName(firstName, lastName) {
  firstName = typeof firstName === 'undefined' ? 'Jane' : firstName;
  secondName = typeof secondName === 'undefined' ? 'Doe' : secondName;

  return firstName + ' ' + secondName;
}

console.log(createName()); // Jane Doe

With the introduction of default parameter values in ES6, the above could be simplified to:

function createName(firstName = 'Jane', lastName = 'Doe') {  
  return firstName + ' ' + secondName;
}

console.log(createName()); // Jane Doe

NPM Needs: snarkdown

Sun, 10 Apr 2022 00:00:00 GMT

What Is It?

snarkdown is a barebones markdown parser with the sole purpose of converting markdown to HTML. This could be used in cases where you don't need a full fledged tool like marked or remark

Usage Examples


console.log(snarkdown('# Hello World'))
// '<h1>Hello World</h1>'

More Info

Github Repo: developit/snarkdown
Author: Jason Miller

NPM Needs: pretty-bytes

Sat, 09 Apr 2022 00:00:00 GMT

What Is It?

pretty-bytes is a utility used to convert an integer form of bytes to a more human readable form (bytes to kilobytes, for example). pretty-bytes-cli is a command line wrapper for the same package.

Usage Examples


prettyBytes(100)
// '100 B'
prettyBytes(1650)
// '1.65 kB'

More Info

Github Repo: sindresorhus/pretty-bytes
Author: Sindre Sorhus

A Fastify Quickstart

Wed, 05 Jan 2022 00:00:00 GMT

This post will cover instantiating a basic server using fastify.

Getting Started

First, we'll need to setup a new folder for this project. Open up a terminal, and type these commands to get setup.

mkdir fastify-quickstart
cd fastify-quickstart
npm init -y

Installing Fastify

After that, we need to install fastify with the below command:

npm i fastify

TLDR: The Code

For some quick code to copy and paste, the snippet below will be enough to get you started:

// server.js
const fastify = require('fastify')({ logger: true })

fastify.get('/', async (request, reply) => {
  return {
    message: 'Hello World!'
  }
})

const startServer = async () => {
  try {
    await fastify.listen(3000)
  } catch (err) {
    fastify.log.error(err)
    process.exit(1)
  }
}

startServer()

To run the server now, type node server.js in your terminal.

You can test that things are working as expected by running curl in your terminal.

> curl http://localhost:3000
{"message":"Hello World!"}

For more info on additional methods, configuration, etc., take a look at the Fastify documentation!

Web Pointer Events

Sat, 14 Aug 2021 00:00:00 GMT

Pointing at things on the web used to be simple. You had a mouse, you moved it around, sometimes you pushed buttons, and that was it. But this, doesn't work so well on here.

Touch events are good, but to support touch and mouse, you had to support two event models:

elem.addEventListener('mousemove', mouseMoveEvent);
elem.addEventListener('touchmove', touchMoveEvent);

Chrome now enables unified input handling by dispatching PointerEvents:

elem.addEventListener('pointermove', pointerMoveEvent);

Pointer events unify the pointer input model for the browser, bringing touch, pens, and mice together into a single set of events. They're supported in IE11, Edge, Chrome, Opera and partially supported in Firefox.

useWindowSize

Sat, 06 Feb 2021 00:00:00 GMT

A really common need is to get the current size of the browser window. This hook returns an object containing the window's width and height. If executed server-side (no window object) the value of width and height will be undefined.


const Example = () => {
  const { height, width } = useWindowSize()

  return (
    <div>
      {width}px / {height}px
    </div>
  )
}

// Hook
function useWindowSize() {
  const isBrowser = typeof window !== 'undefined'

  const getSize = () => ({
    width: isBrowser ? window.innerWidth : undefined,
    height: isBrowser ? window.innerHeight : undefined,
  })

  const handleResize = () => {
    setWindowSize(getSize())
  }

  const [windowSize, setWindowSize] = useState(getSize)

  useEffect(() => {
    if (!isBrowser) return
    window.addEventListener('resize', handleResize)
    return () => window.removeEventListener('resize', handleResize)
  }, [])

  return windowSize
}

Lost Some Commits I Know I Made

Sat, 23 Feb 2019 00:00:00 GMT

First make sure that it was not on a different branch. Try git log -Sbar --all where "bar" is replaced with something unique in the commits you made. You can also search with gitk --all --date-order to see if anything looks likely.Check your stashes, git stash list, to see if you might have stashed instead of committing. You can also visualize what the stashes might be associated with via:

gitk --all --date-order $(git stash list | awk -F: '{print $1};')

Next, you should probably look in other repositories you have lying around including ones on other hosts and in testing environments, and in your backups.Once you are fully convinced that it is well and truly lost, you can start looking elsewhere in git. Specifically, you should first look at the reflog which contains the history of what happened to the tip of your branches for the past two weeks or so. You can of course say git log -g or git reflog to view it, but it may be best visualized with:

gitk --all --date-order $(git reflog --pretty=%H)

Next you can look in git's lost and found. Dangling commits get generated for many good reasons including resets and rebases. Still those activities might have mislaid the commits you were interested in. These might be best visualized with gitk --all --date-order $(git fsck | grep "dangling commit" | awk '{print $3;}')The last place you can look is in dangling blobs. These are files which have been git added but not attached to a commit for some (usually innocuous) reason. To look at the files, one at a time, run:

git fsck | grep "dangling blob" | while read x x s; do git show $s | less; done

Once you find the changes you are interested in, there are several ways you can proceed. You can git reset --hard SHA your current branch to the history and current state of that SHA (probably not recommended for stashes), you can git branch newbranch SHA to link the old history to a new branch name (also not recommended for stashes), you can git stash apply SHA (for the non-index commit in a git-stash), you can git stash merge SHA or git cherry-pick SHA (for either part of a stash or non-stashes), etc.

Edit Styles Inline On A Page

Tue, 19 Feb 2019 00:00:00 GMT

<style contenteditable style="display: block; white-space: pre;">

Reverting A Merge Commit

Wed, 23 Jan 2019 00:00:00 GMT

Oh dear. This is going to get complicated.To create an positive commit to remove the effects of a merge commit, you must first identify the SHA of the commit you want to revert. You can do this using gitk --date-order or using git log --graph --decorate --oneline

You are looking for the 40 character SHA-1 hash ID (or the 7 character abbreviation). Yes, if you know the "^" or "~" shortcuts you may use those.Undoing the file modifications caused by the merge is about as simple as you might hope. git revert -m 1 SHA. (replace "SHA" with the reference you want to revert; -m 1 will revert changes from all but the first parent, which is almost always what you want.) Unfortunately, this is just the tip of the iceberg.

The problem is, what happens months later, long after you have exiled this problem from your memory, when you try again to merge these branches (or any other branches they have been merged into)? Because git has it tracked in history that a merge occurred, it is not going to attempt to remerge what it has already merged, and even worse, if you merge from the branch where you did the revert you will undo the changes on the branch where they were made. (Imagine you revert a premature merge of a long-lived topic branch into master and later merge master into the topic branch to get other changes for testing.)One option is actually to do this reverse merge immediately, annihilating any changes before the bad merge, and then to "revert the revert" to restore them. This leaves the changes removed from the branch you mistakenly merged to, but present on their original branch, and allows merges in either direction without loss. This is the simplest option, and in many cases, can be the best.A disadvantage of this approach is that git blame output is not as useful (all the changes will be attributed to the revert of the revert) and git bisect is similarly impaired. Another disadvantage is that you must merge all current changes in the target of the bad merge back into the source; if your development style is to keep branches clean, this may be undesirable, and if you rebase your branches (e.g. with git pull --rebase), it could cause complications unless you are careful to use git rebase -p to preserve merges.In the following example please replace $destination with the name of the branch that was the destination of the bad merge, $source with the name of the branch that was the source of the bad merge, and $sha with the SHA-1 hash ID of the bad merge itself.

git checkout $destination
git revert $sha
# save the SHA-1 of the revert commit to un-revert it later
revert=`git rev-parse HEAD`
git checkout $source
git merge $destination
git revert $revert

Another option is to abandon the branch you merged from, recreate it from the previous merge-base with the commits since then rebased or cherry-picked over, and use the recreated branch from now on. Then the new branch is unrelated and will merge properly. Of course, if you have pushed the donor branch you cannot use the same name (that would be rewriting public history and is bad) so everyone needs to remember to use the new branch. Hopefully you have something like gitolite where you can close the old branch name.

This approach has the advantage that the recreated donor branch will have cleaner history, but especially if there have been many commits (and especially merges) to the branch, it can be a lot of work. At this time, I will not walk you through the process of recreating the donor branch. Given sufficient demand I can try to add that. However, if you look at howto/revert-a-faulty-merge.txt (also shipped as part of the git distribution) it will provide more words than you can shake a stick at.

React Aha Moments

Tue, 22 Jan 2019 00:00:00 GMT

How using immutable objects as props can make shouldComponentUpdate super fast for pure components, even when you need complicated hierarchical objects
That render function is called before componentDidMount
You don't need to have any data-flow package (flux, redux, mobx, etc) unless your components need to share state
Your UI is a function of your state
That when two components need to share state I need to lift it up instead of trying to keep their states in sync
Components don’t necessarily have to correspond to DOM nodes

Recovering From A Bad Rebase

Thu, 29 Nov 2018 00:00:00 GMT

So, you were in the middle of a rebase, have encountered one or more conflicts, and you have now decided that it was a big mistake and want to get out of the merge.The fastest way out of the merge is:

git rebase --abort

setState: a function??

Fri, 19 Oct 2018 00:00:00 GMT

Components in React are independent and reusable pieces of code that often contain their own state. They return React elements that make up the UI of an application. Components that contain local state have a property called state When we want to change our how application looks or behaves, we need to change our component’s state. So, how do we update the state of our component? React components have a method available to them called setState Calling this.setState causes React to re-render your application and update the DOM.

Normally, when we want to update our component we just call setState with a new value by passing in an object to the setState function:

this.setState({ someField: someValue })

But, often there is a need to update our component’s state using the current state of the component. Directly accessing this.state to update our component is not a reliable way to update our component’s next state. From the React documentation:

Because this.props and this.state may be updated asynchronously, you should not rely on their values for calculating the next state.

The key word from that documentation is asynchronously. Updates to the DOM don’t happen immediately when this.setState is called. React batches updates so elements are re-rendered to the DOM efficiently.

Function in setState!

Instead of passing in an object to this.setState we can pass in a function and reliably get the value of the current state of our component:

this.setState((prevState) => ({
  someBool: !prevState.someBool,
}))

Passing in a function into setState instead of an object will give you a reliable value for your component’s state and props. If you know you’re going to use setState to update your component and you know you’re going to need the current state or the current props of your component to calculate the next state, passing in a function as the first parameter of this.setState instead of an object is the recommended solution.

Bucket List

Thu, 20 Sep 2018 00:00:00 GMT

South Park Escape Room
See the Mona Lisa
Visit a Castle
Go On A Cruise
Fly In A Helicopter
Meet Dan Abramov
~~Fly First Class~~
Live In A Different Country
Fly a Kite
Grow A Tree
Backpack to 10 Places
Run A Marathon
Take Part in Triathlon
Go Scuba Diving
Walk the Inca Trail
Climb a Mountain
Fly in A Hot Air Balloon
Volcano Boarding
Go to Google Headquarters

Advice For Me 10 Years Ago

Tue, 29 May 2018 00:00:00 GMT

Just follow your passion. I think working in different environments is very important. It helps you to gain experience and find your interests and passions. Looking back, it makes a lot of sense, but I would have never imagined where I would end up.

Regular Expression Additions in ES 2018

Thu, 24 May 2018 00:00:00 GMT

Javascript has really come a long way in the past couple of years. With the now yearly updates of the language, there is always a lot of new things to learn. Something that is being added in 2018 is major improvements to regular expressions in JavaScript.

If you are a complete beginner to regular expressions, this article can widen your understanding of the practical use of regular expressions. If, however, you do have at least an average knowledge of regular expressions, this article can get you caught up with new capabilities of regular expressions in JS.

Is Regex Finally Powerful In JS?

It doesn't have everything under the regex sun now, but JS has significantly closed the gap between its own engine and other PCRE-based regex engines. The new updates are geared towards practical use cases:

Dotall Flag
Named Capture Groups
Unicode Escapes
Lookbehinds

Dotall Flag

This is a pretty simple update that was added. In Javascript and many other PCRE regular expressions, newline characters like \n does not match the dot.

// Newline character does not match dot
const regex = /./.regex.test('\n')
// > false

When we test it, the test returns false. However, adding an s flag in ES2018 matches the newline character in addition to the carriage return, line seperator, and paragraph seperator characters:

// Dotall flag
let regex = /./s
regex.test('\n')
// > true
regex.test('\r')
// > true
regex.test('\u2028')
// > true
regex.test('\u2029')
// > true

Named Capture Groups

Suppose you want to get the currency, numeric price value, and total currency in a string of format:

Total: $60.00

The regular matching this string would look like this:

;/^Total: [€\$]\d\d\.\d\d$/

The dolloar sign and dot are escaped because they are metasyntax characters. After adding parentheses to capture the needed values, the regular expression lookis like this:

;/^Total: (([€\$])(\d\d\.\d\d))$/

We now have three capture groups to access the data:

1: price with currency
2: currency symbol
3: numeric price

Using the indices 1, 2, and 3 to refer to these capture groups isn't very maintainable. For example, what if price is multilingual, and you have to capture the Total as well:

;/^(Total|Totaal): (([€\$])(\d\d\.\d\d))$/

As a result, capture groups 1, 2, and 3 have now become 2, 3, and 4. Code processing these values now have to be rewritten. Enter capture groups:

<priceWithSymbol>: price with symbol
<symbol>: currency symbol
<price>: numeric price

The syntax <captureGroupName>content matches content in <captureGroupName>:

// Capture groups example
const regex = /^Total: (?<priceWithSymbol>(?<symbol>[€\$])(?<price>\d\d\.\d\d))$/

In order to create a named capture, all that's needed is to write a question mark after the start of the parentheses, then the capture group name inside greater than and less than symbols.

Now we're done. Let's see the results:

// Named capture groups example
const regex = /^Total: (?<priceWithSymbol>(?<symbol>[€\$])(?<price>\d\d\.\d\d))$/
regex.exec('Total: $60.00').groups
// > {priceWithSymbol: $60.00, symbol: '$', price: '60.00'}

Named capture groups make regular expressions more maintainable.

Unicode Escapes

This new feature is very documentation-heavy since the docs themselves discuss every minute detail in this update. You can use the documentation as a reference. The documentation entails how you can match certain unicode character groups with some expressions without third party libraries. In this section, I'll concentrate on some practical use cases of the addition instead of a thorough walkthrough of all unicode groups.

One use case is matching greek characters. Before ES2018, you would have to create character sets:

// Greek lowercase character set
const greekChars = /[θωερτψυιοπασδφγηςκλζχξωβνμάέήίϊΐόύϋΰώ]/u
greekChars.test('λ')
// > true

That doesn't even include uppercase letters:

const uppercaseGreekChars = /[ΘΩΕΡΤΨΥΙΟΠΑΣΔΦΓΗςΚΛΖΧΞΩΒΝΜΆΈΉΊΪΐΌΎΫΰΏ]/u
uppercaseGreekChars.test('Λ')
// > true

In ES2018, it's a lot simpler:

// Old way
const greekChars = /[θωερτψυιοπασδφγηςκλζχξωβνμάέήίϊΐόύϋΰώ]/u
const uppercaseGreekChars = /[ΘΩΕΡΤΨΥΙΟΠΑΣΔΦΓΗςΚΛΖΧΞΩΒΝΜΆΈΉΊΪΐΌΎΫΰΏ]/u
// New way
const unicodeEscape = /\p{Script=Greek}/u
unicodeEscape.test('π')
// > true
unicodeEscape.test('ω')
// > true
unicodeEscape.test('Ϋ')
// > true

/\p{Script=Greek}/u only matches Greek characters, and this is great semantic shorthand. If you think about it, Greek is very much like English in terms of the limited number of characters. In addition, you would have a have a difficult time working in Chinese or Japanese, where you would have to concatenate another endlees pool of symbols. This problem is solved with Unicode escapes in ES2018.

/\p{Alphabetic}/u matches any alphabetical character of any language:

// Alphabetic unicode escape
const regex = /\p{Alphabetic}/u
regex.test('á')
// > true
regex.test('が')
// > true
regex.test('6')
// > false
regex.test('π')
// > true
regex.test('ω')
// > true
regex.test('Ϋ')
// > true

Lookbehinds

A lookbehind is the opposite of a lookahead. It walks backwards in the regular expression and checks if the given pattern matches the string before the current position. If a lookbehind match is succesful, the match is reverted.

Negative lookbehind: (?<!pattern)
Positive lookbehind: (?<=pattern)

An implicit lookbehind does exist before ES2018, \b, the word boundary anchor. So, in practice, you could use word boundaries without lookbehinds. Here are some examples that show this.

Example 1: Determine if the string contains a character sequence starting with whimper or whisper:

const regex = /\bwhi[ms]per/
regex.test(string)

In the example above, we're looking for the pattern whi[ms]per in the string provided. Before the w character, the \b word boundary anchor filters our results by ensuring a non-whitespace character cannot stand in front of the w.

Example 2: Here are some examples for negative and positive lookbehinds. /(?<=e)i/ matches an i character if it comes right after an e character. The e character is not included in the match.

// Positive lookbehind syntax
const regex = /(?<=e)i/
regex.exec('oi')
// > null
regex.exec('ei')
// > {'i', index: 1, input: 'ei', groups: undefined}

/(?<=e)i/ matches an i character if it does not come right after an e:

// Negative lookbehind syntax
const regex = /(?<=e)i/
regex.exec('oi')
// > {'i', index: 1, input: 'ei', groups: undefined}
regex.exec('ei')
// > null

Want to Learn Faster? Double Your Rate of Failure

Sat, 24 Feb 2018 00:00:00 GMT

I've been doing web development for around a year now, but I've had some rough patches throughout this time. When I used to fail at creating projects, I would just delete everything and start over, or just stop coding altogether. These coding droughts occurred from time periods of a couple days all the way up to a month or two.

I used to see failure as a bad thing. However, as a developer, I have learned that I need to embrace failure and discomfort. Now, I don't look as failure as having to start over: it's a chance to do something better this time.

For example, let's say you want to create a full stack app in a day. If you're just starting out coding, that's not a realistic goal. It's not really specific either. However, if you set a unrealistic goal and fail, learn from it. Try again, fail again, and keep going. Even the best make mistakes: it's what you do after the mistake that counts!

What happens is we, as people and developers, fall into a cycle of discouragement. We mess up, then we beat ourselves up. As a result, we lose our motivation, and the cycle just repeats itself. Break out of that cycle. Look at every failure as an opportunity to start over and do things even better.

Difference Between Git Stash and Git Commit

Wed, 19 Apr 2017 00:00:00 GMT

git stash

The command saves your local modifications away and reverts the working directory to match the HEAD commit. It allows you to store your uncommited modifications into a buffer area called stash, and deletes it from the branch you are working on. You may later retreive them by applying the stash.

git commit

This records your change for next push and this event is recorded in history too.

Andrew Usher's Blog

Handling Multiple Promises: Promise.all vs Promise.allSettled

Promise.all: Everything or Nothing

Promise.allSettled: Let Everything Finish

When to Use Which

Quick Win: Extract Just the Successes

The Bottom Line

Cookie Store API: The Modern Way to Handle Cookies

Introduction

The Problem with document.cookie

Quick Start: Your First Cookie

Cookie Properties Deep Dive

expires vs maxAge

domain

path

Secure

SameSite

Partitioned

Getting Cookies

get() - Single Cookie

getAll() - Multiple Cookies

Cookie Change Events

Partitioned Cookies (CHIPS)

Service Worker Integration

Async Patterns & Error Handling

Promise Chaining

Error Handling

Retry Logic

Migration Guide: From document.cookie to Cookie Store API

Reading Cookies

Setting Cookies

Deleting Cookies

Conditional Implementation

Performance Considerations

Batch Operations

Debounce Change Handlers

Cache Frequently Accessed Cookies

Real-World Use Cases

1. Session Management

2. A/B Testing

3. User Preferences

4. Cross-Domain Authentication

Best Practices

1. Always Use Secure Cookies

2. Set Expiration

3. Use SameSite Appropriately

4. Handle Errors Gracefully

5. Use Partitioned Cookies for Third-Party Contexts

Wrapping Up

Resources

Building Real-Time Dashboards with Cloudflare Durable Objects

Introduction

What Are Durable Objects?

The Perfect Use Case: Live Dashboards

Connection Types: Choosing Your Strategy

WebSockets: True Bidirectional Communication

Server-Sent Events (SSE): Simple Streaming

HTTP Polling: The Fallback

The Verdict for Dashboards

Architecture: How It All Fits Together

Understanding the Flow

The Code Structure

Key Patterns to Notice

The Magic of Hibernation

How Hibernation Works

The Cost Savings

Hibernation Best Practices

Monitoring Hibernation

Stream Backpressure and Buffering

The Problem

Implementing Smart Buffering

Sampling Strategy

Production Considerations

Error Handling

Rate Limiting

Authentication

Monitoring and Observability

Wrapping Up

Next Steps

Give Your Web App a Voice

The Problem with `document.cookie`

`get()` - Single Cookie

`getAll()` - Multiple Cookies

Migration Guide: From `document.cookie` to Cookie Store API