oksa.alpha.api — fi.metosin/oksa 1.0.0

-directive-name? clj/s

(-directive-name? x)

-directive? clj/s

(-directive? x)

-directives? clj/s

(-directives? x)

-field? clj/s

(-field? x)

-fragment-spread? clj/s

(-fragment-spread? x)

-fragment? clj/s

(-fragment? x)

-inline-fragment? clj/s

(-inline-fragment? x)

-list? clj/s

(-list? x)

-mutation? clj/s

(-mutation? x)

-naked-field? clj/s

(-naked-field? x)

-query? clj/s

(-query? x)

-selection-set? clj/s

(-selection-set? x)

-subscription? clj/s

(-subscription? x)

-type? clj/s

(-type? x)

-validate clj/s

(-validate x msg)

(-validate x msg data)

alias clj/s

(alias name)

Returns an alias under key :alias using name which should conform to Name. Used directly within oksa.alpha.api/opts.

Example:

(opts
 (alias :foo))
; => {:alias :foo}

See also Alias.

argument clj/s

(argument name value)

Returns an argument under key :arguments. Used directly within oksa.alpha.api/opts.

Expects that name is a string or a keyword (that conforms to Name) and that value conforms to Value.

Can also be used directly within oksa.alpha.api/directive.

Examples:

(opts (argument :foo 1))
; => {:arguments {:foo 1}}

(api/opts (api/directive :foo (api/argument :bar 123)))
; => {:directives [[:foo {:arguments {:bar 123}}]]}

See also Argument.

arguments clj/s

(arguments & arguments)

Returns arguments under key :arguments. Used directly within oksa.alpha.api/opts.

Expects arguments to be pair(s) of names and values where name is a string or a keyword (that conforms to Name) and where value conforms to Value.

Can also be used directly within oksa.alpha.api/directive.

Example:

(opts (arguments :foo 1 :bar "foobar"))
; => {:arguments {:foo 1, :bar "foobar"}}

(opts (directive :foo (arguments :qux 123 :baz "frob")))
; => {:directives [[:foo {:arguments {:qux 123, :baz "frob"}}]]}

See also Arguments.

default clj/s

(default value)

Returns default value under :default key. Used directly within oksa.alpha.api/opts.

Example:

(opts (variable :fooVar (opts (default 123)) :Foo))
; => {:variables [:fooVar {:default 123} :Foo]}

See also DefaultValue.

directive clj/s

(directive name)

(directive name arguments)

Returns a directive under key :directives using name which should conform to Name. Used directly within oksa.alpha.api/opts.

Optionally accepts arguments, which is an instance of oksa.alpha.api/Argumented (ie. oksa.alpha.api/argument or oksa.alpha.api/arguments).

Examples:

(opts
 (directive :foo))
; => {:directives [[:foo {}]]}

(opts
 (directive :foo (arguments :bar 123)))
; => {:directives [[:foo {:arguments {:bar 123}}]]}

See also Directive.

directive-fn clj/s

(directive-fn f)

Sets field transformer function f to :oksa/directive-fn. Function f is invoked against all representations of :oksa.parse/DirectiveName.

directives clj/s

(directives & directives)

Returns directives under key :directives. Used directly within oksa.alpha.api/opts.

Expects directives is a varargs consisting of keywords (naked directives) or instances of oksa.alpha.api/directive.

Tolerates nil entries.

Examples:

(opts
 (directives :foo :bar))
; => {:directives [:foo :bar]}

(opts
 (directive :foo)
 (directive :bar)
 (directives :frob :nitz))
; => {:directives [[:foo {}] [:bar {}] :frob :nitz]}

;; mixed use example
(opts
 (directives
  :foo
  (directive :bar)
  :foobar))
; => {:directives [:foo [:bar {}] :foobar]}

See also Directives.

document clj/s

(document & definitions)

Composes many executable definitions together to produce a single document.

definitions can be many of:

• oksa.alpha.api/query
• oksa.alpha.api/mutation
• oksa.alpha.api/subscription
• oksa.alpha.api/fragment
• oksa.alpha.api/select

Tolerates nil entries.

Example:

(document
  (select :foo)
  (query (select :bar))
  (mutation (select :qux))
  (subscription (select :baz))
  (fragment (opts
              (name :foo)
              (on :Foo))
    (select :bar)))

See also Document.

enum-fn clj/s

(enum-fn f)

Sets field transformer function f to :oksa/enum-fn. Function f is invoked against all representations of enums under :oksa.parse/Value.

field clj/s

(field name)

(field name selection-set-or-opts)

(field name opts selection-set)

Produces a field using name. Can be used directly within oksa.alpha.api/select when you need to provide options (eg. arguments, directives) for a particular field.

