Skip to content
Skills Library
Programming · Building & coding

ts-api-types

/ts-api-types

Type the boundaries of a TypeScript codebase: public API surfaces, branded types, and runtime validation of untyped input. Use when designing types others consume, or when external data enters your program.

Repository
AI-SKILLS ↗
Licence
MIT
Last repository change
05.09.2026

Assessment and security

90/ 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.
Content25 / 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 05.09.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

Type the boundaries of a TypeScript codebase: public API surfaces, branded types, and runtime validation of untyped input. Use when designing types others consume, or when external data enters your program.

Original author description

Type the boundaries of a TypeScript codebase: public API surfaces, branded types, and runtime validation of untyped input. Use when designing types others consume, or when external data enters your program.

How it works

  1. Method
  2. Boundaries
Original SKILL.md headings · 56 lines, 434 words
SKILL.md preview
---
name: ts-api-types
description: "Type the boundaries of a TypeScript codebase: public API surfaces, branded types, and runtime validation of untyped input. Use when designing types others consume, or when external data enters your program."
---

# TS API types

Types inside your program are checked by the compiler; types at the edges
(what callers pass in, what the network returns) are promises the compiler
cannot verify. The discipline is making public types precise and
validating untyped input where it enters, so the guarantees inside are
real.

## Method

1. **Design public types for the consumer, not the implementation.** An
   exported function's parameter and return types are its contract:
   precise, minimal, and stable (see api-surface-minimalism). Prefer
   specific types over `any`/`object`; use unions and literals to make
   illegal arguments unrepresentable ("size": "sm" | "md" | "lg" beats
   `string`).
2. **Validate untrusted input at the boundary, then trust it inside.**
   Data from the network, files, env, or user is `unknown`, not the type
   you hope. Parse it with a schema validator (zod, valibot, or
   hand-written guards) at the entry point into a typed value; downstream
   code then works with a real type, not a hope (see request-validation,
   typescript-narrowing). A cast (`as User`) on network data is a lie the
   compiler believes.
3. **Derive types from the source of truth.** Infer types from schemas
   (`z.infer<typeof UserSchema>`), from data (`as const` plus `typeof`),
   or from the API contract (generated from OpenAPI): so the type and the
   runtime shape cannot drift. Hand-maintaining a type beside a schema
   guarantees they diverge (see openapi-contracts).
4. **Use branded types for values that are more than their shape.** A
   `UserId` and an `OrderId` are both `string` but must not be swapped:
   brand them (`type UserId = string & { readonly __brand: "UserId" }`)
   so the compiler catches passing one where the other belongs. Reserve
   this for identifiers and values where the mix-up is costly.
5. **Prefer `readonly` and precise object types at boundaries.**
   `readonly` arrays and properties on inputs signal you will not mutate
   them and let callers pass frozen data (see js-immutability); exact
   object types reject typo'd extra properties on public inputs.
6. **Version and evolve public types additively.** Adding optional fields
   is safe; removing, renaming, or narrowing a published type breaks
   consumers (see api-change-management). Treat exported types like any
   API surface.

## Boundaries

- Types vanish at runtime; a `User` type does nothing to a malformed
  object at the boundary. Only runtime validation makes the boundary
  safe, and the type should be derived from that validation, not
  asserted alongside it.
- Branded types and heavy schema inference add ceremony; apply them at
  the edges and the identifiers that matter, not to every internal
  object.
- Generated types from a backend contract are only as honest as the
  contract; a lying OpenAPI spec produces confidently-wrong types (see
  openapi-contracts).

Versions

The database has no other skills named ts-api-types.

Database snapshot: 13.11.2026 · package version b63611cbcc95 (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

  • 90typescript
    Implement, debug, or review TypeScript code and type boundaries. Use when changing types, generic APIs, compiler options, runtime validation, module behavior, or JavaScript interoperability.
  • 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.
  • 100typescript-advanced-types
    Master TypeScript's advanced type system — generics, conditional types, mapped types, template literals, and utility types — for building type-safe Angular 21.x components, NestJS 11.x APIs, and MCP Builder integrations. Use when implementing complex type inference, type-safe…
  • 100typescript
    Use when writing advanced TypeScript — creating utility types, narrowing unions, resolving tricky type errors, configuring the compiler for strict mode, building branded types, or augmenting third-party module types.
  • 98typescript
    Use when writing or hardening TypeScript in strict mode. Covers advanced types, discriminated unions, runtime validation at trust boundaries, generics, and removing `any` from an existing codebase. Trigger on "get rid of all the any types", "turn on strict mode in tsconfig",…
  • 100writing-types
    Use this skill when you need to write TypeScript types and interfaces in `srs/types` for the Next.js app — turn a domain or API spec into modular, well-named type definitions.

Feedback and reports

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