Typeid support

[Le0Developer]

See #2033

This is a very rough draft. I originally tried to use the x-typeid-type property I proposed in jetify-com/typeid#45. Then I noticed there's an IR involved and decided to temporarily extract the type name from the example field instead (which I also had to add to the parsers/IR).

I've tested this by modifying the openapi-ts-fetch example. I downloaded the openapi.yml file and modified the id property of Order to be a typeid like this:

        id:
          type: string
          format: typeid
          example: order_1111

And added typeids: true, to the openapi-ts.config.ts file.

This produced this output:

type TypeID<T extends string> = `${T}_${string}`;

export type Order = {
  complete?: boolean;
  id?: TypeID<'order'>;
  /* ... */
}

Nice 🎉

Currently the TypeID declaration is always added. Which means if you enable the config option but don't use typeids, you'll get an unused type warning.

Questions

• I want to use x-typeid-type instead of parsing the example value, but I'm unsure given the current IR infrastructure. I don't believe adding arbitrary extensions to the parser is maintainable. One I had was: what if the IR had an extra field which simply contained the original object or just x-* properties? This feels more future-proof to me.
• Should TypeID<T> be exported or should consumers do User["id"] instead of TypeID<"user"> if they want to access the type themselves?
• Should there be a concrete type per ID (eg type UserID = "user_${string}") instead of the TypeID "overlord" (or maybe both)? This would require extending the "State" interface to keep track of already generated ID types

[bolt-new-by-stackblitz]

Run & review this pull request in StackBlitz Codeflow.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 31bdccd

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
hey-api-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	May 12, 2025 9:48am

[pkg-pr-new]

Open in StackBlitz

@hey-api/client-axios

npm i https://pkg.pr.new/hey-api/openapi-ts/@hey-api/client-axios@2034

@hey-api/client-fetch

npm i https://pkg.pr.new/hey-api/openapi-ts/@hey-api/client-fetch@2034

@hey-api/client-next

npm i https://pkg.pr.new/hey-api/openapi-ts/@hey-api/client-next@2034

@hey-api/client-nuxt

npm i https://pkg.pr.new/hey-api/openapi-ts/@hey-api/client-nuxt@2034

@hey-api/nuxt

npm i https://pkg.pr.new/hey-api/openapi-ts/@hey-api/nuxt@2034

@hey-api/openapi-ts

npm i https://pkg.pr.new/hey-api/openapi-ts/@hey-api/openapi-ts@2034

@hey-api/vite-plugin

npm i https://pkg.pr.new/hey-api/openapi-ts/@hey-api/vite-plugin@2034

commit: 31bdccd

[codecov]

Codecov Report

Attention: Patch coverage is 2.04082% with 48 lines in your changes missing coverage. Please review.

Project coverage is 22.59%. Comparing base (66f89a4) to head (31bdccd).

Files with missing lines	Patch %	Lines
...enapi-ts/src/plugins/@hey-api/typescript/plugin.ts	0.00%	39 Missing ⚠️
...ages/openapi-ts/src/openApi/2.0.x/parser/schema.ts	0.00%	3 Missing ⚠️
...ages/openapi-ts/src/openApi/3.0.x/parser/schema.ts	0.00%	3 Missing ⚠️
...ages/openapi-ts/src/openApi/3.1.x/parser/schema.ts	0.00%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2034      +/-   ##
==========================================
- Coverage   22.64%   22.59%   -0.05%     
==========================================
  Files         252      252              
  Lines       21475    21524      +49     
  Branches      818      818              
==========================================
+ Hits         4862     4863       +1     
- Misses      16607    16655      +48     
  Partials        6        6              

Flag	Coverage Δ
unittests	22.59% <2.04%> (-0.05%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Le0Developer]

Hey @mrlubos before adding tests and solving the merge conflicts I was wondering what your thoughts were on the previously raised questions in the initial PR message?
It's currently getting the typeid prefix from the example field since adding x-typeid-prefix to the schema felt more awkward (since example could be reused and added to the doc comments in the future?).

Or alternatively should openapi-ts get a better plugin interface so this can be done externally?

[mrlubos]

Hi @Le0Developer, are you able to keep using the preview builds generated by this pull request? I will have some thoughts around developer experience but I think most of your ideas/questions are valid and need addressing, including a better plugin interface. Unfortunately, the current priorities lie elsewhere so I won't have time to address this improvement just yet, but wanted to give you at least some response