Skip to content
Skills Library
Programming · Building & coding

typescript-types

/typescript-types

Use TypeScript's stronger types where they prevent real bugs (unknown with narrowing, discriminated unions, exhaustive checks, satisfies, branded ids, constrained generics) and stop before they become a puzzle. Use it when typing API data or states, when tempted by any, or on a confusing type error.

Repository
yaap ↗
Licence
MIT
Last repository change
13.11.2026

Assessment and security

95/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content30 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use TypeScript's stronger types where they prevent real bugs (unknown with narrowing, discriminated unions, exhaustive checks, satisfies, branded ids, constrained generics) and stop before they become a puzzle. Use it when typing API data or states, when tempted by any, or on a confusing type error.

Original author description

Use TypeScript's stronger types where they prevent real bugs (unknown with narrowing, discriminated unions, exhaustive checks, satisfies, branded ids, constrained generics) and stop before they become a puzzle. Use it when typing API data or states, when tempted by any, or on a confusing type error.

How it works

  1. 1. unknown, then narrow
  2. 2. One union for a value with states
  3. 3. Literal types and satisfies
  4. 4. Brand ids that must not mix
  5. 5. Generics with a constraint
  6. 6. Utility types before custom ones
  7. 7. Assertions are a last resort
  8. 8. Test types that matter
  9. When a type fights you
Original SKILL.md headings · 127 lines, 713 words
SKILL.md preview
---
name: typescript-types
description: Use TypeScript's stronger types where they prevent real bugs (unknown with narrowing, discriminated
  unions, exhaustive checks, satisfies, branded ids, constrained generics) and stop before they become a puzzle. Use
  it when typing API data or states, when tempted by any, or on a confusing type error.
license: MIT
metadata:
  sources: wshobson/plugins/javascript-typescript/skills/typescript-advanced-types
---

# TypeScript types

Types are worth what they catch. Use the features below when they turn a likely bug into a compile error; skip them
when they only make the code look clever. A type a colleague cannot read in a minute is a cost.

## 1. unknown, then narrow

Data from outside (the network, `localStorage`, `JSON.parse`, a message event) is `unknown` until checked. `any`
turns the checker off for everything it touches.

```ts
type OrderSummary = { id: string; total: number };

function isOrderSummary(value: unknown): value is OrderSummary {
  return (
    typeof value === "object" &&
    value !== null &&
    "id" in value &&
    typeof value.id === "string" &&
    "total" in value &&
    typeof value.total === "number"
  );
}
```

For anything larger than a few fields, use the project's schema library and infer the type from the schema, so the
check and the type cannot drift apart.

## 2. One union for a value with states

A value that is loading, loaded or failed is one discriminated union, not three optional fields that allow
impossible combinations.

```ts
type Load<T> =
  | { kind: "idle" }
  | { kind: "loading" }
  | { kind: "done"; data: T }
  | { kind: "failed"; error: string };

function describe(load: Load<Order[]>): string {
  switch (load.kind) {
    case "idle":
      return "Not started";
    case "loading":
      return "Loading";
    case "done":
      return `${load.data.length} orders`;
    case "failed":
      return load.error;
    default: {
      const unreachable: never = load;
      return unreachable;
    }
  }
}
```

The `never` line makes adding a fifth state a compile error in every switch that forgot it.

## 3. Literal types and satisfies

`as const` keeps literal values; `satisfies` checks an object against a type without widening it, so you keep the
exact keys.

```ts
const routes = {
  home: "/",
  orders: "/orders",
} as const satisfies Record<string, `/${string}`>;

type RouteName = keyof typeof routes; // "home" | "orders"
```

Derive unions from such objects instead of writing the list twice.

## 4. Brand ids that must not mix

When several ids are all strings, a branded type stops passing an order id where a customer id belongs.

```ts
type OrderId = string & { readonly brand: "OrderId" };
type CustomerId = string & { readonly brand: "CustomerId" };

const toOrderId = (value: string): OrderId => value as OrderId;
```

Create branded values in one place (the parser of the API response), never ad hoc.

## 5. Generics with a constraint

A generic is useful when the output type depends on the input type. Constrain it so the body can use what it needs.

```ts
function byId<T extends { id: string }>(items: readonly T[]): Map<string, T> {
  return new Map(items.map((item) => [item.id, item]));
}
```

If a type parameter appears only once in the signature, it adds nothing; use the concrete type.

## 6. Utility types before custom ones

`Pick`, `Omit`, `Partial`, `Required`, `Readonly`, `Record`, `ReturnType` and `Awaited` cover most needs. Write a
mapped or conditional type only when they do not, and give it a name and a one-line comment saying what it is for.
Template literal types are good for a fixed set of strings (event names, CSS units); beyond that they slow the
compiler and the reader.

## 7. Assertions are a last resort

`value as T` and `value!` tell the compiler to trust you. Prefer a type guard, an early return or a default. When an
assertion is unavoidable (a DOM element you just created, a library with a loose type), keep it in one small function
with a comment. `@ts-expect-error` with a reason beats `@ts-ignore`, because it fails once the error is gone.

## 8. Test types that matter

For a helper type others rely on, add a type test: a line that must compile and one marked `@ts-expect-error` that
must not, or the test runner's `expectTypeOf`. Run the type check (`tsc --noEmit` or the project's script) with the
tests, and read `diagnostics` for the files you changed.

## When a type fights you

Read the whole error from the bottom up; the last lines name the mismatch. Hover or print the inferred type with a
temporary `type Check = typeof value`. If a type needs more than one conditional to express, the data model is often
the problem; simplify the data first.

Versions

The database has no other skills named typescript-types.

Database snapshot: 13.11.2026 · package version 819d6f0d408c (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100typescript-type-safety
    TypeScript type safety patterns - unknown vs any, generics golden rule, null narrowing, inference discipline, import type, discriminated unions, error typing. Use when writing or reviewing TypeScript code for type correctness.
  • 91typescript-best-practices
    TypeScript idioms and type-safety patterns: discriminated unions, branded types, narrowing, boundary validation. Use when reading, writing, or reviewing any .ts or .tsx file.
  • 95ts-conventions
    ACTIVATE when writing TypeScript types, generics, branded types, discriminated unions, or configuring tsconfig. ACTIVATE for 'type vs interface', 'enum alternative', 'branded type', 'satisfies', 'strict mode'. Covers: strict mode policy, no-any/no-enum rules, type over…
  • 100typescript-expert
    Expert TypeScript: type system, generics, narrowing, inference, and strict-mode safety. Trigger keywords: TypeScript, types, generics, type narrowing, tsconfig, strict, discriminated union, conditional/mapped types, utility types, declaration files, type error, satisfies, infer,…
  • 100typescript
    Apply these opinionated TypeScript conventions whenever writing or reviewing TypeScript: branded types for domain modeling, discriminated unions for state, `satisfies` over `as`, const objects instead of enums, type-only imports, and the strict tsconfig baseline beyond `strict:…
  • 100lang-ts-base
    TypeScript rules that make the compiler reject bad states. Unions over optional-field bags, branded ids, exhaustive switches, no `as` casts, and types derived from the schema that owns the shape. Use when reading, writing, editing or reviewing any .ts or .tsx file.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.