Global Actions

This page documents all the root level mutations powered by Global Actions in the Model Testing API.

Action Result format

Each API action returns results in the same format that includes a success indicator, errors, and the actual result if the action succeeded. The result is the record that was acted on for a model action, or a list of records for a bulk action, or a JSON blob for Global Actions. Model actions that delete the record don't return the record.

The success field returns a boolean indicating if the action executed as expected. Any execution errors are returned in the errors object, which will always be null if success is true or contain ExecutionError objects if success is false.

ExecutionError objects always have a message describing what error prevented the action from succeeding, as well as a code attribute that gives a stable, searchable, human readable error class code for referencing this specific error. Details on each error code can be found in the Errors documentation. All ExecutionError object types returned by the GraphQL object can be one of many types of error, where some types have extra data that is useful for remedying the error. All error types will always have message and code properties, but some, like InvalidRecordError have extra fields for use by clients.

Errors when using the generated client

The generated JavaScript client automatically interprets errors from invoking actions and throws JavaScript Error instances if the action didn't succeed. The Error objects it throws are rich, and expose extra error properties beyond just message and code if they exist.

Errors thrown by the JavaScript client are easiest to catch by using a try/catch statement around an await, like so:

JavaScript
1import {
2 GadgetOperationError,
3 GadgetValidationError,
4} from "@gadget-client/example-app";
5
6// must be in an async function to use `await` syntax
7const runAction = async () => {
8 try {
9 return await api.exampleModel.create(
10 {
11 exampleModel: {
12 name: "example record name",
13 },
14 }
15 );
16 } catch (error) {
17 if (
18 error instanceof
19 GadgetOperationError
20 ) {
21 // a recognized general error has occurred, retry the operation or inspect error.code`
22 console.error(error);
23 } else if (
24 error instanceof
25 GadgetValidationError
26 ) {
27 // the submitted input data for the action was invalid, inspect the invalid fields which `GadgetValidationError` exposes
28 console.error(
29 error.validationErrors
30 );
31 } else {
32 // an unrecognized error occurred, like an HTTP connection interrupted error or a syntax error. Re-throw it because it's not clear what to do to fix ti
33 throw error;
34 }
35 }
36};

For more information on error codes, consult the Errors documentation.

File upload

Example File upload Invocation
const result = await api.fileUpload();
console.log(result); //=> a JSON blob returned by the global action
const [result, fileUpload] = useGlobalAction(api.fileUpload);
const { data, error, fetching } = result;
await fileUpload();
console.log(result.data); //=> a JSON blob returned by the global action
1mutation {
2 fileUpload {
3 success
4 errors {
5 message
6 ... on InvalidRecordError {
7 validationErrors {
8 apiIdentifier
9 message
10 }
11 }
12 }
13 }
14}
Variables
json
{}
Output

File upload returns whatever data the effects within it produce.

File upload Output
type FileUploadResult {
success: Boolean!
errors: [ExecutionError!]
result: JSON
}

Test Action

Example Test Action Invocation
const result = await api.testAction();
console.log(result); //=> a JSON blob returned by the global action
const [result, testAction] = useGlobalAction(api.testAction);
const { data, error, fetching } = result;
await testAction();
console.log(result.data); //=> a JSON blob returned by the global action
1mutation {
2 testAction {
3 success
4 errors {
5 message
6 ... on InvalidRecordError {
7 validationErrors {
8 apiIdentifier
9 message
10 }
11 }
12 }
13 }
14}
Variables
json
{}
Output

Test Action returns whatever data the effects within it produce.

Test Action Output
type TestActionResult {
success: Boolean!
errors: [ExecutionError!]
result: JSON
}

Test Action2

Example Test Action2 Invocation
const result = await api.testAction2();
console.log(result); //=> a JSON blob returned by the global action
const [result, testAction2] = useGlobalAction(api.testAction2);
const { data, error, fetching } = result;
await testAction2();
console.log(result.data); //=> a JSON blob returned by the global action
1mutation {
2 testAction2 {
3 success
4 errors {
5 message
6 ... on InvalidRecordError {
7 validationErrors {
8 apiIdentifier
9 message
10 }
11 }
12 }
13 }
14}
Variables
json
{}
Output

Test Action2 returns whatever data the effects within it produce.

Test Action2 Output
type TestAction2Result {
success: Boolean!
errors: [ExecutionError!]
result: JSON
}