com.walmartlabs.lacinia.resolve — com.walmartlabs/lacinia 1.1-alpha-2

Complex results for field resolver functions.

Resolver functions may return a value directly, or return a value in an immediate or asynchronous ResolverResult. The resolved value may be wrapped in a a modifier:

• with-error
• with-warning
• with-context
• with-extensions

The modifiers exist to resolve a value and to perform a side effect, such as adding an error to the execution result.

A value or wrapped value may be returned asynchronously using a ResolverResultPromise.

The FieldResolver protocol allows a Clojure record to act as a field resolver function.

*callback-executor* clj

If non-nil, then specifies a java.util.concurrent.Executor (typically, a thread pool of some form) used to invoke callbacks when ResolveResultPromises are delivered.

as-resolver-fn clj

(as-resolver-fn field-resolver)

Wraps a FieldResolver instance as a field resolver function.

If the field-resolver provided is a function or a Var, it is returned unchanged.

Anything other value will cause an exception to be thrown.

FieldResolver clj protocol

Allows a Clojure record to operate as a field resolver.

resolve-value clj

(resolve-value this context args value)

The analog of a field resolver function, this method is passed the instance, and the standard context, field arguments, and container value, and returns a resolved value.

is-resolver-result? clj

(is-resolver-result? value)

Is the provided value actually a ResolverResult?

resolve-as clj

(resolve-as resolved-value)

(resolve-as resolved-value resolver-errors)

Invoked by field resolvers to wrap a simple return value as a ResolverResult.

The two-arguments version is a convienience around using with-error.

This is an immediately realized ResolverResult.

Use resolve-promise and [[deliver!]] for an asynchronous result.

When [[on-deliver!]] is invoked, the provided callback is immediately invoked (in the same thread).

resolve-promise clj

(resolve-promise)

Returns a ResolverResultPromise.

At creation, the promise will capture per-thread bindings and ensure they are conveyed to the callback, should the callback be invoked asynchronously (when *callback-executor* is bound to an Executor).

A value must be resolved and ultimately provided via [[deliver!]].

ResolverResult clj protocol

A special type returned from a field resolver that can contain a resolved value, possibly wrapped with modifiers.

on-deliver! clj

(on-deliver! this callback)

Provides a callback that is invoked immediately after the ResolverResult is realized. The callback is passed the ResolverResult's value.

on-deliver! should only be invoked once. It returns this.

On a simple ResolverResult (not a ResolverResultPromise), the callback is invoked immediately.

For a ResolverResultPromise, the callback may be invoked on another thread.

The callback is invoked for side-effects; its result is ignored.

If per-thread bindings are relevant to the callback, it should make use of clojure.core/bound-fn.

ResolverResultImpl clj

ResolverResultPromise clj protocol

A specialization of ResolverResult that supports asynchronous delivery of the resolved value and errors.

deliver! clj

(deliver! this value)

(deliver! this value errors)

Invoked to realize the ResolverResult, triggering the callback to receive the value and errors.

The callback is invoked in the current thread, unless [[thread-pool]] is non-nil, in which case the callback is invoked in a pooled thread.

The two arguments version is simply a convienience around the with-error modifier.

Returns this.

ResolverResultPromiseImpl clj

with-context clj

(with-context value context-map)

Wraps a value so that when nested fields (at any depth) are executed, the provided values will be in the context.

The provided context-map is merged onto the application context.

with-error clj

(with-error value error)

Wraps a value, modifiying it to include an error map (or seq of error maps).

The provided error map will be enhanced with a :location key, identifying where field occurs within the query document, and a :path key, identifying the sequence of fields (or aliases) and list indexes within the :data key of the result map.

Any additional keys in the error map beyond :message (which must be present, and must be a string) will be added to an embedded :extensions map.

with-extensions clj

(with-extensions value f & args)

Wraps a value with an update to the extensions for the request.

The extensions are a map, and this applies a change to that map, as with clojure.core/update: the function is provided with the current value of the extensions map and the arguments, and returns the new value of the extensions map.

with-warning clj

(with-warning value warning)

As with with-error, but the error map will be added to the :warnings key of the root :extensions map (not to the root :errors map). Errors should only be used to indicate a substantial failure, whereas warnings are more advisory. It is up to the application to determine what situations call for an error and what call for a warning.

wrap-resolver-result clj

(wrap-resolver-result resolver wrapper-fn)

Wraps a resolver function or (FieldResolver instance), passing the result through a wrapper function.

The wrapper function is passed four values: the context, arguments, and value as passed to the resolver, then the resolved value from the resolver.

wrap-resolver-result understands resolver functions that return either a ResolverResult or a bare value, as well as values wrapped with a modifier (such as with-error).

The wrapper-fn is passed the underlying value and must return a new value. The new value will be re-wrapped with modifiers as necessary.

The new value returned by the wrapper-fn may itself be a ResolverResult, and the value (either plain, or inside a ResolverResult) may also be modified (via with-error, etc.).

Returns a standard field resolver function, with the standard three parameters (context, args, value).