feat(openapi-typescript): add readOnly/writeOnly support via markers #2549

abumalick · 2025-12-16T08:31:16Z

Summary

Add opt-in --read-write-markers flag that generates $Read<T> and $Write<T> marker types for readOnly/writeOnly OpenAPI properties
Wrap readOnly properties with $Read<T>, writeOnly with $Write<T>
Generate inline helper types (Readable, Writable) in output
Update openapi-fetch to use Writable<T> for request bodies and Readable<T> for responses

This enables proper type-checking:

readOnly properties are excluded from request bodies
writeOnly properties are excluded from response types

Closes #604

Test plan

Added TDD tests in packages/openapi-fetch/test/read-write-visibility/
Tests verify compile-time type errors for invalid usage
Tests verify runtime behavior
All existing tests pass

changeset-bot · 2025-12-16T08:31:20Z

🦋 Changeset detected

Latest commit: 46a6e86

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
openapi-typescript	Minor
openapi-typescript-helpers	Minor
openapi-fetch	Minor
openapi-react-query	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

netlify · 2025-12-16T08:31:20Z

👷 Deploy request for openapi-ts pending review.

Visit the deploys page to approve it

Name	Link
🔨 Latest commit	`46a6e86`

abumalick · 2025-12-16T09:28:15Z

this one is a new implementation of #1863 @drwpow FYI

Copilot

Pull request overview

This PR adds opt-in support for OpenAPI's readOnly and writeOnly property modifiers via a new --read-write-markers CLI flag. When enabled, the type generator wraps these properties with marker types ($Read<T> and $Write<T>), enabling compile-time enforcement of visibility rules in openapi-fetch.

Key Changes:

Added --read-write-markers flag to wrap readOnly properties with $Read<T> and writeOnly properties with $Write<T>
Generated inline helper types (Readable<T>, Writable<T>) strip markers appropriately for request/response contexts
Updated openapi-fetch to use Writable<T> for request bodies and Readable<T> for responses

Reviewed changes

Copilot reviewed 11 out of 14 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/openapi-typescript/src/types.ts	Added `readWriteMarkers` option to OpenAPITSOptions and GlobalContext interfaces
packages/openapi-typescript/src/index.ts	Wired up `readWriteMarkers` option from user input to global context
packages/openapi-typescript/bin/cli.js	Added `--read-write-markers` CLI flag support
packages/openapi-typescript/src/transform/schema-object.ts	Implemented `wrapWithReadWriteMarker` function and integrated marker wrapping for properties and $defs
packages/openapi-typescript/src/transform/index.ts	Added inline generation of helper types ($Read, $Write, Readable, Writable) when flag is enabled
packages/openapi-typescript-helpers/src/index.ts	Added exportable helper types for marker definitions and transformation utilities
packages/openapi-fetch/src/index.d.ts	Applied Writable to request bodies and Readable to response data/errors
packages/openapi-typescript/test/transform/schema-object/object.test.ts	Added comprehensive test cases for readWriteMarkers option behavior
packages/openapi-typescript/test/test-helpers.ts	Added readWriteMarkers: false to default test context
packages/openapi-fetch/test/read-write-visibility/schemas/read-write.yaml	Test schema with readOnly and writeOnly properties
packages/openapi-fetch/test/read-write-visibility/schemas/read-write.d.ts	Generated types from test schema with markers enabled
packages/openapi-fetch/test/read-write-visibility/read-write.test.ts	Runtime and compile-time tests verifying marker behavior
docs/cli.md	Documentation for the new --read-write-markers flag with usage examples
.changeset/happy-pans-run.md	Changeset describing the new feature

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

docs/cli.md

packages/openapi-typescript/src/types.ts

abumalick · 2025-12-16T11:07:17Z

mmh, sorry it is not fully ready yet, after more testing I get some bugs

abumalick · 2025-12-24T06:57:32Z

Here it is ready incha Allah.
I tested it by migrating my enterprise's app to use this patched version. It is working well and it is really good to have this painful problem fixed.
I could remove all @ts-expect-errors on network requests payloads.

Please tell me if you need any changes or if you have any concern @htunnicliff @drwpow

abumalick · 2025-12-30T06:50:51Z

@htunnicliff @drwpow any feedback please?

abumalick · 2026-01-13T11:00:59Z

Ping for feedback @drwpow @kerwanp @gzm0 @htunnicliff

This implements the readOnly/writeOnly markers discussed in #1863 following @drwpow's suggested approach.

Production validation: Running in 2 company projects with openapi-fetch + openapi-react-query. Eliminated nearly all @ts-expect-error annotations for request/response type mismatches.

Key decisions needing review:

Opt-in via --read-write-markers flag
$Read<T>/$Write<T> marker approach
Helper types in openapi-typescript-helpers

Happy to adjust based on feedback. Is this direction acceptable or should I take a different approach?

abumalick · 2026-02-05T08:53:21Z

@duncanbeevers or any other maintainer. Can I get a review on this?

drwpow

