feat(openapi-generator): suggest resolution for unknown codec types #974
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
The Problem
-----------
If you try to import a codec from `io-ts-types` like this:
```typescript
import { DateFromISOString} from 'io-ts-types/DateFromISOString';
```
you will see an error like this:
```
node_modules/@api-ts/openapi-generator/dist/src/codec.js:287
if (init.type === 'Identifier' || init.type === 'MemberExpression') {
^
TypeError: Cannot read properties of null (reading 'type')
```
This is not a helpful error message, as it does not indicate
1. What went wrong?
2. What does the user need to do to fix it?
Additional Context
------------------
Since codecs from `io-ts-types` are frequently used,
@api-ts/openapi-generator ships with knowledge of `io-ts-types`
codecs[^1]. However, these defaults only match against the user's code
when the user imports from the top-level `io-ts-types` package, like
this:
```typescript
import { DateFromISOString} from 'io-ts-types';
```
This Change
-----------
This diff detects when @api-ts/openapi-generator encounters a codec
for which it cannot determine encode/decode types. This happens when a
codec is declared with `t.Type` instead of the io-ts combinators, which
happens in `io-ts-types` and in some third-party modules.
In this case, the generator will now print a message informing the
user what went wrong, and provides a suggestion on how the user should
resolve the issue:
> [ERROR] Could not determine encode/decode types for codec 'MyCustomCodec' in '~/workspace/node_modules/my-custom-types/lib/MyCustomType.d.ts'
> Consider defining a custom codec for this type.
>
> https://github.com/BitGo/api-ts/tree/master/packages/openapi-generator#4-defining-custom-codecs
Additionally, when the path defining the codec comes from `io-ts-types`,
the message is even more specific:
> [ERROR] Could not determine encode/decode types for codec 'DateFromISOString' in '~/workspace/node_modules/io-ts-types/lib/DateFromISOString.d.ts'
> It looks like this codec comes from io-ts-types. Try importing directly from io-ts-types instead:
>
> ```
> import { DateFromISOString } from 'io-ts-types';
> ```
Considerations
--------------
I was not able to easily write any tests for this functionality, since
our test harness does not currently handle failure cases and asserting
against given error messages.
[^1]: https://github.com/BitGo/api-ts/blob/b214578caa8272e8370025ae3ef6fd7bf45d514c/packages/openapi-generator/src/knownImports.ts#L334
ghost
approved these changes
Dec 24, 2024
|
🎉 This PR is included in version @api-ts/openapi-generator@5.4.0 🎉 The release is available on npm package (@latest dist-tag) Your semantic-release bot 📦🚀 |
|
🎉 This PR is included in version @api-ts/typed-express-router@2.0.0-beta.1 🎉 The release is available on npm package (@beta dist-tag) Your semantic-release bot 📦🚀 |
|
🎉 This PR is included in version @api-ts/express-wrapper@2.0.0-beta.1 🎉 The release is available on npm package (@beta dist-tag) Your semantic-release bot 📦🚀 |
|
🎉 This PR is included in version @api-ts/typed-express-router@1.1.14 🎉 The release is available on npm package (@latest dist-tag) Your semantic-release bot 📦🚀 |
|
🎉 This PR is included in version @api-ts/express-wrapper@1.0.34 🎉 The release is available on npm package (@latest dist-tag) Your semantic-release bot 📦🚀 |
|
🎉 This PR is included in version @api-ts/superagent-wrapper@1.3.4 🎉 The release is available on npm package (@latest dist-tag) Your semantic-release bot 📦🚀 |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The Problem
If you try to import a codec from
io-ts-typeslike this:you will see an error like this:
This is not a helpful error message, as it does not indicate
Additional Context
Since codecs from
io-ts-typesare frequently used, @api-ts/openapi-generator ships with knowledge ofio-ts-typescodecs1. However, these defaults only match against the user's code when the user imports from the top-levelio-ts-typespackage, like this:This Change
This diff detects when @api-ts/openapi-generator encounters a codec for which it cannot determine encode/decode types. This happens when a codec is declared with
t.Typeinstead of the io-ts combinators, which happens inio-ts-typesand in some third-party modules.In this case, the generator will now print a message informing the user what went wrong, and provides a suggestion on how the user should resolve the issue:
Additionally, when the path defining the codec comes from
io-ts-types, the message is even more specific:Considerations
I was not able to easily write any tests for this functionality, since our test harness does not currently handle failure cases and asserting against given error messages.
Footnotes
https://github.com/BitGo/api-ts/blob/b214578caa8272e8370025ae3ef6fd7bf45d514c/packages/openapi-generator/src/knownImports.ts#L334 ↩