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

TypeScript

Contents

Type definitions for Guillotine extensions

Introduction

The @enonic-types/guillotine package provides the TypeScript types for writing an extension. It contains no runtime code; it describes the extensions function contract, the graphQL utility object passed to it, the environment a resolver receives, and constants naming the built-in schema types.

Install it as a development dependency in your app:

npm install --save-dev @enonic-types/guillotine

The package depends on @enonic-types/core, @enonic-types/global and @enonic-types/lib-content, which are installed with it. Types shared with the XP libraries, such as Content and ScriptValue, are defined in @enonic-types/core and documented in the library type reference.

The pages in this chapter name these types in their examples. This page is the canonical reference for the exported types themselves.

Each exported type is a TypeScript shape only. The behaviour behind it, such as how localContext is merged or when a creation callback runs, is documented on the page for the corresponding extension property.

Extension contract

Extensions

The object returned by the extensions function. Every property is optional, but the function must return an object.

Name Type Description

enums

Record<string, Enum>

Optional. Custom enums, keyed by enum name. See Enums.

inputTypes

Record<string, InputType>

Optional. Custom input types, keyed by type name. See Input types.

interfaces

Record<string, Interface>

Optional. Custom interfaces, keyed by interface name. See Interfaces.

unions

Record<string, Union>

Optional. Custom unions, keyed by union name. See Unions.

types

Record<string, Type>

Optional. Custom object types, keyed by type name. See Types.

creationCallbacks

Record<string, CreationCallback>

Optional. Callbacks modifying existing types and interfaces, keyed by the name of the type to modify. See Creation callbacks.

resolvers

Record<string, Record<string, Resolver>>

Optional. Field resolvers, keyed by type name and then by field name. See Resolvers.

typeResolvers

Record<string, TypeResolver>

Optional. Type resolvers for interfaces and unions, keyed by interface or union name. See Type resolvers.

The sub-object types below are not exported by name. Derive them from Extensions when you split definitions across files:

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

type Types = NonNullable<Extensions['types']>;
type Resolvers = NonNullable<Extensions['resolvers']>;

Enum

Name Type Description

description

string

Description shown in the schema.

values

Record<string, string>

Enum values, keyed by the name exposed in the schema.

InputType

Name Type Description

description

string

Optional. Description shown in the schema.

fields

Record<string, GraphQLType>

Input fields, keyed by field name. Each value is a scalar, an enum or input type reference, or a list of one of these.

Interface

Name Type Description

description

string

Description shown in the schema.

fields

Record<string, Field>

Fields every implementing type must provide, keyed by field name.

Union

Name Type Description

description

string

Description shown in the schema.

types

GraphQLType[]

The object types that are members of the union, typically created with graphQL.reference().

Type

Name Type Description

description

string

Description shown in the schema.

fields

Record<string, Field>

Fields of the object type, keyed by field name.

interfaces

GraphQLType[]

Optional. Interfaces the type implements, created with graphQL.reference(). The type must declare every field of each interface.

Field

A field on an object type or interface. Used in Type, Interface, and the addFields and modifyFields methods of a CreationCallback.

Name Type Description

type

GraphQLType

The field’s output type.

args

GraphQLArgs

Optional. Arguments the field accepts, keyed by argument name.

CreationCallback

A function invoked while Guillotine builds the schema. It receives a single params object with these methods:

Name Type Description

addFields

(fields: Record<string, Field>) ⇒ void

Adds fields to the type.

modifyFields

(fields: Record<string, Field>) ⇒ void

Changes the type or arguments of existing fields. Supplying args replaces all existing arguments.

removeFields

(names: string[]) ⇒ void

Removes the named fields.

setDescription

(description: string) ⇒ void

Replaces the type’s description.

setInterfaces

(interfaces: GraphQLType[]) ⇒ void

Replaces the interfaces implemented by an object type.

The callback returns nothing.

TypeResolver

(value: any) ⇒ string

A function receiving the value resolved for an interface or union field and returning the name of the concrete object type. See Type resolvers.

Resolvers

Resolver

Resolver<Args, Source, Return>

A function receiving a DataFetchingEnvironment and returning the field’s value. All three generic parameters default to permissive types, so an untyped resolver is accepted. Narrow Args and Source to the shapes your field expects:

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

interface Book {
    title: string;
}

const findBooks = (env: DataFetchingEnvironment<{queryString: string}, null>): Book[] => {
    return [{title: env.args.queryString}];
};

A resolver may return a plain value, an object used as the source for child fields, or the result of createDataFetcherResult.

DataFetchingEnvironment

DataFetchingEnvironment<Args, Source>

The single argument passed to a Resolver.

Name Type Description

args

Args

Arguments supplied to the field in the query. Defaults to Record<string, any>.

source

Source

Value returned by the parent field’s resolver. null for fields directly on Query. Defaults to unknown.

localContext

LocalContext

Read-only context inherited from ancestor resolvers.

LocalContext

LocalContext<T extends LocalContextRecord>

The context object available as env.localContext. Guillotine always supplies the first three properties. Additional properties come from ancestor resolvers via createDataFetcherResult; describe them with the generic parameter T when you read them.

Name Type Description

project

string

Project selected for the query.

branch

string

Branch selected for the query.

siteKey

string

Optional. Selected site key, when present. See Site context.

LocalContextRecord

Record<string, string | number | boolean | null>

The value types a local context may hold. Objects and arrays are not allowed; serialize them with JSON.stringify if needed. Keys with null values are removed.

DataFetcherResult

