Fetching Data & Network States

A local array exists immediately. Remote data may arrive later, arrive empty, fail validation, or never arrive. A useful interface represents those situations deliberately instead of assuming that every request produces a nonempty array.

In the practice application (practice/), we will extend the explicit Load todos pattern from Part 1 using the same neutral /api/todos endpoint. It returns rows with id and name. This laboratory version adds response decoding, a single state union, and cancellation on /lab; preserve the original TodoList at /. The marketplace project later adapts these ideas to marketplace reads.

Fetch has two important steps

const response = await fetch(`${baseUrl}/api/todos`);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();

The first await obtains a response. The second reads and decodes its body. A 404 or 500 normally resolves to a Response; it does not automatically reject the fetch promise. Network failures can reject it, and invalid JSON can fail during body decoding. See the Fetch guide.

Do not use an empty successful array as a universal replacement for errors. “No records exist” and “we do not know whether records exist” are different facts.

Put one read operation in a small module

Create client/src/lib/examples/todos-api.ts:

export type Todo = { id: number; name: string };

export const decodeTodos = (value: unknown): Todo[] => {
  if (!Array.isArray(value)) throw new Error('Expected a todo array');
  return value.map((row: unknown) => {
    if (typeof row !== 'object' || row === null ||
        !('id' in row) || !('name' in row) ||
        typeof row.id !== 'number' || !Number.isInteger(row.id) || row.id <= 0 ||
        typeof row.name !== 'string') {
      throw new Error('Invalid todo response');
    }
    return { id: row.id, name: row.name };
  });
};

export const getTodos = async (signal?: AbortSignal): Promise<Todo[]> => {
  const baseUrl = import.meta.env.VITE_API_BASE_URL || 'http://localhost:8000';
  const response = await fetch(`${baseUrl}/api/todos`, { signal });
  if (!response.ok) throw new Error(`Todo request failed (${response.status})`);
  return decodeTodos(await response.json());
};

The local decoder makes a distinction that a TypeScript assertion cannot: it checks values while the program runs. as Todo[] would only tell the type checker what to assume. Part 3 introduces schema validation rather than expanding handwritten checks indefinitely.

The helper reads the same public API-base variable as Part 1. Do not replace it with an internal container host name for normal browser use. The E2E environment already supplies a different address because its browser runs on the Compose network.

Represent mutually exclusive outcomes

Create client/src/lib/examples/TodosPanel.svelte:

<script lang="ts">
  import { onMount } from 'svelte';
  import { getTodos, type Todo } from './todos-api';

  type LoadState =
    | { kind: 'idle' }
    | { kind: 'loading' }
    | { kind: 'ready'; todos: Todo[] }
    | { kind: 'error'; message: string };

  let state = $state<LoadState>({ kind: 'idle' });
  let generation = 0;
  let controller: AbortController | undefined;

  const load = async () => {
    const requestNumber = ++generation;
    controller?.abort();
    const current = new AbortController();
    controller = current;
    state = { kind: 'loading' };
    try {
      const todos = await getTodos(current.signal);
      if (requestNumber !== generation || current.signal.aborted) return;
      state = { kind: 'ready', todos };
    } catch (error) {
      if (requestNumber !== generation || current.signal.aborted) return;
      state = {
        kind: 'error',
        message: error instanceof Error ? error.message : 'Could not load todos'
      };
    }
  };

  onMount(() => () => {
    generation += 1;
    controller?.abort();
  });
</script>

