CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-openapi-typescript-helpers

TypeScript helpers for consuming openapi-typescript types

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

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

Install with Tessl CLI

npx tessl i tessl/npm-openapi-typescript-helpers
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/openapi-typescript-helpers@0.0.x
Publish Source
CLI
Badge
tessl/npm-openapi-typescript-helpers badge