An opaque value returned by createDataFetcherResult. Return it from a resolver unchanged. Guillotine unwraps its data as the field value and merges its localContext into the context of child resolvers.

The graphQL argument

GraphQL

The utility object passed as the argument to the extensions function.

Name Type Description

GraphQLString

scalar

The String scalar.

GraphQLInt

scalar

The Int scalar.

GraphQLFloat

scalar

The Float scalar.

GraphQLBoolean

scalar

The Boolean scalar.

GraphQLID

scalar

The ID scalar.

Json

scalar

The Json scalar.

Date

scalar

The Date scalar, an ISO date string.

DateTime

scalar

The DateTime scalar, an ISO instant string.

LocalDateTime

scalar

The LocalDateTime scalar, an ISO date-time string without zone.

LocalTime

scalar

The LocalTime scalar, an ISO time string.

nonNull

(type: GraphQLType) ⇒ GraphQLType

Marks a type as non-nullable.

list

(type: GraphQLType) ⇒ GraphQLType[]

Wraps a type in a list.

reference

(typeName: string) ⇒ GraphQLType

References a named type in the schema, built in or custom. Use it for object types, interfaces, unions, enums and input types.

createDataFetcherResult

CreateDataFetcherResult

Wraps a resolver’s return value together with context for child resolvers.

Scalars

GraphQLString, GraphQLInt, GraphQLFloat, GraphQLBoolean, GraphQLID, GraphQLJson, GraphQLDate, GraphQLDateTime, GraphQLLocalDateTime and GraphQLLocalTime are exported as named types. Each is a branded primitive, so a GraphQLString is a string carrying the scalar’s schema name at the type level. Use them to annotate the fields of an object a resolver returns:

import type {GraphQLDateTime, GraphQLString} from '@enonic-types/guillotine';

interface Book {
    title: GraphQLString;
    published: GraphQLDateTime;
}

In schema definitions, use the properties of the GraphQL object rather than the named types.

GraphQLType

The type of any schema type reference: a scalar from the GraphQL object, or the result of reference(), nonNull() or list(). It is declared as any, so TypeScript does not validate that a reference names an existing type. Schema generation reports unknown names at runtime.

GraphQLArgs

Record<string, GraphQLType | GraphQLType[]>

Field arguments, keyed by argument name. Values are scalars, enum or input type references, or lists of these.

CreateDataFetcherResult

graphQL.createDataFetcherResult() takes a single params object with these properties:

Name Type Description

data

ScriptValue | string | number | boolean

The field value. Objects and arrays must be wrapped with __.toScriptValue(); primitives may be passed as is. Must not be null.

localContext

LocalContextRecord

Optional. Values made available to child resolvers through env.localContext. Overrides matching keys in parentLocalContext.

parentLocalContext

LocalContext

Optional. The current env.localContext. Pass it to keep inherited values; omit it to replace the context with localContext only.

Returns a DataFetcherResult. See Resolvers for the merge rules and an example.

Schema name constants

These are runtime enums, imported without import type. Each member’s value is the type name as it appears in the schema. Use them as keys in creationCallbacks, resolvers and typeResolvers, and as arguments to graphQL.reference(), instead of string literals.

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

export const extensions = (graphQL: GraphQL): Extensions => ({
    creationCallbacks: {
        [ObjectTypeName.Content]: (params) => {
            params.addFields({
                wordCount: {type: graphQL.GraphQLInt},
            });
        },
    },
});
Name Description

ObjectTypeName

Built-in object types, such as Content, HeadlessCms, Query, RichText, Image, Link, PublishInfo and the generated types for built-in content types like portal_Site and media_Image.

InputTypeName

Built-in input types, such as QueryDSLInput, SortDslInput, AggregationInput and ProcessHtmlInput.

EnumTypeName

Built-in enums, such as ComponentType, FormItemType, Permission and PrincipalType.

ScalarTypeName

The scalar names String, Int, Float, Boolean, ID, Json, Date, DateTime, LocalDateTime and LocalTime.

The companion types ObjectTypeNames, InputTypeNames, EnumTypeNames and ScalarTypeNames are string unions of the corresponding member names.

Enum values

The values of these built-in schema enums are exported as runtime enums, for comparing against data in a resolver or returning a valid enum value:

Name Values

ComponentType

page, layout, image, part, text, fragment

FormItemType

Input, ItemSet, Layout, OptionSet

MediaIntentType

download, inline

Permission

READ, CREATE, MODIFY, DELETE, PUBLISH, READ_PERMISSIONS, WRITE_PERMISSIONS

PrincipalType

user, group, role

Content types

Three content shapes are exported for typing env.source in resolvers on built-in content types. They are built on Content from @enonic-types/core and Site from @enonic-types/lib-content.

Name Description

BaseFolderContent

Content<{}, 'base:folder'>. A folder with no data of its own.

MediaImageContent

Content<..., 'media:image'>. An image, with media.attachment, media.focalPoint, and optional altText, artist, caption, copyright and tags.

PortalSiteContent<Config>

Site<Config>. A site, with Config describing the merged site configuration.

For the full Content shape, see the library type reference.

Advanced entry point

@enonic-types/guillotine/advanced exports a larger, experimental set of types. It includes TypeScript declarations mirroring the built-in schema object types, such as Content, HeadlessCms, Query, RichText, Image, Link, PublishInfo and the Mixin_* configuration types, plus branded scalar and reference helpers.

These declarations describe the GraphQL schema, not the values a resolver receives as env.source, which follow the XP content model instead. Use them to type the objects your resolvers return for built-in types. Their names and shapes may change between minor releases.

Contents

Contents