Runtime GraphQL

Start here

Use GraphQLQuery at runtime walks through using these.

GraphQLQuery

class

class GraphQLQuery<T>

Encapsulates a GraphQL query using exactly one GraphQL query or mutation method.

GraphQLQuery.constructor

constructor(query: string);

GraphQLQuery.register

register(result: T): void;

Registers this query with the given result

Parameters

result	GraphQL result object to attach this query to

GraphQLQuery.access

static access<T>(o: T): GraphQLQuery<T> | null;

Returns the GraphQL query registered with the given object

Parameters

o	former GraphQL result with an attached query

Returns query attached to object or null

GraphQLQuery.execute

execute(params: GraphQLParams): Promise<T>;

Executes the query with the given parameters at runtime.

Make sure you really want to use this method. To get an update for an injected QueryDocument, call update() on that document snapshot instead.

See Use GraphQLQuery at runtime.

Parameters

params

useQueryDocument()

function

declare function useQueryDocument<T>(document: QueryDocument<T> | null): T;

Subscribes the current component to the given QueryDocument and returns the current snapshot.

Parameters

document

graphql()

function

declare function graphql<T>(query: GraphQLQuery<T> | string, params: GraphQLParams): Promise<T>;

Posts the given query to the server’s /graphql endpoint and resolves with its data, rejecting on a transport error or on any GraphQL error in the response: with a GraphQLTransportError where no GraphQL response came back, with a GraphQLResponseError carrying the errors where one did.

This is the raw call: values go out and come back in their wire format, and the result is the whole data object, keyed by result key. GraphQLQuery.execute() runs the same request through the query’s conversion map and unwraps the single selection, and is what an application normally wants – reach for this one when the query has several top-level selections, or when the wire format is what you are after.

Running on a fixture (see initFixture()), there is no server to post to, and this rejects without trying.

Parameters

query	query to run, as a GraphQLQuery or its source
params	variables for the query, in wire format

Returns the “data” member of the GraphQL response

GraphQLParams

type

type GraphQLParams = {
  [name: string]: any;
};

Parameters for a GraphQL query. This is just the most generic description. Queries will complain loudly and in great length if you don’t give them their inputs.

GraphQLResponseError

class

class GraphQLResponseError extends Error

The rejection of a request the server answered with GraphQL errors. It carries them parsed, so a caller can tell an ended session from a missing role or a broken query without reading the message.

catch (e)
{
    if (e instanceof GraphQLResponseError && e.hasClassification("UNAUTHENTICATED")) ...
}

A request that got no GraphQL response at all – the network, a server that isn’t up – rejects with whatever went wrong instead.

GraphQLResponseError.errors

readonly errors: readonly GraphQLError[];

The errors of the response, as the server sent them

GraphQLResponseError.constructor

constructor(errors: readonly GraphQLError[]);

Parameters

errors	the errors of the response, at least one

GraphQLResponseError.hasClassification

hasClassification(classification: string): boolean;

Returns true if one of the errors has the given classification.

Parameters

classification	classification from the errors’ extensions, e.g. “UNAUTHENTICATED”

GraphQLTransportError

class

class GraphQLTransportError extends Error

The rejection of a request that got no GraphQL response: the server couldn’t be reached, or answered with something other than a GraphQL response – an error page, or a 503 while it is starting up.

Where the server did answer GraphQL, errors and all, the rejection is a GraphQLResponseError instead.

GraphQLTransportError.status

readonly status: number | null;

HTTP status of the answer, null where there was none

GraphQLTransportError.constructor

constructor(message: string, status: number | null, cause?: unknown);

Parameters

message	what went wrong
status	HTTP status of the answer, null where there was none
cause	the error underneath, e.g. fetch()’s or the JSON parser’s

GraphQLError

type

type GraphQLError = {
  /**
   * Error message
   */
  message: string;
  /**
   * Query string location
   */
  locations?: GraphQLErrorLocation[];
  /**
   * Result key path of the field that failed, for an error while executing
   */
  path?: (string | number)[];
  /**
   * Whatever else the server says about the error. The QLive server puts its kind in `classification`:
   * "UNAUTHENTICATED" for a missing or expired login, "FORBIDDEN" for a missing role or CSRF token, and
   * graphql-java's own classifications, such as "ValidationError", for the rest.
   */
  extensions?: {
    classification?: string;
    [name: string]: unknown;
  };
};

One entry of the “errors” of a GraphQL response.

GraphQLErrorLocation

type

type GraphQLErrorLocation = {
  line: number;
  column: number;
};

Where in the query string an error is.

firstValue()

function

declare function firstValue(result: any): any;

Returns the value of the first key of a GraphQL result.

The wire format of a result is keyed by result key, while GraphQLQuery promises T for one execution of the query – the value of its single selection. This is where the two meet, which only works out because a query we inject or execute for its value has exactly one top-level selection.