using traversable with typed-openapi

[astahmer]

hey, I'm not sure how I stumbled upon this repo but it seems awesome and I feel like it would make a lot of sense to use it to generate API clients from an OpenAPI schema

tl;dr: I spent a bit trying to figure out how to proceed with your lib but it looks like there's a skill issue on my part and I'm not sure how to integrate traversable into typed-openapi

---

I've got a library (typed-openapi) that does the OpenAPI -> API client part but it has a weird/crap codebase despite working pretty well to generate a raw TS client (with just typings, no input/output validation); but it is supposed to somewhat-work with different runtime targets (ark, zod, yup etc) using https://github.com/sinclairzx81/typebox-codegen

but the typebox-codegen/workbench lib hasnt been maintained in a while and I also didnt spend much time on it outside of the basics and also didn't care much about having the runtime validation cause I simply didnt have the use case anymore (I used to, and used to solve that with another previous library I made which generates the same thing using zod schemas and is horribly slow past a certain threshold; approximatively 3 or 5k thousand lines, hence why I wanted to get instant suggestions with a types only api client)

prior to finding typebox-codegen I had in mind to make that feature possible (different generation targets) at some point with an intermediate representation which currently only has a single TS implementation, but when I found it I simply switched to using it directly

and then much later I found your repo and figured it might be time to refactor typed-openapi codebase + use traversable to handle runtime generation and it seems like it matches well the use case

---

I'd love to use traversable to delegate the toString generation (and delete w/e is similar in my codebase) from a schema that is found in the OpenAPI schemas but I'm not sure how to handle the recursion issues / I'm not sure how to handle $ref (ideally I'd want to output the name of the $ref instead of inlining the nested schema; you can see what I mean on https://typed-openapi-web.vercel.app/)

I have a very messy branch here, you can run tests and see the issues here:

cd packages/typed-openapi       
pnpm test /Users/astahmer/dev/alex/typedapi/packages/typed-openapi/tests/openapi-schema-to-ts.test.ts

[ahrjarrett]

Hey @astahmer, thanks for reaching out.

I'm familiar with openapi-zod-client – I actually used it to build a POC at a previous company where we used OpenAPI in some very non-idiomatic ways.

The goal of that POC was to convince our RoR teams to start using OpenAPI correctly, to show them how much we could get for free – which they didn't do, so I ended up needing to write an API client that worked with the way "we did things".

That's how this project started :)

I'm a bit busy today and tomorrow, but I should have some time this weekend to clone that branch and play around with it.

[ahrjarrett]

@astahmer I spent a little time on a POC for implementing refs. Let me know how this looks as a first draft?

StackBlitz

It's still pretty naive, but hopefully that at least gives you an idea how you could use it.

Happy to iterate to get this working for your use case, since I think doing so would benefit other library authors as well.

[astahmer]

hey! that's awesome thank you so much that helps a lot!
ideally I think I don't need an IR of my own since traversable looks like what I need? not sure what I'd gain with having my own

---

I tried a using the stackblitz examples and I ended up with a few issues which makes me reconsider my current approach (OpenAPI/JSON Schema -> traversable -> TS | zod | etc):

1. when there's an unhandled schema kind, the conversion from JSON -> traversable can be done on my side (using the fold example you wrote!) but the traversable -> TS cant without you adding the case

so I'll instead try going from JSON schema to TS directly to get full control

2. sometimes the ref handling returns an object refs with the name of the ref as the key (without $/without/this/part/...) and sometimes the full $ref string is used as key

[ahrjarrett]

@astahmer cool.

Working on number 2, will update back here in the next day or two.

Regarding number 1, I can add support for oneOf nodes.

---

Question, which set of names make more sense to you?

Option 1:

/** types */
JsonSchema.Union
JsonSchema.Intersect
JsonSchema.DisjointUnion // new

/** predicates */
JsonSchema.isUnion
JsonSchema.isIntersect
JsonSchema.isDisjointUnion // new

Option 2:

/** types */
JsonSchema.AnyOf // renamed
JsonSchema.AllOf // renamed
JsonSchema.OneOf // new

/** predicates */
JsonSchema.isAnyOf // renamed
JsonSchema.isAllOf // renamed
JsonSchema.isOneOf // new

[astahmer]

nice!

I have a preference for option 2, I like when things are very explicit, with this there's no confusion possible on the internal mapping

[ahrjarrett]

Cool, that's how I was leaning too. Wanted to confirm before I broke things. Thanks!

[ahrjarrett]

@astahmer okay, I published @traversable/json-schema@0.0.22.

It features less naive (but probably still a little rough around the edges) ref handling.

Here's the changelog and an updated version of the StackBlitz.

Let me know if you have any questions or run into places where the DX could be better, happy to keep iterating!