Session

This page documents the Session model.

Data Shape

Gadget's database stores Session records by storing and retrieving each of the fields defined on the model in the Gadget Editor to a managed database. Gadget has generated a GraphQL type matching the configured fields for Session:

1export interface Session {
2 __typename: "Session";
3
4 /** The globally unique, unchanging identifier for this record. Assigned and managed by Gadget. */
5 id: Scalars["GadgetID"];
6
7 /** The time at which this record was first created. Set once upon record creation and never changed. Managed by Gadget. */
8 createdAt: Scalars["DateTime"];
9
10 /** The time at which this record was last changed. Set each time the record is successfully acted upon by an action. Managed by Gadget. */
11 updatedAt: Scalars["DateTime"];
12
13 /** The current state this record is in. Changed by invoking actions. Managed by Gadget. */
14 state: Scalars["RecordState"];
15
16 user: User | null;
17
18 userId: Scalars["GadgetID"] | null;
19
20 roles: Role[];
21
22 /** Get all the fields for this record. Useful for not having to list out all the fields you want to retrieve, but slower. */
23 _all: Scalars["JSONObject"];
24}
1type Session {
2 """
3 The globally unique, unchanging identifier for this record. Assigned and managed by Gadget.
4 """
5 id: GadgetID!
6
7 """
8 The time at which this record was first created. Set once upon record creation and never changed. Managed by Gadget.
9 """
10 createdAt: DateTime!
11
12 """
13 The time at which this record was last changed. Set each time the record is successfully acted upon by an action. Managed by Gadget.
14 """
15 updatedAt: DateTime!
16
17 """
18 The current state this record is in. Changed by invoking actions. Managed by Gadget.
19 """
20 state: RecordState!
21 user: User
22 userId: GadgetID
23 roles: [Role!]
24
25 """
26 Get all the fields for this record. Useful for not having to list out all the fields you want to retrieve, but slower.
27 """
28 _all: JSONObject!
29}

You can preview what a real record's shape looks like by fetching it using the blog API Playground.

Any fetched Session record will have this same Session type, and expose the same data by default, regardless of where it comes from. This means you can select any of the record's fields wherever you like in a GraphQL query according to the use case at hand.

Session for Session Storage and Authentication

The Session powers session functionality for the blog app. Sessions store transient data specific to one browser interacting with the application, like whether a banner message has been shown, or anything else that needs to be specific to each session someone has with blog.

blog uses Session to power user authentication using actions on Session. Each user's current Session is accessible using special GraphQL fields for querying and mutating. Session are stored in the Gadget platform similarly to other models, but have this extra functionality for convenient access to the current Session.

Because of this, Session does not have normal findOne, maybeFindOne, findMany, findFirst, maybeFindFirst, or create actions. The Gadget platform manages the lifecycle of Session records, and uses cookies to associate them with browser requests as needed.

Session can still be managed like other models using the Internal API .

Retrieving the current Session record

The current Session record for a request can be retrieved using the

currentSession GraphQL field, or the .currentSession.get() JS client function. You can also return only some fields, or extra fields beyond what Gadget retrieves by default, using the select option.

The findOne, maybeFindOne, findMany, findFirst, and maybeFindFirst record readers do not exist for Session. If you need to change arbitrary records, or iterate the list of Session, you can use the Internal API for Session.

const record = await api.currentSession.get();
console.log(record.id); //=> a string
console.log(record.state); //=> a state value like { "created": "loggedOut" }
console.log(record.createdAt); //=> a Date object
const [result, refresh] = useGet(api.currentSession);
const { data, error, fetching } = result;
console.log(result.data?.id); //=> a string
console.log(result.data?.state); //=> a state value like { "created": "loggedOut" }
console.log(result.data?.createdAt); //=> a Date object
1query GetCurrentSession {
2 currentSession {
3 id
4 state
5 createdAt
6 }
7}
Variables
json
{}

Invoking Actions

Session records are changed by invoking Actions. Action are the things that "do" stuff -- creating data, deleting data, making API calls to other services, etc. Actions each have one corresponding GraphQL mutation and a corresponding function available in the API client libraries.

