com.walmartlabs.lacinia.schema

Responsible for constructing and validating the GraphQL schema.

GraphQL schema starts in a format easy to read and maintain as an EDN file.

Compiling the schema performs a number of validations and reorganizations to make query execution faster and simpler, such as generating a flatter structure for the schema, and pre-computing many defaults.

*verbose-schema-printing*

dynamic

added in 0.25.0

If bound to true, then the compiled schema prints and pretty-prints like an ordinary map, which is sometimes useful during development. When false (the default) the schema output is just a placeholder.

as-conformer

deprecated in 0.31.0

(as-conformer f)

Creates a clojure.spec/conformer as a wrapper around the supplied function.

The function is only invoked if the value to be conformed is non-nil.

Any exception thrown by the function is silently caught and the returned conformer will return :clojure.spec/invalid or a coercion-failure.

This function has been deprecated, as Scalar parse and serialize callbacks are now simple functions, and not conformers.

can-reach-null-producer?

(can-reach-null-producer? schema element-def)

coercion-failure

added in 0.16.0

deprecated in 0.32.0

(coercion-failure message)(coercion-failure message data)

Returns a special record that indicates a failure coercing a scalar value. This may be returned from a scalar’s :parse or :serialize callback.

This is deprecated in version 0.32.0; just throw an exception instead.

A coercion failure includes a message key, and may also include additional data.

message
A message string presentable to a user.
data
An optional map of additional details about the failure.

compile

(compile schema)(compile schema options)

Compiles a schema, verifies its correctness, and prepares it for query execution. The compiled schema is in an entirely different format than the input schema.

The format of the compiled schema is subject to change without notice.

This function explicitly validates its arguments using clojure.spec.

Compile options:

:default-field-resolver
A function that accepts a field name (as a keyword) and converts it into the default field resolver; this defaults to default-field-resolver.
:promote-nils-to-empty-list?
Returns the prior, incorrect behavior, where a list field that resolved to nil would be “promoted” to an empty list. This may be necessary when existing clients rely on the incorrect behavior, which was fixed in 0.31.0.
:enable-introspection?
If true (the default), then Schema introspection is enabled. Some applications may disable introspection in production.
:disable-checks? (added in 1.1)
If true (defaults to false), certain runtime checks on data returned from field resolvers are omitted; this trades safety for speed, but may make sense when running in production.
:disable-java-objects? (added in 1.1)
Normally, Lacinia must check each returned field to see if it is a wrapper around a Java object (this happens when a Java objects is tagged via tag-with-type); in most applications, resolvers return only Clojure values, not Java objects, and the step that looks for tagged values iis only needed for fields whose type is an interface or union. Using this option improves performance slightly, but should be used consistently across environments (testing and production).
:apply-field-directives
An optional callback function; for fields that have any directives on the field definition, the callback is invoked; it is passed the FieldDef (from which directives may be extracted) and the base field resolver function (possibly, a default field resolver). The callback may return a new field resolver function, or return nil to use the base field resolver function.

A FieldResolver instance is converted to a function before being passed to the callback.

The callback should be aware that the base resolver function may return a raw value, or a ResolverResult. Generally, this option is used with the wrap-resolver-result function.

This processing occurs at the very end of schema compilation.

Produces a form ready for use in executing a query.

default-field-resolver

(default-field-resolver field-name)

The default for the :default-field-resolver option, this uses the field name as the key into the resolved value.

default-scalar-transformers

hyphenating-default-field-resolver

added in 0.17.0

(hyphenating-default-field-resolver field-name)

An alternative to default-field-resolver, this converts underscores in the field name into hyphens. At one time, this was the default behavior.

is-coercion-failure?

added in 0.16.0

(is-coercion-failure? v)

Is this a coercion error created by coercion-failure?

select-type

added in 0.39

(select-type compiled-schema type-name)

Given a compiled schema and a keyword type name, returns a TypeDef, or nil if not found.

tag-with-type

(tag-with-type x type-name)

Tags a value with a GraphQL type name, a keyword. The keyword should identify a specific concrete object (not an interface or union) in the relevent schema.

In most cases, this is accomplished by modifying the value’s metadata.

For the more rare case, where a particular Java object is used rather than a Clojure map, this function returns a new wrapper instance that combines the value and the type name.