Type Safety

The Model Testing client package includes TypeScript types by default. No special installation steps are necessary to take advantage of the type information that the Model Testing client has.

How strict are the types?

The Model Testing client includes full type safety for all the high level JavaScript functions like find and findMany. Your API client goes to great lengths to provide you with useful, reliable types for API requests and responses. When you use the select option to retrieve only some fields, the client maps your field selection to its knowledge of the underlying GraphQL schema and returns an object with only the selected fields and the correct types for each of them.

For example, this TypeScript will fetch only the id and name of a User model:

TypeScript
1const users = await api.user.findMany({
2 select: { id: true, name: true },
3});
4
5console.log(users[0].id);
6// will typecheck just fine as the type `string`, and log an ID string for the user
7
8console.log(users[0].name);
9// will typecheck just fine as the type of the `name` field as set in the Gadget Editor, and log the value
10
11console.log(users[0].email);
12// will _fail_ the typecheck, as the `email` key was not included in the `select` option

GadgetRecord and Return Types

The Model Testing client returns a type called GadgetRecord for all single record operations, and a GadgetRecordList for all array-of-record operations. These objects are lightweight wrappers around basic JavaScript objects that add handy utility functions like toJSON. These objects don't have functions to mutate themselves, and so after being loaded, they don't affect and aren't affected by server side state. If you want to change a GadgetRecord, make an API call with the client and pass new values for the record as the input, like api.user.update("10", {name: "foo"}).

Default Selection

Gadget makes a default selection when you don't pass the select option to a finder, which will include all the model's scalar fields and a small representation of its related records. This default is also type safe, so you can rely on the returned objects from default finder methods returning type safe GadgetRecord results conforming to the default shape. To figure out exactly what your client will select by default for a model, see the documentation for that model.

Client Regeneration

The Model Testing client includes type information for all the fields present in the Model Testing API when the client was generated. If you edit the application to add new fields, or change field types, the API client package's types will be out of date, and may generate erroneous type errors. You must upgrade your API client package to the newest version to resolve this.

You can upgrade your API client package by fetching the latest version from the registry, like so:

npm update @gadget-client/model-testing
yarn upgrade @gadget-client/model-testing