Wow, thanks for all the thought and effort put into this PR! This has been a long-requested feature, and this adds in the ability in what looks to be a far more backwards-compatible way than some alternate solutions. I was worried this would be a breaking change, and so this (and the draft PR) fell behind in getting it merged in. But your approach looks sound, and looks like it wouldn’t disrupt users.

For openapi-fetch we’ve been reserving minor releases for breaking changes, and even though this is is backwards-compatible, I think a minor change makes sense here given it requires a more recent version of openapi-typescript. Folks will be happy to get this merged and released, thank you! 🙂

drwpow · 2026-02-08T23:21:17Z

It looks like the PR has some minor conflicts, if these get resolved I’d be happy to get this merged & released

Add opt-in `--read-write-markers` flag that generates `$Read<T>` and `$Write<T>` marker types for readOnly/writeOnly OpenAPI properties. - Wrap readOnly properties with `$Read<T>` - Wrap writeOnly properties with `$Write<T>` - Generate inline helper types (`Readable`, `Writable`) in output - Update openapi-fetch to use `Writable<T>` for request bodies and `Readable<T>` for responses - Add `$Read`, `$Write`, `Readable`, `Writable` types to openapi-typescript-helpers This enables proper type-checking: - readOnly properties are excluded from request bodies - writeOnly properties are excluded from response types Closes openapi-ts#604

When Readable<$Read> was resolved, it returned U directly instead of Readable, causing nested $Read markers inside U to not be unwrapped. Same issue for Writable<$Write>.

abumalick · 2026-02-09T05:19:01Z

Thanks @drwpow.

I really love this library and was really bothered by the typing issues with our APIs.
Since I started using the changes from this PR (as a patch) on our projects, we were able to confidently remove all TypeScript silencing and casting related to API types, and it greatly improved our confidence in the backend types. I am really happy with the result.

I was worried that you would not accept this change because of the complexity. I believe it makes a lot of sense to put this behind a flag so as not to bother users who don't need it or don't want to spend time refactoring their code for these changes.

Thank you for taking the time to work on this wonderful library.

abumalick force-pushed the feat/read-write-markers branch 4 times, most recently from b3daedc to b1d920a Compare December 16, 2025 09:25

abumalick marked this pull request as ready for review December 16, 2025 09:25

abumalick requested a review from a team as a code owner December 16, 2025 09:25

abumalick requested review from Copilot and htunnicliff December 16, 2025 09:25

Copilot started reviewing on behalf of abumalick December 16, 2025 09:26 View session

Copilot AI reviewed Dec 16, 2025

View reviewed changes

docs/cli.md Show resolved Hide resolved

packages/openapi-typescript/src/types.ts Outdated Show resolved Hide resolved

abumalick force-pushed the feat/read-write-markers branch from b1d920a to 3dd3cf1 Compare December 16, 2025 10:03

abumalick marked this pull request as draft December 16, 2025 11:06

abumalick marked this pull request as ready for review December 24, 2025 06:51

abumalick mentioned this pull request Dec 24, 2025

Support "readOnly" and "writeOnly" OpenAPI properties #604

Closed

htunnicliff removed their request for review December 30, 2025 17:23

drwpow approved these changes Feb 8, 2026

View reviewed changes

drwpow mentioned this pull request Feb 8, 2026

feat: Proposal of an approach to support readOnly / writeOnly properties #1863

Closed

3 tasks

abumalick added 3 commits February 9, 2026 07:55

fix: export read-write helper types in generated output

f2cf767

fix: Readable/Writable types now recursively unwrap nested markers

fd239b8

When Readable<$Read> was resolved, it returned U directly instead of Readable, causing nested $Read markers inside U to not be unwrapped. Same issue for Writable<$Write>.

abumalick force-pushed the feat/read-write-markers branch from 61d7b87 to fd239b8 Compare February 9, 2026 04:55

fix: biome formatting in helpers

46a6e86

abumalick force-pushed the feat/read-write-markers branch from d8dd87b to 46a6e86 Compare February 9, 2026 05:03

drwpow merged commit a690e52 into openapi-ts:main Feb 11, 2026
7 checks passed

openapi-ts-bot mentioned this pull request Feb 11, 2026

[ci] release #2611

Merged

Uh oh!

feat(openapi-typescript): add readOnly/writeOnly support via markers #2549

feat(openapi-typescript): add readOnly/writeOnly support via markers #2549

Uh oh!

Conversation

abumalick commented Dec 16, 2025

Summary

Test plan

Uh oh!

changeset-bot bot commented Dec 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

netlify bot commented Dec 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

👷 Deploy request for openapi-ts pending review.

Uh oh!

abumalick commented Dec 16, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

abumalick commented Dec 16, 2025

Uh oh!

abumalick commented Dec 24, 2025

Uh oh!

abumalick commented Dec 30, 2025

Uh oh!

abumalick commented Jan 13, 2026

Uh oh!

abumalick commented Feb 5, 2026

Uh oh!

drwpow left a comment

Choose a reason for hiding this comment

Uh oh!

drwpow commented Feb 8, 2026

Uh oh!

abumalick commented Feb 9, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

changeset-bot bot commented Dec 16, 2025 •

edited

Loading

netlify bot commented Dec 16, 2025 •

edited

Loading