Context API

The KeystoneContext object is the primary API entry point for all of the run-time functionality 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,

  // Internal DB object API
  db: {
    lists,
  }

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

  // Session API
  session,
  startSession,
  endSession,

  // New context creators
  sudo,
  exitSudo,
  withSession,

  // Database access
  prisma,

  // Images API
  images: {
    getSrc,
    getDataFromRef,
    getDataFromStream,
  },

  // Internal state
  totalResults,
  maxTotalResults,
  schemaName,

  // Deprecated
  gqlNames,
};

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.

Database item API

db.lists: The database items API, which can be used to retrieve objects suitable for return from mutations in schema extensions.

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 via context.prisma, which is a Prisma Client object.

Images API

If support for image fields is enabled in the system, then an images API will be made available on the context object. This API takes advantage of the following types:

type ImageMode = 'local';

type ImageExtension = 'jpg' | 'png' | 'webp' | 'gif';

type ImageData = {
  mode: ImageMode;
  id: string;
  extension: ImageExtension;
  filesize: number;
  width: number;
  height: number;
};

images.getSrc(mode, id, extension): Given a mode, id, and extension from an ImageData object, returns the src value representing the location from which the image can be accessed over HTTP.

async images.getDataFromRef(ref): Given a ref string, taken from the id field of an existing image, returns an ImageData object.

async images.getDataFromStream(stream): Given a readable data stream, returns an ImageData object. The mode will be taken from config.images.mode, and id will be a uuid value. The other values will be inferred from the data stream itself. The contents of the stream will be written to the filesystem at config.images.local.storagePath.

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.