pdellaert
commented
4 months ago I like this in general, but needs a deeper review than I can do right now :)
Open ExampleWasTaken opened 4 months ago
pdellaert
commented
4 months ago I like this in general, but needs a deeper review than I can do right now :)
Overview
Using 3rd-party APIs in statically typed languages poses a challenge as you need some way to validate the type of the returned data to avoid type errors at runtime. So far, the codebase used TypeScript's
anytype on responses from 3rd-party APIs to access values on the returned data. Asanybasically means opting out of all type checking, it's best practice to avoid its usage wherever possible. Therefore, the upcoming lint overhaul will disallowanycompletely.Refactoring all currently used API implementations to avoid using
anyis too complex to be included in the lint overhaul. This PR is a mix offeatandrefactor: It introduces a new generic API wrapper and migrates all existing 3rd-party APIs to use it.Description
The API wrapper uses the 3rd-party library Zod to validate the returned data against statically declared schemas. It leverages TypeScript's ability to implicitly infer types thereby enabling type checking on the returned data. Code completion on the returned data is another QoL feature added by this PR/library.
Basic usage
Details
Using the wrapper is as simple as declaring a Zod schema for the returned data: ```ts import { z } from 'zod'; export const PersonSchema = z.object({ name: z.string(), age: z.number(), }); export type Person = z.infer;
```
Then using the `fetchForeignAPI(request, schema)` method:
```ts
import { Request } from 'node-fetch';
try {
const data = await fetchForeignAPI(new Request('https://api.example.com/'), PersonSchema);
data.[name, age] // code completion and type checking
} catch (e) {
if (e instanceof ZodError) {
// full access to the error - note that fetchForeignAPI() already logs the error to the console as well as the endpoint from which the data was retrieved
}
}
```
For simplicity you can also just pass a `URL` object or `string` to `fetchForeignAPI()`.
Testing
A list of all modified commands can be found below. While testing make sure to use improbable inputs as well as more typical inputs. E.g. requesting station/taf/metar information from small airports, airports with almost no traffic etc. Consider any case where the command doesn't succeed as 'failed'. The goal is to get correct typing, not limit the data we can show/use.
Affected Commands
| Command | Status | |--------|--------| | `/vatsim data` | ✅ |
| `/vatsim events` |  |
| `/station` |  |
| `/taf` |  |
| `/metar` |  |
| `/live-flights` |  |
| `/simbrief-data retrieve` |  |
| `/wolframalpha` |  |
Additional Information
The
/tafembed has been slightly modified to be more consistent. Instead of decoding the first part of the TAF only, it now only provides the raw string and links to our docs and https://e6bx.com/weather/{ICAO}/?showDecoded=1&focuspoint=tafdecoder which decodes the TAF for the queried airport.Discord Username
examplewastaken