`Readable` in new openapi-typescript-helpers is broken

[evrom]

openapi-fetch version

0.17.0

Description

it is broken using both the latest openapi-typescript package and using the previous version without re-generating the types.

I always use --immutable=true and almost all JsonSchemas in my openapi have:

      additionalProperties: false
      readOnly: true

In the latest 0.17.0 version, Arrays in the response bodies of openapi-fetch are iterable objects that remove methods for reading arrays, like .map.

 '{ readonly [x: number]: string; readonly length: number; toString: {}; toLocaleString: {}; concat: {}; join: {}; slice: {}; indexOf: {}; lastIndexOf: {}; every: {}; some: {}; forEach: {}; ... 20 more ...; readonly [Symbol.unscopables]: { ...; }; }' 

I can workaround this and get the old behavior before version 0.17.0, by putting this iterable object into Array.from, then typing it as readonly:

const openapiFetchArray = response.data.myArray; /* `Readable` object from openapi-typescript-helpers */
const desiredArray: readonly Item[] = Array.from(openapiFetchArray);

Reproduction

this is reproduced on type-checking a project using openapi-fetch after updating to 0.17.0

To reproduce in the unittests of this repo:

1. Add --immutable=true here:

   openapi-typescript/packages/openapi-fetch/package.json

   Line 49 in f3a3a19

   "generate-types": "openapi-typescript -c test/redocly.yaml",

2. add an array to the schemas in the tests (i.e. add an array as an attribute to either of these:

   openapi-typescript/packages/openapi-fetch/test/http-methods/schemas/get.yaml

   Line 46 in f3a3a19

   components:

3. in packages/openapi-fetch, run pnpm run generate-types

4. then try to call a method like .map on that array, it will break in lint:ts. However, the test may successfully run, because it is a typescript error only.

Expected result

I think this should be opt-in. I do not have --read-write-markers anywhere, or made any other changes to the code.

Extra

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

[albannurkollari]

Date in response bodies becomes a structural object and stops being assignable to Date, too!

It stems from openapi-fetch 0.17.0 update. I can confirm that I too have this issue. Right now I'm forced to lock the version to 0.15.0 (that was the safe one that worked for me).

[drwpow]

I think this should be opt-in. I do not have --read-write-markers anywhere

I agree. Given that this was less backwards-compatible than anticipated, we’ll add a flag to make this change opt-in. Sorry for the disruption here, this wasn’t as invisible as we’d hoped!

[evrom]

I have isolated this further. Removing "readOnly: true" has no effect on this bug. However, adding "--immutable=true" will re-create this, even in the unittests.

1. Add --immutable=true here:

   openapi-typescript/packages/openapi-fetch/package.json

   Line 49 in f3a3a19

   "generate-types": "openapi-typescript -c test/redocly.yaml",

2. add an array to the schemas in the tests (i.e. add an array as an attribute to either of these:

   openapi-typescript/packages/openapi-fetch/test/http-methods/schemas/get.yaml

   Line 46 in f3a3a19

   components:

3. in packages/openapi-fetch, run pnpm run generate-types

4. then try to call a method like .map on that array, it will break in lint:ts. However, the test may successfully run, because it is a typescript error only.

[evrom]

It further can be isolated by importing Readable directly from openapi-typescript-helpers.

import type {Readable} from "./index.js";
type NothingHappens = Readable<string[]>  // evaluates to `string[]`
type Broken = Readable<readonly string[]> // evaluates to strange object with every method being `{}`

[hakushun]

We hit the same kind of issue after upgrading openapi-fetch from 0.16 to 0.17 (openapi-typescript 7.12).

Summary: The type of result.data from api.GET(...) does not match the path’s 200 response type from the generated schema. Required properties on oneOf variants and full union shapes are dropped or simplified in the inferred type, so we have to cast result.data to the path type when passing it to our own functions.

---

1. oneOf variant: required id is missing in inferred type

OpenAPI (minimal, generic names only):

# components/schemas
VariantWithNullId:
  type: object
  required: [id, kind, label]
  properties:
    id: { type: string, enum: [null], nullable: true }
    kind: { type: string, enum: [a] }
    label: { type: string }

# path GET /items response 200
content:
  application/json:
    schema:
      type: object
      properties:
        list:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/VariantWithNullId'

Generated schema (openapi-typescript): VariantWithNullId has id: null (required). So the path type is { list: ({ id: null; kind: "a"; label: string } | ...)[] }.

What happens with openapi-fetch 0.17:

import createClient from 'openapi-fetch';
import type { paths } from './schema';

const client = createClient<paths>({ baseUrl: '/' });
const result = await client.GET('/items');

if (!result.error) {
  // Inferred type of result.data.list[0] for the variant
  // does NOT include `id` — it's { kind: "a"; label: string } only.
  // So this fails: "Property 'id' is missing in type ... but required in type '{ id: null; kind: "a"; ... }'"
  acceptPathResponse(result.data);
}

function acceptPathResponse(
  data: paths['/items']['get']['responses']['200']['content']['application/json']
) {
  const first = data.list[0];
  if (first.kind === 'a') {
    first.id; // we expect id: null here
  }
}

We have to use acceptPathResponse(result.data as PathResponse) so that the variant is typed with required id.

---

2. Union member simplified to { name: string } instead of full shape

OpenAPI (conceptually): A response has an array of union type (OptionA | OptionB)[] where:

• OptionA = { id: number; name: string; groupName: string; parentId: number | null }
• OptionB = { id: null; name: string; groupName: null; parentId: null } (all required).

Generated schema: The path type correctly has that union.

What happens with 0.17: The inferred type for that array becomes (OptionA | { name: string })[]. The second variant is reduced to { name: string }, so groupName and parentId are missing and we get "Property 'parentId' does not exist on type '{ name: string }'" when using the path type.

Workaround: We cast result.data to the path’s 200 response type when passing it to our own functions and added type guards that accept both the full option type and { name: string }.

---

Environment

• openapi-fetch 0.17.0
• openapi-typescript 7.12.0
• TypeScript 5.x

Runtime responses are correct; only the inferred type for result.data is wrong. Happy to provide a small repo with the minimal OpenAPI + TS if needed.

[Guuz]

Same bug happening here. The types are a union:

Device: components["schemas"]["DeviceBase"] & {
            status: "DISCONNECTED";
            propertyOverwrite: null;
        };

DeviceBase also has propertyOverwrite as a boolean for instance. Before 0.17 this correctly worked, but after 0.17 propertyOverwrite just gets removed entirely from the object and we get compiler errors due to it.

[drwpow]

So I realized our tests gave us a false positive here, which was fixed with #2646. Now that test fixture in openapi-fetch responds to changes in openapi-typescript. This is a more complicated setup that just got missed in review before shipping, but it’s been fixed.

[Guuz]

Thanks @drwpow ! :) Any idea when/what release this fix will be included?