Normalize an API payload into a typed list

Canonical URL: https://devexamples.com/typescript/normalize-an-api-payload-into-a-typed-list/

Endpoints drift. Before any reshaping or rendering, one function should take whatever arrived and promise a single array type, while keeping a written record of every entry it could not accept.

Language: TypeScript

export type ReportRow = {
  readonly id: string;
  readonly label: string;
  readonly score: number;
};

export type NormalisedList<TItem> = {
  readonly items: readonly TItem[];
  readonly problems: readonly string[];
};

const ENVELOPE_KEYS = ["items", "results", "data"] as const;

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

function extractRows(payload: unknown): readonly unknown[] | null {
  if (Array.isArray(payload)) {
    return payload;
  }

  if (!isRecord(payload)) {
    return null;
  }

  for (const key of ENVELOPE_KEYS) {
    const nested = payload[key];
    if (Array.isArray(nested)) {
      return nested;
    }
  }

  return null;
}

function toReportRow(row: unknown, index: number, problems: string[]): ReportRow | null {
  if (!isRecord(row)) {
    problems.push(`entry ${index}: dropped, the value is not an object`);
    return null;
  }

  const id = row["id"];
  const score = row["score"];
  const label = row["label"];

  if (typeof id !== "string" || id === "") {
    problems.push(`entry ${index}: dropped, no usable id`);
    return null;
  }

  if (typeof score !== "number" || !Number.isFinite(score)) {
    problems.push(`entry ${index} (${id}): dropped, score is not a finite number`);
    return null;
  }

  return {
    id,
    score,
    label: typeof label === "string" && label !== "" ? label : id,
  };
}

export function normaliseReports(payload: unknown): NormalisedList<ReportRow> {
  const problems: string[] = [];
  const rows = extractRows(payload);

  if (rows === null) {
    problems.push("no array at the payload root or under items, results, or data");
    return { items: [], problems };
  }

  const items: ReportRow[] = [];
  const acceptedIds = new Set<string>();

  rows.forEach((row, index) => {
    const candidate = toReportRow(row, index, problems);

    if (candidate === null) {
      return;
    }

    if (acceptedIds.has(candidate.id)) {
      problems.push(`entry ${index}: duplicate id ${candidate.id} was dropped`);
      return;
    }

    acceptedIds.add(candidate.id);
    items.push(candidate);
  });

  return { items, problems };
}

The payload arrives over the network, so the await boundary stays next to the normaliser rather than inside it.

Language: TypeScript

export async function fetchReports(url: string): Promise<NormalisedList<ReportRow>> {
  const response = await fetch(url);

  if (!response.ok) {
    throw new Error(`Reports request failed with status ${response.status}`);
  }

  const payload: unknown = await response.json();

  return normaliseReports(payload);
}

One call with this body exercises every branch of the normaliser:

Language: Plain text

{
  "results": [
    { "id": "eu-west", "score": 12.5 },
    { "score": 4 },
    "unexpected string",
    { "id": "eu-west", "score": 3 },
    { "id": "us-east", "score": null, "label": "US East" }
  ]
}

Explanation

Normalisation is two decisions, and the code separates them. extractRows answers “where is the list?” by testing the root and then each key in ENVELOPE_KEYS, returning the first array it finds or null when the payload carries none. toReportRow answers “is this entry usable?” by checking each field against the declared ReportRow shape and returning either a complete row or nothing. Because both answers are explicit, the caller never has to guess whether an empty result means an empty endpoint or a payload it failed to read: the second case always writes a line into problems.

Everything entering the function is unknown, which is what makes the output type meaningful. Array.isArray on an unknown narrows it to an array of unchecked values, so the rows handed to toReportRow are still unknown and each field access goes through isRecord first — the index signature on Record<string, unknown> permits row["id"] while keeping the result untrusted until a typeof test resolves it. The annotations are what stop any from leaking: no value is ever asserted to be a ReportRow, and the only place a ReportRow is created is the return statement where all three fields have already been checked or defaulted. The label fallback to id is a deliberate product choice rather than a type decision, and it is the one field worth revisiting when you adapt the function, since a silent fallback is invisible in the problems list.

The duplicate filter uses a Set of accepted ids, so the first occurrence wins and the order of items matches payload order. That is a boundary condition you should confirm against your own data: if the endpoint sends an updated row after a stale one with the same id, keeping the first drops the update, and you would rather keep the last or key on a version field. The other boundary is the empty case — a payload of { "results": [] } returns an empty list with no problems, while { "results": null } returns an empty list with a problem, because null is not an array under any envelope key. A JSON null body and an empty collection are different facts and this function keeps them apart.

Normalize an API payload into a typed list

The problem

Short answer

Explanation

Expected output

Usage notes

Common mistakes

Caveats

Alternatives

Prerequisite

Examples that treat this as a prerequisite

Related examples

References