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 type Session = {
2
3  __typename: 'Session';
4
5  /** The globally unique, unchanging identifier for this record. Assigned and managed by Gadget. */
6  id: string;
7
8  /** The time at which this record was first created. Set once upon record creation and never changed. Managed by Gadget. */
9  createdAt: Date;
10
11  /** The time at which this record was last changed. Set each time the record is successfully acted upon by an action. Managed by Gadget. */
12  updatedAt: Date;
13
14  user: (User | null);
15
16  userId: string;
17
18  roles: Role[];
19
20  /** Get all the fields for this record. Useful for not having to list out all the fields you want to retrieve, but slower. */
21  _all: Record<string, any>;
22};

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  user: User
17  userId: GadgetID
18  roles: [Role!]
19
20  """
21  Get all the fields for this record. Useful for not having to list out all the fields you want to retrieve, but slower.
22  """
23  _all: JSONObject!
24}

You can preview what a real record's shape looks like by fetching it using the  openai-screenwriter-tutorial-v2 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 openai-screenwriter-tutorial-v2 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 openai-screenwriter-tutorial-v2.

openai-screenwriter-tutorial-v2 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.

1const record = await api.currentSession.get();
2// => a string
3console.log(record.id);
4// => a state value like { "created": "loggedOut" }
5console.log(record.state);
6// => a Date object
7console.log(record.createdAt);

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

1query GetCurrentSession {
2  currentSession {
3    id
4    createdAt
5  }
6}

{}

1const record = await api.currentSession.get();
2// => a string
3console.log(record.id);
4// => a state value like { "created": "loggedOut" }
5console.log(record.state);
6// => a Date object
7console.log(record.createdAt);

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

export const run: ActionRun = async ({ params, logger, api, session }) => {
  const { user } = session;
  // ...
};

export const run: ActionRun = async ({ params, logger, api, session }) => {
  const { user } = session;
  // ...
};

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 with a GraphQL API trigger 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:

1import {
2  GadgetOperationError,
3  InvalidRecordError,
4} from "@gadgetinc/api-client-core";
5
6// must be in an async function to use await` syntax
7export async function run({ api }) {
8  try {
9    return await api.exampleModel.create({ name: "example record name" });
10  } catch (error) {
11    if (error instanceof GadgetOperationError) {
12      // a recognized general error has occurred, retry the operation or inspect \error.code\`
13      console.error(error);
14    } else if (error instanceof InvalidRecordError) {
15      // the submitted input data for the action was invalid, inspect the invalid fields which \`InvalidRecordError\` exposes
16      console.error(error.validationErrors);
17    } else {
18      // 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 it
19      throw error;
20    }
21  }
22}

1import {
2  GadgetOperationError,
3  InvalidRecordError,
4} from "@gadgetinc/api-client-core";
5
6// must be in an async function to use await` syntax
7export async function run({ api }) {
8  try {
9    return await api.exampleModel.create({ name: "example record name" });
10  } catch (error) {
11    if (error instanceof GadgetOperationError) {
12      // a recognized general error has occurred, retry the operation or inspect \error.code\`
13      console.error(error);
14    } else if (error instanceof InvalidRecordError) {
15      // the submitted input data for the action was invalid, inspect the invalid fields which \`InvalidRecordError\` exposes
16      console.error(error.validationErrors);
17    } else {
18      // 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 it
19      throw error;
20    }
21  }
22}

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