<section aria-label="Stored todos">
  <h2>Stored todos</h2>
  <button type="button" onclick={load}>Load todos</button>
  {#if state.kind === 'idle'}
    <p>Load the current todos.</p>
  {:else if state.kind === 'loading'}
    <p role="status">Loading todos...</p>
  {:else if state.kind === 'error'}
    <p role="alert">{state.message}</p>
  {:else if state.todos.length === 0}
    <p>No stored todos.</p>
  {:else}
    <ul>
      {#each state.todos as todo (todo.id)}
        <li>{todo.name}</li>
      {/each}
    </ul>
  {/if}
</section>

The union gives each state an explicit shape. Loading cannot simultaneously contain an old error because that field belongs to another variant. An empty array is a successful ready result, not a network failure.

Mount this component on /lab. Loading remains explicit, as in Part 1. The new onMount hook registers cleanup when the component is created; it does not start this component’s request. Later, if a page should load immediately, call the same named load function from a synchronous onMount callback and return the cancellation cleanup from that callback.

Prevent old responses from replacing new ones

The user may reload while a previous request is still running. Request A might then finish after request B. Without a guard, older data can overwrite newer data.

The request number identifies the currently relevant request. Aborting the previous request avoids unnecessary client work where possible; the generation check protects the state update even when cancellation is too late. This does not mean an aborted mutation was undone on the server. In this chapter we only cancel reads.

The onMount callback returns cleanup for component removal. It is deliberately not an async callback: an async function returns a promise, not the cleanup function Svelte expects. The lifecycle documentation explains this distinction.

Test success and failure without a live API

Create TodosPanel.test.ts beside the component:

import { cleanup, render, screen } from '@testing-library/svelte';
import { userEvent } from '@testing-library/user-event';
import { afterEach, expect, it, vi } from 'vitest';
import TodosPanel from './TodosPanel.svelte';

afterEach(() => {
  cleanup();
  vi.unstubAllGlobals();
});

it('renders returned rows', async () => {
  vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(
    JSON.stringify([{ id: 31, name: 'Review notes' }]),
    { status: 200, headers: { 'Content-Type': 'application/json' } }
  )));
  const user = userEvent.setup();
  render(TodosPanel);
  await user.click(screen.getByRole('button', { name: 'Load todos' }));
  expect(await screen.findByText('Review notes')).toBeInTheDocument();
});

it('does not present an HTTP failure as an empty result', async () => {
  vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response('Unavailable', {
    status: 503
  })));
  const user = userEvent.setup();
  render(TodosPanel);
  await user.click(screen.getByRole('button', { name: 'Load todos' }));
  expect(await screen.findByRole('alert')).toHaveTextContent('503');
  expect(screen.queryByText('No stored todos.')).not.toBeInTheDocument();
});

These tests substitute the browser API, not a real network. They establish component response handling but do not check DNS, CORS, or Hono. Add a test for [], a rejected fetch promise, and invalid response data. For a loading-state test, control when a promise resolves rather than sleeping for a guessed duration. Vitest documents global stubbing.

CORS is a browser access boundary

The practice application’s client and API have different origins. The API’s CORS middleware supplies response headers authorizing browser access from the configured client origin. curl is not a browser enforcing that policy, so a direct request can work while a browser cannot expose the response to JavaScript.

For some cross-origin requests, the browser first sends a preflight request. A simple read may not need one. Do not set mode: 'no-cors' as a fix: an opaque response does not give your JavaScript the JSON body it needs. Do not disable browser security or treat CORS as authorization. Part 5 supplies actual identity and access rules. See the CORS guide.

Use browser fetch for this first network boundary

For this chapter’s programming exercise, implement the request with browser fetch, not hc or a framework-managed remote function. Inspect the actual request in the Network panel. This is an implementation requirement, not a restriction on sources of help. Part 4 will refactor the same kind of operation to a typed client after its runtime behavior is familiar.

A local type declaration is useful documentation, but assigning await response.json() to that type does not inspect the bytes. Keep the distinction between the value received and the type the program expects.

Read a different response shape

The next two exercises use weather readings rather than todos or marketplace listings. First write the read module and its decoder. The interface exercise then uses a supplied correct read module rather than files from your submission, so its implementation focus remains state and request lifetime. The API exercise is still listed as a prerequisite for the interface exercise.

The weather contract needs two numeric checks that the todo example did not. typeof temperatureC === 'number' also accepts NaN and infinities, so combine that check with Number.isFinite(temperatureC). For an unknown id, first establish that it is a number, then require Number.isSafeInteger(id) && id > 0. A negative finite temperature remains valid.

{"station":"Harbour","readings":[{"id":17,"temperatureC":12.5}]}

Recover a networked interface

Keep the load action available for retry. Test transitions in one mounted component, including a previously successful read followed by empty data or a failure. A late response from an old request must not replace the latest result.

Check Your Understanding

1. Why must successful fetch completion and successful HTTP status be checked separately?
2. What does the decoder establish that a TypeScript assertion does not?
3. Why is an empty result not an appropriate replacement for every error?
4. How can an older response overwrite a newer one, and how is that prevented here?
5. What does a stubbed component test fail to establish about CORS or connectivity?