Multiple arities are supported:

• (field name)
• (field name opts)
• (field name selection-set)
• (field name opts selection-set)

Expects name to conform to Name, and expects selection-set to be an instance of oksa.alpha.api/select.

opts is an (optional) map and uses the following fields here:

field	description	API reference
:alias	A field alias conforming to Alias	oksa.alpha.api/alias
:arguments	Field arguments, see also Arguments	oksa.alpha.api/arguments or oksa.alpha.api/argument
:directives	Field directives, see also Directives	oksa.alpha.api/directives or oksa.alpha.api/directive

Examples:

(gql
 (select
   (field :foo)
   (field :bar)))
; => {foo bar}

(gql
 (select
   (field :foo (opts (alias :FOO)))))
; => {FOO:foo}

(gql
 (select
   (field :foo (select :bar))))
; => {foo{bar}}

(gql
 (select
   (field :foo (opts (alias :FOO)
                     (directives :fooDirective :barDirective)
                     (arguments :fooArg "fooValue"
                                :barArg 123))
     (select :bar))))
; => {FOO:foo(fooArg:"fooValue", barArg:123)@fooDirective @barDirective{bar}}

See tests for more examples.

See also Field.

field-fn clj/s

(field-fn f)

Sets field transformer function f to :oksa/field-fn. Function f is invoked against all representations of :oksa.parse/Name under :oksa.parse/Selection.

fragment clj/s

(fragment opts selection-set)

Produces a fragment definition using the fields defined in selection-set.

Expects :name and :on fields under opts arg, and expects selection-set to be an instance of oksa.alpha.api/select.

opts is a map and uses the following fields here:

field	required	description	API reference
:name	true	A fragment name conforming to Name	oksa.alpha.api/name
:on	true	Type condition, see also TypeCondition	oksa.alpha.api/on
:directives	false	Fragment directives, see also Directives	oksa.alpha.api/directives or oksa.alpha.api/directive

Examples:

(gql
 (fragment (opts (name :FooFragment)
                 (on :FooType))
   (select :foo :bar)))
; => fragment FooFragment on FooType{foo bar}

(gql
 (fragment (opts (name :FooFragment)
                 (on :FooType)
                 (directives :fooDirective :barDirective))
   (select :foo :bar)))
; => fragment FooFragment on FooType@fooDirective @barDirective{foo bar}

See also FragmentDefinition.

fragment-spread clj/s

(fragment-spread opts)

Produces a fragment spread using :name under opts. Can be used directly within oksa.alpha.api/select.

Expects :name under opts arg.

opts is a map and uses the following fields here:

field	required	description	API reference
:name	true	A fragment name conforming to Name	oksa.alpha.api/name
:directives	false	Fragment directives, see also Directives	oksa.alpha.api/directives or oksa.alpha.api/directive

Examples:

(gql
 (select (fragment-spread (opts (name :Foo)))))
; => {...Foo}

(gql
  (select
    (fragment-spread (opts
                       (name :Foo)
                       (directives :fooDirective :barDirective)))))
; => {...Foo@fooDirective @barDirective}

See also FragmentSpread.

gql clj/s

(gql obj)

(gql opts obj)

Returns a GraphQL request string for a given obj.

Expects obj to implement oksa.alpha.protocol/Representable or will throw.

The following functions implement oksa.alpha.protocol/Representable:

• oksa.alpha.api/document
• oksa.alpha.api/select
• oksa.alpha.api/query
• oksa.alpha.api/mutation
• oksa.alpha.api/subscription
• oksa.alpha.api/fragment

opts is an (optional) map and uses the following fields here:

field	description
:oksa/name-fn	Single-arg fn that applies fn to all names.
-----------------------	----------------------------------------------------------------------------------
:oksa/field-fn	Single-arg fn that applies fn to all fields.
	Overrides :oksa/name-fn.
-----------------------	----------------------------------------------------------------------------------
:oksa/enum-fn	Single-arg fn that applies fn to all enums.
	Overrides :oksa/name-fn.
-----------------------	----------------------------------------------------------------------------------
:oksa/directive-fn	Single-arg fn that applies fn to all directives.
	Overrides :oksa/name-fn.
-----------------------	----------------------------------------------------------------------------------
:oksa/type-fn	Single-arg fn that applies fn to all types.
	Overrides :oksa/name-fn.

inline-fragment clj/s

(inline-fragment selection-set)

(inline-fragment opts selection-set)

Produces an inline fragment using the fields defined in selection-set. Can be used directly within oksa.alpha.api/select.

Expects selection-set to be an instance of oksa.alpha.api/select.

opts is an (optional) map and uses the following fields here:

field	description	API reference
:on	Type condition, see also TypeCondition	oksa.alpha.api/on
:directives	Fragment directives, see also Directives	oksa.alpha.api/directives or oksa.alpha.api/directive

Examples:

(gql
 (select
   (inline-fragment (select :foo :bar))))
; => {...{foo}}

(gql
 (select
   (inline-fragment (opts (on :FooType)
                          (directives :fooDirective :barDirectives))
     (select :foo :bar))))
; => {...on FooType@fooDirective @barDirectives{foo bar}}

See also InlineFragment.

list clj/s

(list type-or-list)

Returns a list type using type-or-list.

Expects type-or-list to be an instance of oksa.alpha.api/type, oksa.alpha.api/type!, oksa.alpha.api/list, or oksa.alpha.api/type!.

Examples:

(opts (variable :foo (list :FooType)))
; => {:variables [:foo [:oksa/list {:non-null false} :FooType]]}

(opts (variable :foo (list (list :BarType))))
; => {:variables [:foo
;                 [:oksa/list
;                  {:non-null false}
;                  [:oksa/list {:non-null false} :BarType]]]}

See also ListType.

list! clj/s

(list! type-or-list)

Returns a non-nil list type using type-or-list.

Expects type-or-list to be an instance of oksa.alpha.api/type, oksa.alpha.api/type!, oksa.alpha.api/list, or oksa.alpha.api/type!.

Examples:

(opts (variable :foo (list! :FooType)))
; => {:variables [:foo [:oksa/list {:non-null true} :FooType]]}

(opts (variable :foo (list (list! :BarType))))
; => {:variables [:foo
                  [:oksa/list
                   {:non-null false}
                   [:oksa/list {:non-null true} :BarType]]]}

(opts (variable :foo (list! (list! :BarType))))
; => {:variables [:foo
                  [:oksa/list
                   {:non-null true}
                   [:oksa/list {:non-null true} :BarType]]]}

See also NonNullType.

mutation clj/s

(mutation selection-set)

(mutation opts selection-set)

Produces an operation definition of mutation operation type using the fields defined in selection-set.

Supports query naming, variable definitions, and directives through opts, and expects selection-set to be an instance of oksa.alpha.api/select.

opts is an (optional) map and uses the following fields here:

field	description	API reference
:name	Mutation name conforming to Name	oksa.alpha.api/name
:variables	Mutation variable definitions, see also VariableDefinitions	oksa.alpha.api/variables or oksa.alpha.api/variable
:directives	Mutation directives, see also Directives	oksa.alpha.api/directives or oksa.alpha.api/directive

Examples:

(gql
 (mutation (select :foo :bar)))
; => mutation {foo bar}

(gql
 (mutation (opts (name :Foobar)
                 (variables :foo :FooType
                            :bar :BarType)
                 (directives :fooDirective :barDirective))
           (select :foo :bar)))
; => mutation Foobar ($foo:FooType,$bar:BarType)@fooDirective @barDirective{foo bar}

See also OperationDefinition.

name clj/s

(name name)

Returns name under key :name. Name should conform to Name. Used directly within oksa.alpha.api/opts.

Example:

(opts
 (name :foo)
 (on :Foo))
; => {:name :foo, :on :Foo}

See Name.

name-fn clj/s

(name-fn f)

Sets name transformer function f to :oksa/name-fn. Function f is invoked against all representations of :oksa.parse/Name.

on clj/s

(on name)

Returns a type condition under key :on using name which should conform to NamedType. Used directly within oksa.alpha.api/opts.

Example:

(opts
 (name :foo)
 (on :Foo))
; => {:name :foo, :on :Foo}

See also TypeCondition.

opts clj/s

(opts & options)

Produces a map of options, a collection of oksa.alpha.protocol/UpdateableOptions. Output is a clojure.lang.IPersistentMap.

Tolerates nil entries.

Each instance of oksa.alpha.protocol/UpdateableOption implements their own behavior on where & how to update opts with the instance's own value:

API reference	Key	Expected update behavior
oksa.alpha.api/alias	:alias	Replaces value
oksa.alpha.api/argument	:arguments	Associates value
oksa.alpha.api/arguments	:arguments	Associates value(s)
oksa.alpha.api/default	:default	Replaces value
oksa.alpha.api/directive	:directive	Appends value
oksa.alpha.api/directives	:directives	Appends value(s)
oksa.alpha.api/name	:name	Replaces value
oksa.alpha.api/on	:on	Replaces value
oksa.alpha.api/variable	:variables	Appends value
oksa.alpha.api/variables	:variables	Appends value(s)

Examples:

(opts (alias :bar))
; => {:alias :bar}

(opts
 (name :foo)
 (on :Foo)
 (directives :fooDirective :barDirective))
