How inference works

The input is treated as a sample, not a schema. If every item in an array has the same key, it becomes required. If a key is missing from some items, it becomes optional (?). If a key holds different types across items, the generator emits a union such as string | number.

typescript
export interface Root {
  id: number;
  name: string;
  tags: string[];
  meta?: {
    createdAt: string;
  };
}

Generate from several representative samples if the API is polymorphic. A single sample produces a type that fits that sample, not the whole contract.

Naming and nesting

Nested objects get interface names derived from their key path (User, UserProfile). Awkward names are PascalCased and deduplicated. Array types use the element type followed by []; deeply nested arrays become T[][].

  • null values become unknown unless every value is null, in which case the field is null.
  • Dates are strings unless you post-process them into Date.
  • Numbers are number even if they are integer IDs; consider string for 64-bit IDs to avoid precision loss.
  • Duplicate interface names are suffixed with a number.

What the generator cannot know

TypeScript types describe shapes, not constraints. A string may be an email, a UUID or an enum; the sample does not tell you which. Review generated interfaces and tighten them with literal unions or branded types where the API documents constraints.