Docs Developer Site
Developer Docs Guillotine - Headless GraphQL API next Extending resolvers

resolvers

Contents

Set or override data fetcher for a field.

Usage

Add functions to the resolvers property returned by your extension function. The outer key names a GraphQL type, and each inner key names a field on that type. Each resolver receives a DataFetchingEnvironment and returns the field’s value.

DataFetchingEnvironment

A DataFetchingEnvironment instance (env) is passed to a DataFetcher as an execution context, and it’s the place where you can find information to help you resolve a data value given a GraphQL field input.

Guillotine provides the following properties in the DataFetchingEnvironment:

  • source - value of the parent field. For the root query it is equal to null.

  • args - the arguments provided to the field in the GraphQL query.

  • localContext - a context object that parent fields may have returned. This object is unmodifiable.

The localContext object supports value types such as string, double, integer, boolean, and null. Keys with null values will be removed. If you need to provide a complex object as a value, you can use the JSON.stringify function to convert it to a string.

The localContext object is unmodifiable, so you can’t change it. If you need to pass some data to the lower levels, then you can use createDataFetcherResult function. Also, the localContext object provides the following properties:

  • project - project name, selected by the guillotine field’s argument or supplied by the request context.

  • branch - branch name, selected by the guillotine field’s argument or supplied by the request context.

  • siteKey - the selected site key, when present. Treat this property as optional; see Site context.

Keys starting with __ are internal to Guillotine and are not part of the extension contract.

Resolvers beneath guillotine run in the selected project’s repository and branch. Calls to XP libraries such as /lib/xp/content use that context automatically. See Lifecycle and execution for fields added directly to Query.

Below you can find an example of how to use these properties:

import type {DataFetchingEnvironment, Extensions} from '@enonic-types/guillotine';

interface Source {
    _id: string;
}

export const extensions = (): Extensions => ({
    resolvers: {
        MyCustomType: {
            myCustomField: (env: DataFetchingEnvironment<Record<string, never>, Source>): string => {
                const {project, branch, siteKey} = env.localContext;
                return `${project}/${branch}: ${env.source._id} (site: ${siteKey ?? 'not selected'})`;
            },
        },
    },
});

This example assumes MyCustomType has a string field named myCustomField, and that its parent resolver supplies an object with an _id property. The generic parameters describe the field arguments and source value respectively.

Application context

A resolver runs as a script of the app containing the extension: app.name, app.config, require and localization through /lib/xp/i18n refer to that app.

The portal request keeps its own application context. When calling a portal URL helper that accepts an application parameter, pass application: app.name to reference your extension app’s resources explicitly.

createDataFetcherResult

Guillotine provides createDataFetcherResult function via graphQL object. This function will be useful when your DataFetcher retrieves data from multiple sources, or you want to pass extra context to lower levels.

The createDataFetcherResult function accepts an object with the following properties:

  • data - data to return, must not be null. Object must be wrapped by __.toScriptValue function.

  • localContext - a key-value object that will be passed to the lower levels. This object is unmodifiable at the lowest level.

  • parentLocalContext - a context object that parent fields may have returned.

If parentLocalContext is not provided, then localContext will override parentLocalContext. Otherwise, localContext will be merged with parentLocalContext and localContext will override parentLocalContext if they have the same keys.

If localContext is not provided, then parentLocalContext will be used as localContext.

Below you can find an example of how to use createDataFetcherResult function:

import type {Extensions, GraphQL} from '@enonic-types/guillotine';

export const extensions = (graphQL: GraphQL): Extensions => ({
    resolvers: {
        MyCustomType: {
            myCustomField: (env) => {
                return graphQL.createDataFetcherResult({
                    data: __.toScriptValue({id: '100'}),
                    localContext: {
                        parentId: '101',
                    },
                    parentLocalContext: env.localContext,
                });
            },
        },
    },
});

Here, myCustomField must return an object type with an id field. Its child resolvers receive parentId through env.localContext. This is an alternative to the string-valued resolver above.

Contents

Contents