Fix prefixItems / minItems / maxItems tuple generation

[duncanbeevers]

Changes

Closes #2048

• Extract types generation for Array-type schemas to transformArraySchemaObject method
• Throw error when OpenAPI items is array
• Generate correct number of union members for minItems * maxItems unions
• Generate readonly tuple members for minItems & maxItems unions
• Generate readonly spread member for prefixItems tuple
• Preserve prefixItems type members in minItems & maxItems tuples
• Generate spread member for prefixItems tuple with no minItems / maxItems constraints
• Add test case for error thrown when OpenAPI items is array
• Add test case for heterogeneous item members: items: oneOf: [{ type: 'string' }, { type: 'number' }]
• Add test cases for minItems + maxItems schema generating empty tuple, as outlined in --array-length with minItems: 1 generates empty array #2048
• Add test cases for many combinations of arrayLength and immutable options, and prefixItems, minItems, maxItems schemas

The previous union+tuples generation implementation was a little hair-ball, and difficult for me to parse, so I replaced it with a stepped implementation, returning early with results whenever possible.

• first returning the full min + max union-of-tuples if possible; each union member may be readonly, but not the union as a whole
• next, returning the min tuple if possible; the tuple as a whole may be readonly, as well as its spread members.
• finally, returning the simple array type, which may be readonly

Examples

Here's a simple schema, and the before+after generated types.

☕ minItems empty tuple

components:
  schemas:
    TwoNumbers:
      type: array
      items:
        type: number
      minItems: 1
      maxItems: 2

// Before
export interface components {
    schemas: {
        TwoNumbers: [
        ] | [
            number
        ];
    };
    …

// After
export interface components {
    schemas: {
        TwoNumbers: [
            number
        ] | [
            number,
            number
        ];
    };
    …

📖 readonly spread type

components:
  schemas:
    OneNumber:
      type: array
      items:
        type: number
      minItems: 1

// Before
export interface components {
    schemas: {
        readonly OneNumber: [
            number,
            ...number[]
        ];
    };
    …

// After
export interface components {
    schemas: {
        readonly OneNumber: readonly [
            number,
            ...readonly number[]
        ];
    };
    …

🙉 preserve prefixItems

components:
  schemas:
    WithPrefixItems:
      type: array
      items:
        type: string
      prefixItems:
        - type: string
          enum:
            - professor
        - type: string
          enum:
            - student
      minItems: 2
      maxItems: 4

// Before
export interface components {
    schemas: {
        WithPrefixItems: [
            "doctor",
            "intern"
        ];
    };
    …

// After
export interface components {
    schemas: {
        WithPrefixItems: [
            "doctor",
            "intern",
            ...string[]
        ];
    };
    …

The same schema with the arrayLength: true option set generates quite different types.

// Before
export interface components {
    schemas: {
        WithPrefixItems: [
        ] | [
            [
                "doctor",
                "intern"
            ]
        ] | [
            [
                "doctor",
                "intern"
            ],
            [
                "doctor",
                "intern"
            ]
        ];
    };
    …

// After
export interface components {
    schemas: {
        WithPrefixItems: [
            "doctor",
            "intern"
        ] | [
            "doctor",
            "intern",
            string
        ] | [
            "doctor",
            "intern",
            string,
            string
        ];
    };
    …

How to Review

• Ensure generated schemas are all still acceptable
• Ensure code-style is appropriate
• Ensure newly-readonly spread member is acceptable (this may qualify as a breaking change)
• Ensure new error behavior on OpenAPI items is array is acceptable
• Ensure new spread behavior on prefixItems schemas is acceptable
• Look closely at the new tests cases, and changes to old test cases, including options and schemas passed to the schema transformer
• This PR undoes some of the work done in fix(openapi-typescript):transformSchemaObject support two-dimensional… #1489, updating its test case to use prefixItems and arrayLength in combination to generate the desired array-of-tuples

Checklist

• Unit tests updated
• docs/ updated (if necessary)
• pnpm run update:examples run (only applicable for openapi-typescript)

[changeset-bot]

🦋 Changeset detected

Latest commit: 68d9191

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

This PR includes changesets to release 2 packages

Name	Type
openapi-typescript	Major
swr-openapi	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

[drwpow]

This is amazing! To be honest this is the first time a contributor has made such an incremental improvement in the library that warranted a major version push. I’d like to get this merged, but the rest of the maintainers and myself would have to work a little bit more on the roadmap to 8.x because as of now it’s unknown. I’d like to strategize a little bit more before simply merging this and releasing a major version.

But I don’t want this PR to just sit around, waiting for that to happen. So what I’ll propose doing for now is merging this into an 8.x branch that we’ll revisit when we have more of a plan of what else constitutes the next major release. But it will ensure we build off your work here and see that this makes it in the next version.

Thank you!