feat(codegen): x-expanded-relations

[patrick-medusajs]

What

Alter generated types base on x-expanded-relations OAS extension declared on schemaObjects.

Why

Often, API endpoints will automatically expand a model relations by default. They can also decorate a model with calculated totals. In order to more accurately represent the API, we wish to alter the generated types based on the expanded relations information.

How

• Follow the relation declaration signature as the backend controllers and the expand query param, i.e.: items.variant.product.
• Introduce a custom x-expended-relations OAS extension.
• Allow for organizing declared relations to help their maintenance.
• Use traversal algorithms in codegen to support deeply nested relationships.
• Use type-fest's Merge and SetRequired to efficiently alter the types while enabling great intellisense for IDEs.

Extra scope:

• Added convenience yarn script to interact with the medisa-oas CLI within the monorepo.

Test

Include in the PR are two implementations of the x-expanded-relations on OAS schema, a simple and a complex one.

Step 1

• Run yarn install
• Run yarn build
• Run yarn medusa-oas oas --type combined --out-dir ~/tmp/oas
• Run yarn medusa-oas client --type combined --component types --src-file ~/tmp/oas/combined.osa.json --out-dir ~/tmp/types
• Open ~/tmp/types/models/StoreRegionsRes
• Expect relations to be declared as required

Step 2

• Open ~/tmp/types/models/StoreCartsRes
• Expect relations to be declared as required
• Expect nested relations to have relations as required.

Step 3 (optional)

• Open ~/tmp/types in an intellisense capable IDE
• Within the index.ts file, attempt to declare a const storeRegionRes: StoreRegionRes = {}
• Expect IDE to highlight that countries is a required field of StoreRegionRes

[changeset-bot]

🦋 Changeset detected

Latest commit: 708eefa

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

This PR includes changesets to release 1 package

Name	Type
@medusajs/openapi-typescript-codegen	Minor

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

[vercel]

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

Name	Status	Preview	Comments	Updated
medusa-docs	✅ Ready (Inspect)	Visit Preview	💬 Add your feedback	Mar 13, 2023 at 2:18PM (UTC)

[olivermrbl]

Great job @patrick-medusajs - it works as expected!

What do you think are good next steps?

It seems like adding this to all responses is a lot of work, but it might be best to get through it now?

[patrick-medusajs]

What do you think are good next steps?

I would merge this feature as is. I would even argue that we could remove the two examples included with it.

Then, I would refactor the OAS for Store responses in one PR and do another PR for Admin responses.

It seems like adding this to all responses is a lot of work, but it might be best to get through it now?

It's not worst than editing content on a website. It might feel like tedious work but "this is the way". And yes, I would recommend tackling it now.

[olivermrbl]

@patrick-medusajs Sounds like a solid plan 💪

[patrick-medusajs]

@olivermrbl, anything missing before merging this one?