feat: Add support for prefixItems tuple generation

[freddie-volant]

This PR extends the existing tuple generation logic to recognise the prefixItems keyword in addition to the existing items array syntax. prefixItems support was adopted in v3.1. The implementation maintains backwards compatibility with the existing handling of tuple arrays defined using items.

"TrailState": {
    "prefixItems": [
        { "$ref": "#/components/schemas/Longitude" },
        { "$ref": "#/components/schemas/Latitude" },
        { "$ref": "#/components/schemas/Timestamp" }
    ],
    "type": "array",
    "maxItems": 3,
    "minItems": 3
}

Currently produces

export type RetinaTrailState = any[];

After the change a more complete type is produced

export type RetinaTrailState = [
  RetinaLongitude,
  RetinaLatitude,
  RetinaTimestamp,
];

This appears to be related to issues/285

I've run the existing test suite and all tests pass.

I've tried to keep the change minimal and aligned with the existing tuple generation logic. However, I am open to feedback if there is a preferred approach for integrating prefixItems support within the existing schema parser design.

I haven't added testing for this new behaviour, as I wasn't sure where parser tests of this kind are expected to live. I'm happy to add one if you can point me towards the preferred location in the existing test suite.

---

Summary by cubic

Add tuple generation for array schemas that use prefixItems (OpenAPI 3.1), producing precise tuples instead of any[].

• New Features
  • Generate tuples from prefixItems with fallback to array items; non-tuple arrays unchanged.
  • Added spec test and snapshot validating prefixItems tuples; includes changeset for a patch of swagger-typescript-api. Minor schema formatting cleanup in tests.

^{Written for commit b1f519f. Summary will update on new commits.}

[changeset-bot]

🦋 Changeset detected

Latest commit: b1f519f

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

This PR includes changesets to release 1 package

Name	Type
swagger-typescript-api	Patch

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

[cubic-dev-ai]

1 issue found across 2 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/schema-parser/base-schema-parsers/array.ts">

<violation number="1" location="src/schema-parser/base-schema-parsers/array.ts:15">
P2: When `prefixItems` is combined with `items` (or omitted, implying an open tuple), the generated type is always a fixed-length closed tuple `[A, B, C]`, ignoring the `items` schema that should describe trailing/rest elements (e.g. `[A, B, ...string[]]`) or the fact that extra items of any type are allowed by default. Consider appending a rest element derived from `items` when it's present alongside `prefixItems`.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: When prefixItems is combined with items (or omitted, implying an open tuple), the generated type is always a fixed-length closed tuple [A, B, C], ignoring the items schema that should describe trailing/rest elements (e.g. [A, B, ...string[]]) or the fact that extra items of any type are allowed by default. Consider appending a rest element derived from items when it's present alongside prefixItems.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/schema-parser/base-schema-parsers/array.ts, line 15:

<comment>When `prefixItems` is combined with `items` (or omitted, implying an open tuple), the generated type is always a fixed-length closed tuple `[A, B, C]`, ignoring the `items` schema that should describe trailing/rest elements (e.g. `[A, B, ...string[]]`) or the fact that extra items of any type are allowed by default. Consider appending a rest element derived from `items` when it's present alongside `prefixItems`.</comment>

<file context>
@@ -4,11 +4,17 @@ import { MonoSchemaParser } from "../mono-schema-parser.js";
+        ? items
+        : null;
+
+    if (tupleItems && type === SCHEMA_TYPES.ARRAY) {
       const tupleContent = [];
-      for (const item of items) {
</file context>

[js2me]

@freddie-volant Thanks for your contribution!

Please add spec test (+snapshot) for this property too

[cubic-dev-ai]

No issues found across 5 files

_{Re-trigger cubic}