{"id":14786,"library":"openapi-typescript-helpers","title":"OpenAPI TypeScript Helpers","description":"openapi-typescript-helpers is a utility package providing TypeScript helper types designed to complement types generated by `openapi-typescript`. Its primary purpose is to offer generic type transformations, which are internally leveraged by other packages in the `openapi-ts` ecosystem, such as `openapi-fetch`. The current stable version is `0.1.0`. Given its recent initial release and close ties to `openapi-typescript`, its release cadence is likely tied to major `openapi-typescript` releases and feature additions, though it may not have independent major version bumps as frequently. Key differentiators include its focus on type-level transformations for refining generated OpenAPI types, particularly for handling `readOnly` and `writeOnly` properties, ensuring type safety and correct data handling across different API operations. Unlike `openapi-typescript` which generates the types, this package provides tools to manipulate and refine those generated types for specific application logic.","status":"active","version":"0.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/openapi-ts/openapi-typescript","tags":["javascript","typescript"],"install":[{"cmd":"npm install openapi-typescript-helpers","lang":"bash","label":"npm"},{"cmd":"yarn add openapi-typescript-helpers","lang":"bash","label":"yarn"},{"cmd":"pnpm add openapi-typescript-helpers","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides the base types that these helpers transform and refine. It is a fundamental peer dependency for this package to be useful.","package":"openapi-typescript","optional":false}],"imports":[{"note":"Used to transform types, excluding `writeOnly` properties, making a type suitable for read operations. Import as a type.","symbol":"Readable","correct":"import type { Readable } from 'openapi-typescript-helpers';"},{"note":"Used to transform types, excluding `readOnly` properties, making a type suitable for write operations. Import as a type.","symbol":"Writable","correct":"import type { Writable } from 'openapi-typescript-helpers';"},{"note":"Internal helper type used when the `--read-write-markers` flag is enabled in `openapi-typescript`. Developers generally shouldn't need to import this directly, but it indicates a `readOnly` property.","symbol":"$Read","correct":"import type { $Read } from 'openapi-typescript-helpers';"}],"quickstart":{"code":"import type { paths } from './my-api'; // Assume this is generated by openapi-typescript\nimport type { Readable, Writable } from 'openapi-typescript-helpers';\n\n// Example: Define a schema type from openapi-typescript generated types\ntype Pet = paths['/pets/{petId}']['get']['responses'][200]['content']['application/json'];\n\n// Create a type for a pet when fetching (should not include writeOnly fields)\ntype ReadablePet = Readable<Pet>;\n\n// Create a type for creating a pet (should not include readOnly fields)\ntype WritablePet = Writable<Pet>;\n\ninterface PetInput { // Simulate a type with readOnly/writeOnly markers\n  id: $Read<string>;\n  name: string;\n  tag?: string;\n  secretToken: $Write<string>;\n}\n\ntype FetchablePetInput = Readable<PetInput>; // id, name, tag\ntype CreatablePetInput = Writable<PetInput>; // name, tag, secretToken\n\n// You would typically use these types in your API client logic:\n// async function fetchPet(petId: string): Promise<ReadablePet> { /* ... */ }\n// async function createPet(newPet: WritablePet): Promise<ReadablePet> { /* ... */ }\n\n// Demonstrate how the types change\nconst petToCreate: CreatablePetInput = {\n  name: 'Buddy', \n  // id is excluded by Writable\n  secretToken: process.env.PET_SECRET ?? '' // secretToken is included\n};\n\nconst fetchedPet: FetchablePetInput = {\n  id: '123',\n  name: 'Buddy' \n  // secretToken is excluded by Readable\n};","lang":"typescript","description":"Demonstrates the usage of `Readable` and `Writable` helper types to refine generated OpenAPI types for specific read and write operations, highlighting how they filter `readOnly` and `writeOnly` properties."},"warnings":[{"fix":"Ensure `openapi-typescript` is installed and run to generate your API types before attempting to use these helpers.","message":"This package is designed to work with types generated by `openapi-typescript`. Its utility is minimal without a pre-generated `paths` or similar type from `openapi-typescript`.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Be prepared for potential minor breaking changes or undocumented behavior. Refer to the source code and `openapi-fetch`'s implementation for advanced usage.","message":"The README explicitly states this package is \"not as well-documented as the others\" and to \"use at your own discretion.\" This suggests that its API may be less stable or more prone to change in minor versions compared to its parent project.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"When generating types with `openapi-typescript`, ensure you use the `--read-write-markers` flag (e.g., `npx openapi-typescript --read-write-markers your-api.yaml -o src/api-types.ts`).","message":"The `Readable` and `Writable` types rely on markers (`$Read<T>` / `$Write<T>`) which are only added to `openapi-typescript` generated types when the `--read-write-markers` flag is enabled. Without this flag, these helpers will have no effect on `readOnly` / `writeOnly` properties.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Remove the `readOnly` property from the object being assigned to the `Writable` type, as it's not meant to be written to. Ensure `openapi-typescript` was run with `--read-write-markers`.","cause":"Attempting to assign a `readOnly` field to a `Writable` type, which excludes `readOnly` properties.","error":"Property 'someReadOnlyField' does not exist on type 'Writable<MySchema>'"},{"fix":"Ensure the target type or function parameter is also expecting a `Readable` type or a type that is compatible with the `writeOnly` properties being excluded. Or, verify that the original schema does not have `writeOnly` properties that are essential for the assignment.","cause":"This error is unlikely to occur directly for `Readable`, as it only removes `writeOnly` properties. However, a similar error might occur if you try to assign a `Readable` type to a context expecting the original schema type that includes `writeOnly` properties if that context strictly requires them for some reason.","error":"Type 'MySchema' is not assignable to type 'Readable<MySchema>'"}],"ecosystem":"npm"}