or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

http-types.mdindex.mdopenapi-utilities.mdtypescript-utilities.md
tile.json

tessl/npm-openapi-typescript-helpers

TypeScript helpers for consuming openapi-typescript types

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/openapi-typescript-helpers@0.0.x

To install, run

npx @tessl/cli install tessl/npm-openapi-typescript-helpers@0.0.0

index.mddocs/

OpenAPI TypeScript Helpers

OpenAPI TypeScript Helpers provides essential TypeScript utility types and helpers for consuming OpenAPI-generated types. It includes comprehensive HTTP method and status code types, sophisticated type manipulation utilities for extracting request/response types from OpenAPI schemas, and advanced TypeScript conditional types for handling success and error responses.

This package serves as the foundational type system that powers openapi-fetch and other tools in the OpenAPI TypeScript ecosystem, offering generic utilities that can be reused across any TypeScript project working with OpenAPI schemas.

Package Information

  • Package Name: openapi-typescript-helpers
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install openapi-typescript-helpers

Core Imports

// Most commonly used types
import type { 
  HttpMethod, 
  OkStatus, 
  ErrorStatus,
  PathsWithMethod,
  SuccessResponse,
  ErrorResponse,
  FilterKeys,
  MediaType,
  JSONLike
} from "openapi-typescript-helpers";

// Additional OpenAPI utilities
import type {
  OperationObject,
  OperationRequestBody,
  IsOperationRequestBodyOptional,
  SuccessResponseJSON,
  ErrorResponseJSON,
  RequestBodyJSON
} from "openapi-typescript-helpers";

// Status and key utilities
import type {
  OKStatusUnion,
  FirstErrorStatus,
  RequiredKeysOf
} from "openapi-typescript-helpers";

Basic Usage

import type { 
  HttpMethod, 
  PathsWithMethod, 
  SuccessResponse, 
  ErrorResponse,
  FilterKeys 
} from "openapi-typescript-helpers";

// Define OpenAPI paths type (typically generated by openapi-typescript)
type Paths = {
  "/users": {
    get: {
      responses: {
        200: { content: { "application/json": User[] } };
        404: { content: { "application/json": { error: string } } };
      };
    };
    post: {
      requestBody: { content: { "application/json": CreateUser } };
      responses: {
        201: { content: { "application/json": User } };
        400: { content: { "application/json": { error: string } } };
      };
    };
  };
};

// Extract paths that support GET method
type GetPaths = PathsWithMethod<Paths, "get">; // "/users"

// Extract success response types
type UserListResponse = SuccessResponse<Paths["/users"]["get"]["responses"]>;
// Result: User[]

// Extract error response types  
type UserListError = ErrorResponse<Paths["/users"]["get"]["responses"]>;
// Result: { error: string }

// Use FilterKeys to extract specific media type
type JsonResponse = FilterKeys<
  Paths["/users"]["get"]["responses"][200]["content"], 
  "application/json"
>; // User[]

Architecture

OpenAPI TypeScript Helpers is organized around several key type categories:

  • HTTP Types: Fundamental HTTP method and status code types for OpenAPI schemas
  • OpenAPI Utilities: Advanced type manipulation for extracting and transforming OpenAPI operation types
  • TypeScript Utilities: Generic TypeScript conditional types and utility functions for type-level programming

The package provides no runtime code - all exports are TypeScript type definitions designed for compile-time type checking and inference.

Capabilities

HTTP and Status Types

Core HTTP method and status code types for building type-safe OpenAPI integrations.

type HttpMethod = "get" | "put" | "post" | "delete" | "options" | "head" | "patch" | "trace";

type OkStatus = 200 | 201 | 202 | 203 | 204 | 206 | 207 | "2XX";

type ErrorStatus = 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 510 | 511 | '5XX' | 
  400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 420 | 421 | 422 | 423 | 424 | 425 | 426 | 427 | 428 | 429 | 430 | 431 | 444 | 450 | 451 | 497 | 498 | 499 | '4XX' | "default";

HTTP and Status Types

OpenAPI Path and Operation Utilities

Advanced type utilities for extracting and manipulating OpenAPI path and operation objects, including request/response type extraction.

type PathsWithMethod<Paths extends {}, PathnameMethod extends HttpMethod> = {
  [Pathname in keyof Paths]: Paths[Pathname] extends {
    [K in PathnameMethod]: any;
  }
    ? Pathname
    : never;
}[keyof Paths];

type SuccessResponse<
  T extends Record<string | number, any>,
  Media extends MediaType = MediaType,
> = GetResponseContent<T, Media, OkStatus>;

type ErrorResponse<
  T extends Record<string | number, any>,
  Media extends MediaType = MediaType,
> = GetResponseContent<T, Media, ErrorStatus>;

OpenAPI Utilities

Generic TypeScript Utilities

General-purpose TypeScript utility types for advanced type manipulation and conditional type logic.

type FilterKeys<Obj, Matchers> = Obj[keyof Obj & Matchers];

type MediaType = `${string}/${string}`;

type JSONLike<T> = FilterKeys<T, `${string}/json`>;

type RequiredKeysOf<T> = RequiredKeysOfHelper<T> extends undefined ? never : RequiredKeysOfHelper<T>;

TypeScript Utilities