Typed API & State — Programuoki

Code

src/lib/api.ts — a type guard at the boundary

In the code column — src/lib/api.ts. Two decisions do all the work.

1. request() returns Promise<unknown>, not Promise<any>. The difference is fundamental:

any — "don't worry about types, do whatever". A hole.
unknown — "you have something, but you don't know what yet; you must check before using it".

With unknown the compiler won't let you use the result as Apod[] straight away — it forces you through a guard.

2. The type guard isApod:

function isApod(value: unknown): value is Apod {
  if (typeof value !== 'object' || value === null) return false;
  const v = value as Record<string, unknown>;
  return (
    typeof v['date'] === 'string' &&
    typeof v['url'] === 'string' &&
    (v['media_type'] === 'image' || v['media_type'] === 'video')
  );
}

value is Apod is a type predicate. If the function returns true, the compiler treats value as an Apod from there on. The real check happens at runtime (it inspects the fields), and its result unlocks the type at compile time.

And fetchPictures uses it at the boundary:

return data.filter(isApod).reverse();   // drop anything malformed, don't crash

.filter(isApod) is clever: it both validates and filters out bad entries. If NASA returns one malformed picture, it simply disappears and the gallery keeps working. The returned type is a clean Apod[].

Tip. We write the guard once, in one place — at the network boundary. After that, the whole app works with a trusted Apod and no extra checks. This is "push any/unknown to the edges, keep the core strictly typed". The boundary is where the untrusted world meets your types.

api.ts CREATE

Create this file in src/lib/

// The API layer.
//
// The important idea: `response.json()` returns `any`. That `any` is a HOLE in
// the type system — it lets unchecked, unshaped data flow into an app that
// believes it is well-typed. Types describe what we EXPECT; they do NOT check
// what we GOT. TypeScript will not save you from an API that changes.
//
// So we VALIDATE at the boundary. The type guard below confirms what we got.

import type { Apod } from '../types.js';
import { NetworkError, RateLimitError, ApiError } from './errors.js';

const API_URL = 'https://api.nasa.gov/planetary/apod';
const API_KEY = import.meta.env.VITE_NASA_API_KEY ?? 'DEMO_KEY';

/**
 * A TYPE GUARD. The return type `value is Apod` tells the compiler: "if this
 * returns true, you may treat `value` as an Apod." That is how untrusted
 * `unknown` data becomes a trusted, typed value.
 */
function isApod(value: unknown): value is Apod {
  if (typeof value !== 'object' || value === null) return false;
  const v = value as Record<string, unknown>;
  return (
    typeof v['date'] === 'string' &&
    typeof v['title'] === 'string' &&
    typeof v['url'] === 'string' &&
    (v['media_type'] === 'image' || v['media_type'] === 'video')
  );
}

// request() returns Promise<unknown> — NOT Promise<any>. The caller is FORCED
// to validate before it can use the result as anything.
async function request(url: string): Promise<unknown> {
  let response: Response;
  try {
    response = await fetch(url);
  } catch {
    throw new NetworkError();        // fetch only rejects on a network failure
  }
  if (response.ok) return response.json();
  if (response.status === 429) throw new RateLimitError();
  throw new ApiError(response.status);
}

export async function fetchPictures(url: string): Promise<Apod[]> {
  const data = await request(url);
  if (!Array.isArray(data)) throw new ApiError(500);
  return data.filter(isApod).reverse();   // drop anything malformed, don't crash the gallery
}