Type Safety

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

How strict are the types?

The Simple Blog Example 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:

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

GadgetRecord and Return Types

The Simple Blog Example 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 that includes all of the data stored on each record of the model. Things like string, number and other scalar values will be included in the default selection, but relationship fields like has many or has many fields will not be included. This default selection 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 Simple Blog Example client includes type information for all the fields present in the Simple Blog Example 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/simple-blog-example
yarn upgrade @gadget-client/simple-blog-example