Context API

The KeystoneContext object is the primary API entry point for all of the run-time functionally of your Keystone system. In GraphQL, a context is a value which is provided to every resolver and holds important contextual information such as the currently logged in user, or access to a database. Keystone makes a KeystoneContext object available as the context of all resolvers in the system. The APIs provided by the KeystoneContext object can be used to write the business logic for things like access control, hooks, testing and GraphQL schema extensions.

The KeystoneContext object has the following properties, which are documented below.

import type { KeystoneContext } from '@keystone-next/types';

context = {
  // HTTP request object
  req,

  // List item API
  lists,

  // GraphQL helpers
  graphql: {
    schema,
    run,
    raw,
  };

  // Session API
  session,
  startSession,
  endSession,

  // New context creators
  sudo,
  exitSudo,
  withSession,

  // Database access
  knex,
  prisma,
  mongoose,

  // Access control helpers
  getListAccessControlForUser,
  getFieldAccessControlForUser,

  // Internal state
  totalResults,
  maxTotalResults,
  schemaName,

  // Deprecated
  gqlNames,
  executeGraphQL,
  keystone,
};

HTTP request object

req: The IncomingMessage object from the HTTP request which called the GraphQL API.

List item API

lists: The list items API, which can be used to perform CRUD operations against your GraphQL API.

GraphQL helpers

graphql.schema: The GraphQL Schema object, which can be used directly, or via graphql.raw, graphql.run, or the lists API.

graphql.raw: An async function which takes ({ query, variables }) and executes the query against the GraphQL schema, returning { data, errors }. query can be either a string or a GraphQL Document. variables is an optional object containing the input variables for the query. The returned object is an ExecutionResult. This query uses the current context object as its context.

graphql.run: An async function which takes ({ query, variables }) and executes the query against the GraphQL schema, returning data. query can be either a string or a GraphQL Document. variables is an optional object containing the input variables for the query. The returned object is an ExecutionResult.data. Any errors generated by the query will be thrown as an exception. This query uses the current context object as its context.

See the schema extension guide for examples of using these functions.

Session API

If you configure your Keystone system with session management then you will have access to the following properties. See the session API for more details.

session: The current session data object.

startSession: An internal helper function used by authentication mutations to start a session on a successful login. This should not be called directly.

endSession: An internal helper function used by authentication mutations to end a session on logout. This should not be called directly.

New context creators

When using the context.lists, context.graphql.run, and context.graphql.raw APIs, access control and session information is passed through to these calls from the context object. The following functions will create a new KeystoneContext object with this behaviour modified.

sudo(): A function which returns a new KeystoneContext object with all access control disabled for subsequent API calls.

exitSudo(): A function which returns a new KeystoneContext object with all access control re-enabled for subsequent API calls.

withSession(newSession): A function which returns a new KeystoneContext object with the .session object replaced with newSession.

Database access

The KeystoneContext object exposes the underlying database driver directly, depending on the value of config.db.adapter.

If config.db.adapter === 'prisma_postgresql', then context.prisma will be a Prisma Client object.

If config.db.adapter === 'knex', then context.knex will be a Knex connection object.

if config.db.adapter === 'mongoose', then context.mongoose will be a Mongoose object.

Access control helpers

The functions getListAccessControlForUser() and getFieldAccessControlForUser() are used by the internal Keystone resolvers to apply access control. They should not be called directly.

Internal state

These properties are used internally by Keystone and generally do not need to be directly accessed.

totalResults: The cumulative total number of results returned by the current request. See config.graphql.queryLimits.

maxTotalResults: The maximum number of results which can be returned before a query limit error is triggered. See config.graphql.queryLimits.

schemaName: The internal name used by Keystone to refer to the GraphQL schema.

Deprecated

The following properties are deprecated and should not be used. They will be removed in future releases.

gqlNames: A function which takes a listKey and returns an object containing the GraphQL query, mutation and type names related to that list.

executeGraphQL: This function is identical to context.graphql.raw, which is the preferred API to use.

keystone: An object representing the internal state of the system.