; => {:name :foo, :on :Foo, :directives [:fooDirective :barDirective]}

See tests for more examples.

query clj/s

(query selection-set)

(query opts selection-set)

Produces an operation definition of query operation type using the fields defined in selection-set. Supports query naming, variable definitions, and directives through opts.

Expects selection-set to be an instance of oksa.alpha.api/select.

opts is an (optional) map and uses the following fields here:

field	description	API reference
:name	A query name conforming to Name	oksa.alpha.api/name
:variables	Query variable definitions, see also VariableDefinitions	oksa.alpha.api/variables or oksa.alpha.api/variable
:directives	Query directives, see also Directives	oksa.alpha.api/directives or oksa.alpha.api/directive

Examples:

(gql
 (query (select :foo :bar)))
; => query {foo bar}

(gql
 (query (opts (name :Foobar)
              (variables :foo :FooType
                         :bar :BarType)
              (directives :fooDirective :barDirective))
   (select :foo :bar)))
; => query Foobar ($foo:FooType,$bar:BarType)@fooDirective @barDirective{foo bar}

See also OperationDefinition.

select clj/s

(select & selections)

Produces a selection set using selections.

Expects an entry in selections to be an instance of:

• oksa.alpha.api/field
• keyword (representing a naked field)
• oksa.alpha.api/fragment-spread
• oksa.alpha.api/inline-fragment
• oksa.alpha.api/select (but only directly after a field)

Tolerates nil entries.

Examples:

(gql
 (select :foo :bar))
; => {foo bar}

(gql
 (select :foo :bar
   (select :qux :baz)
   (field :foobar (opts (alias :BAR)))
   (when false (field :conditionalFoo))
   (fragment-spread (opts (name :FooFragment)))
   (inline-fragment (opts (on :KikkaType))
     (select :kikka :kukka))))
; => {foo bar{qux baz} BAR:foobar ...FooFragment ...on KikkaType{kikka kukka}}

See also SelectionSet.

subscription clj/s

(subscription selection-set)

(subscription opts selection-set)

Produces an operation definition of subscription operation type using the fields defined in selection-set.

Supports query naming, variable definitions, and directives through opts, and expects selection-set to be an instance of oksa.alpha.api/select.

opts is an (optional) map and uses the following fields here:

field	description	API reference
:name	A subscription name conforming to Name	oksa.alpha.api/name
:variables	Subscription variable definitions, see also VariableDefinitions	oksa.alpha.api/variables or oksa.alpha.api/variable
:directives	Subscription directives, see also Directives	oksa.alpha.api/directives or oksa.alpha.api/directive

Examples:

(gql
 (subscription (select :foo :bar)))
; => subscription {foo bar}

(gql
 (subscription (opts (name :Foobar)
                     (variables :foo :FooType
                                :bar :BarType)
                     (directives :fooDirective :barDirective))
               (select :foo :bar)))
; => subscription Foobar ($foo:FooType,$bar:BarType)@fooDirective @barDirective{foo bar}

See also OperationDefinition.

type clj/s

(type type-name)

Returns a named type using type-name.

See also NamedType.

type! clj/s

(type! type-name)

Returns a non-nil named type using type-name.

See also NonNullType.

type-fn clj/s

(type-fn f)

Sets field transformer function f to :oksa/type-fn. Function f is invoked against all representations of :oksa.parse/TypeName.

variable clj/s

(variable variable-name variable-type)

(variable variable-name opts variable-type)

Returns a variable definition under :variables key using variable-name (which can be a string or a keyword) and variable-type. Used directly within oksa.alpha.api/opts.

opts is an (optional) map and uses the following field(s) here:

field	description	API reference
:default	Default value for variable, see also DefaultValue	oksa.alpha.api/default
:directives	Variable directives, see also Directives	oksa.alpha.api/directives or oksa.alpha.api/directive

Examples:

(opts (variable :fooVar :FooType))
; => {:variables [:fooVar :FooType]}

(opts (variable :foo (opts (directives :fooDirective :barDirective)
                           (default 123))
        :Bar))
; => {:variables [:foo
;                 {:directives [:fooDirective :barDirective], :default 123}
;                 :Bar]}

See also VariableDefinitions.

variables clj/s

(variables & variable-definitions)

Returns variable-definitions under key :variables. Used directly within oksa.alpha.api/opts.

Expects variable-definitions to be pair(s) of variables and types where variable is a string or a keyword (that conforms to Variable) and where type is a string or keyword that conforms to Type.

Example:

(opts (variables :fooVar :FooType
                 :barVar :BarType))
; => {:variables [:fooVar :FooType :barVar :BarType]}

See also VariableDefinitions.