Behavior change in 0.17.0 for array and prefixItems

[panwauu]

openapi-fetch version

0.17.0

Description

I am no expert with openapi so be understanding if i formulate or understand something wrong.

I am generating a openapi.json file from my python backend and using this to generate a client in typescript to ensure compatability. With the update to version 0.17.0 i get some typescript errors. The generated code does not change but the types in frontend does. The response.data was typed as [string, string][] before and is string[][] now.

Does anyone else have this problem?

Reproduction

My openapi definition looks like this:

          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "array",
                    "prefixItems": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "string"
                      }
                    ],
                    "minItems": 2,
                    "maxItems": 2
                  },
                  "title": "Response Get Personal By Substring Api Get Personal By Substring Get"
                }
              }
            }
          },

The generated ts code looks like this:

            200: {
                headers: {
                    [name: string]: unknown;
                };
                content: {
                    "application/json": [
                        string,
                        string
                    ][];
                };
            };

With version 0.17.0 i get a more generic type even though the type in the generated code is fine and what i would expect:

data: string[][]

Expected result

With version 0.16.0 i get the expected type for my response.data:

data: [string, string][]

I would expect 0.17.0 to behave the same way

Extra

• I’m willing to open a PR (see CONTRIBUTING.md)

[aperkaz]

I am having the same issue, is this a regression or an expected feature?

[panwauu]

Honestly for me this is a regression as the new type in typescript is less narrow than the type before and also less narrow than the openapi definition. Could somebody with experience in this repository comment on this?

I personally am not even sure from which package the problem originates. Aka is it a change in openapi-fetch that causes the change or maybe in openapi-typescript-helpers

[panwauu]

Analysis by Claude Code

I hope this helps to understand the issue and may help a potential merge request

Root Cause Analysis

The regression was introduced in PR #2549, which added readOnly/writeOnly support via Readable<T> and Writable<T> helper types.

What changed

In openapi-fetch 0.17.0, response data is now wrapped with Readable<T> (index.d.ts#L114):

- data: ParseAsResponse<SuccessResponse<ResponseObjectMap<T>, Media>, Options>;
+ data: ParseAsResponse<Readable<SuccessResponse<ResponseObjectMap<T>, Media>>, Options>;

This applies Readable<T> unconditionally to all responses — even when --read-write-markers is not enabled and no $Read/$Write markers exist in the schema.

Why tuples break

The Readable<T> type in openapi-typescript-helpers/src/index.ts#L219-L228 has an array branch that destroys tuple types:

export type Readable<T> =
  T extends $Write<any> ? never
  : T extends $Read<infer U> ? Readable<U>
  : T extends (infer E)[] ? Readable<E>[]   // ← bug
  : T extends object ? { [K in keyof T as ...]: Readable<T[K]> }
  : T;

T extends (infer E)[] matches tuples (tuples extend arrays), but infers the union of all element types as E, collapsing the tuple structure:

1. Readable<[string, string][]> → Readable<[string, string]>[]
2. Readable<[string, string]> → matches (infer E)[] again → E = string → string[]
3. Result: string[][] instead of [string, string][]

The same issue exists in Writable<T> (index.ts#L236-L247) which uses identical array handling.

Suggested fix

Replace the array branch with a mapped type that preserves tuple structure:

- : T extends (infer E)[] ? Readable<E>[]
+ : T extends readonly any[] ? { [K in keyof T]: Readable<T[K]> }

TypeScript's mapped types over tuples are special-cased to preserve tuple shape. Applying { [K in keyof T]: Readable<T[K]> } to [string, string] produces [string, string], while on a regular string[] it produces string[] — correct in both cases.

The same change should be applied to Writable<T>.

[panwauu]

I added MR #2673 which should fix the problem in my view

[panwauu]

It seems that openapi-fetch will not recieve more updates (#2559). Hope that this regression will be fixed anyways