Actions for Session are executed on the currentSession GraphQL field, or the .currentSession JS client ModelManager object. Each of these automatically refers to the Session for the current browser session.

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 InvalidRecordError,
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 exampleModel: { name: "example record name" },
11 });
12 } catch (error) {
13 if (error instanceof GadgetOperationError) {
14 // a recognized general error has occurred, retry the operation or inspect error.code`
15 console.error(error);
16 } else if (error instanceof InvalidRecordError) {
17 // the submitted input data for the action was invalid, inspect the invalid fields which `InvalidRecordError` exposes
18 console.error(error.validationErrors);
19 } else {
20 // 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
21 throw error;
22 }
23 }
24};

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

Session Log In Via Email

The Log In Via Email action transitions a Session from Logged Out to Logged In.

Input

Log In Via Email operates on the current Session for the API client making a request. The Gadget platform manages which Session is available, and no `id` parameter should be passed. The Log In Via Email action takes this input:

export interface LogInViaEmailArguments {
email?: (Scalars["String"] | null) | null;
password?: (Scalars["String"] | null) | null;
}
input LogInViaEmailArguments {
email: String
password: String
}
Example Invocation
const record = await api.currentSession.logInViaEmail({
// action input data
});
console.log(record.id); //=> a string
console.log(record.state); //=> a state value, like { "created": "loggedOut" }
1const [result, logInViaEmailCurrentSession] = useAction(
2 api.currentSession.logInViaEmail
3);
4const { data, error, fetching } = result;
5await logInViaEmailCurrentSession({
6 // action input data
7});
8console.log(data?.id); //=> a string
9console.log(data?.state); //=> a state value, like { "created": "loggedOut" }
1mutation ($email: LogInViaEmailEmailInput, $password: String) {
2 currentSession {
3 logInViaEmail(email: $email, password: $password) {
4 success
5 errors {
6 message
7 ... on InvalidRecordError {
8 validationErrors {
9 apiIdentifier
10 message
11 }
12 record
13 model {
14 apiIdentifier
15 }
16 }
17 }
18 session {
19 __typename
20 id
21 state
22 createdAt
23 roles {
24 key
25 name
26 }
27 updatedAt
28 }
29 }
30 }
31}
Variables
json
{ "session": {} }
Output

Log In Via Email returns data in the action result format, which includes the record if the action was successful. The fields returned for the record can be controlled with the select option.

1export interface LogInViaEmailSessionResult {
2 __typename: "LogInViaEmailSessionResult";
3
4 success: Scalars["Boolean"];
5
6 errors: ExecutionError[];
7
8 session: Session | null;
9}
type LogInViaEmailSessionResult {
success: Boolean!
errors: [ExecutionError!]
session: Session
}

Session Log Out

The Log Out action transitions a Session from Logged In to Logged Out.

Input

Log Out operates on the current Session for the API client making a request. The Gadget platform manages which Session is available, and no `id` parameter should be passed. The Log Out action takes this input:

Example Invocation
const record = await api.currentSession.logOut();
console.log(record.id); //=> a string
console.log(record.state); //=> a state value, like { "created": "loggedOut" }
const [result, logOutCurrentSession] = useAction(api.currentSession.logOut);
const { data, error, fetching } = result;
await logOutCurrentSession();
console.log(data?.id); //=> a string
console.log(data?.state); //=> a state value, like { "created": "loggedOut" }
1mutation {
2 currentSession {
3 logOut {
4 success
5 errors {
6 message
7 ... on InvalidRecordError {
8 validationErrors {
9 apiIdentifier
10 message
11 }
12 record
13 model {
14 apiIdentifier
15 }
16 }
17 }
18 session {
19 __typename
20 id
21 state
22 createdAt
23 roles {
24 key
25 name
26 }
27 updatedAt
28 }
29 }
30 }
31}
Variables
json
{}
Output

Log Out returns data in the action result format, which includes the record if the action was successful. The fields returned for the record can be controlled with the select option.

1export interface LogOutSessionResult {
2 __typename: "LogOutSessionResult";
3
4 success: Scalars["Boolean"];
5
6 errors: ExecutionError[];
7
8 session: Session | null;
9}
type LogOutSessionResult {
success: Boolean!
errors: [ExecutionError!]
session: Session
}