dagql

package
v0.18.18 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 16, 2025 License: Apache-2.0 Imports: 34 Imported by: 0

README

dagql

DagQL is a strongly opinionated implementation of a GraphQL server.

axioms

Below are a set of assertions that build on one another.

  • All Objects are immutable.
  • All Objects are Nodes, i.e. all objects have an id.
  • All Objects have their own ID type, e.g. PointID.
  • All Objects have a top-level constructor named after the object, e.g. point.
  • All Objects may be loaded from an ID, which will create the Object if needed.
  • An Object's field may be @impure which indicates that the field's result shall not be cached.
  • An Object's field may be @meta which indicates that the field may be omitted without affecting the result.
  • All IDs are derived from the query that constructed the Object.
  • An ID is canonicalized by removing any embedded @meta selectors.
  • An ID is impure if it contains any @impure selectors or any tainted IDs.
  • An ID may be loaded on a server that has never seen its Object before.
  • When a pure ID is loaded it must always return the same Object.
  • When an impure ID is loaded it may return a different Object each time.
  • An impure query or ID may return an Object with a pure ID.
  • All data may be kept in-memory with LRU-like caching semantics.
  • All Arrays returned by Objects have deterministic order.
  • An ID may refer to an Object returned in an Array by specifying the nth index (starting at 1).
  • All Objects in Arrays have IDs: either an ID of their own, or the field's ID with nth set.
  • At the GraphQL API layer, Objects are passed to each other by ID.
  • At the code layer, Objects received as arguments are automatically loaded from a given ID.

context

This repository might be re-integrated into Dagger, but for now is just a personal experiment.

It should replace our use of the following forks:

  • github.com/dagger/graphql
  • github.com/dagger/graphql-go-tools

I think it may make sense to leave as its own repo just to make sure there's a clear boundary between the theory and the practice. But it should probably move into the Dagger account.

TODO

  • parallel query execution
  • figure out whether constructor patterns are enshrined or ad-hoc
    • ad-hoc; you can now Extend any ObjectType in the Server.
  • figure out how to return objects that already have an ID (e.g. loadFooFromID should not have itself in the returned ID)
    • if resolvers return an Object no further wrapping/ID-ing is required
  • implement caching semantics, including @impure and @meta
  • figure out telemetry
    • resolvers can be wrapped, have access to the current *idproto.ID
  • support schema docs for everything (types, fields, args, enum values, etc)
  • figure out how interfaces work
    • don't need this yet, but might be a next step for Dagger interfaces
  • IDs should also contain module info
    • IDs can now contain a reference to a single module ID which provides the implementation of the field that the ID resolves
    • all modules contained recursively by an ID (i.e. in parents or arguments) are loaded prior to evaluating the ID
      • technically we might not need to load all modules, since arguably arguments could be evaluated in a vacuum; TBD
  • IDs should also contain digest of result (stretch goal, this is higher level, e.g. we want literal file checksums for objects that represent a file)
  • get rid of Identified in favor of Object? (see interfaces + wrapping concern below)

Documentation

Index

Constants

View Source 
const InstrumentationLibrary = "dagger.io/dagql"
View Source 
const (
	XXH3 digest.Algorithm = "xxh3"
)

Variables

View Source 
var (
	DirectiveLocationQuery                = DirectiveLocations.Register("QUERY")
	DirectiveLocationMutation             = DirectiveLocations.Register("MUTATION")
	DirectiveLocationSubscription         = DirectiveLocations.Register("SUBSCRIPTION")
	DirectiveLocationField                = DirectiveLocations.Register("FIELD")
	DirectiveLocationFragmentDefinition   = DirectiveLocations.Register("FRAGMENT_DEFINITION")
	DirectiveLocationFragmentSpread       = DirectiveLocations.Register("FRAGMENT_SPREAD")
	DirectiveLocationInlineFragment       = DirectiveLocations.Register("INLINE_FRAGMENT")
	DirectiveLocationVariableDefinition   = DirectiveLocations.Register("VARIABLE_DEFINITION")
	DirectiveLocationSchema               = DirectiveLocations.Register("SCHEMA")
	DirectiveLocationScalar               = DirectiveLocations.Register("SCALAR")
	DirectiveLocationObject               = DirectiveLocations.Register("OBJECT")
	DirectiveLocationFieldDefinition      = DirectiveLocations.Register("FIELD_DEFINITION")
	DirectiveLocationArgumentDefinition   = DirectiveLocations.Register("ARGUMENT_DEFINITION")
	DirectiveLocationInterface            = DirectiveLocations.Register("INTERFACE")
	DirectiveLocationUnion                = DirectiveLocations.Register("UNION")
	DirectiveLocationEnum                 = DirectiveLocations.Register("ENUM")
	DirectiveLocationEnumValue            = DirectiveLocations.Register("ENUM_VALUE")
	DirectiveLocationInputObject          = DirectiveLocations.Register("INPUT_OBJECT")
	DirectiveLocationInputFieldDefinition = DirectiveLocations.Register("INPUT_FIELD_DEFINITION")
)
View Source 
var DirectiveLocations = NewEnum[DirectiveLocation]()

Functions

func CachePerClientSchema added in v0.18.11 

func CachePerClientSchema[P Typed, A any](srv *Server) func(context.Context, ObjectResult[P], A, CacheConfig) (*CacheConfig, error)

CachePerClientSchema is a CacheKeyFunc that scopes the cache key to both the client and the current schema of the provided server.

This should be used by anything that should invalidate when the schema changes, but also has an element of per-client dynamism.

func CachePerSchema added in v0.18.11 

func CachePerSchema[P Typed, A any](srv *Server) func(context.Context, ObjectResult[P], A, CacheConfig) (*CacheConfig, error)

CachePerSchema is a CacheKeyFunc that scopes the cache key to the schema of the provided server.

This should be used only in scenarios where literally the schema is all that determines the result, irrespective of what client is making the call.

func ContextWithID added in v0.18.7 

func ContextWithID(ctx context.Context, id *call.ID) context.Context

func CurrentID 

func CurrentID(ctx context.Context) *call.ID

func ExtractIDArgs added in v0.18.13 

func ExtractIDArgs(specs InputSpecs, id *call.ID) (map[string]Input, error)

func FormatDescription 

func FormatDescription(paras ...string) string

func HashFrom added in v0.16.3 

func HashFrom(ins ...string) digest.Digest

func IDTypeNameFor added in v0.9.8 

func IDTypeNameFor(t Typed) string

func IDTypeNameForRawType added in v0.18.6 

func IDTypeNameForRawType(t string) string

func IsInternal added in v0.10.0 

func IsInternal(ctx context.Context) bool

IsInternal returns whether the internal flag is set in the context.

func IsSkipped added in v0.18.13 

func IsSkipped(ctx context.Context) bool

func LoadIDs 

func LoadIDs[T Typed](ctx context.Context, srv *Server, ids []ID[T]) ([]T, error)

func NewDefaultHandler added in v0.15.4 

func NewDefaultHandler(es graphql.ExecutableSchema) *handler.Server

func NoopDone added in v0.11.0 

func NoopDone(res AnyResult, cached bool, rerr error)

func Tracer added in v0.11.0 

func Tracer() trace.Tracer

func UnwrapAs added in v0.16.2 

func UnwrapAs[T any](val any) (T, bool)

UnwrapAs attempts casting val to T, unwrapping as necessary.

NOTE: the order of operations is important here - it's important to first check compatibility with T before unwrapping, since sometimes T also implements Wrapper.

func WithRepeatedTelemetry added in v0.18.11 

func WithRepeatedTelemetry(ctx context.Context) context.Context

WithRepeatedTelemetry resets the state of seen cache keys so that we emit telemetry for spans that we've already seen within the session.

This is useful in scenarios where we want to see actions performed, even if they had been performed already (e.g. an LLM running tools).

func WithSkip added in v0.18.13 

func WithSkip(ctx context.Context) context.Context

Types

type AllView added in v0.12.0 

type AllView struct{}

AllView is similar to the global view, however, instead of being an empty view, it's still counted as a view.

This means that each call for a field is associated with the server view, which results in slightly different caching behavior. Additionally, it can be overridden in different views.

func (AllView) Contains added in v0.12.0 

func (AllView) Contains(view call.View) bool

type AnyObjectResult added in v0.18.13 

type AnyObjectResult interface {
	AnyResult

	// ObjectType returns the type of the object.
	ObjectType() ObjectType

	// Call evaluates the field selected by the given ID and returns the result.
	//
	// The returned value is the raw Typed value returned from the field; it must
	// be instantiated with a class for further selection.
	//
	// Any Nullable values are automatically unwrapped.
	Call(context.Context, *Server, *call.ID) (AnyResult, error)

	// Select evaluates the field selected by the given selector and returns the result.
	//
	// The returned value is the raw Typed value returned from the field; it must
	// be instantiated with a class for further selection.
	//
	// Any Nullable values are automatically unwrapped.
	Select(context.Context, *Server, Selector) (AnyResult, error)
}

AnyObjectResult is an AnyResult that wraps a selectable value (i.e. a graph object)

type AnyResult added in v0.18.13 

type AnyResult interface {
	Typed
	Wrapper
	IDable
	PostCallable
	Setter

	// DerefValue returns an AnyResult when the wrapped value is Derefable and
	// has a value set. If the value is not derefable, it returns itself.
	DerefValue() (AnyResult, bool)

	// NthValue returns the Nth value of the wrapped value when the wrapped value
	// is an Enumerable. If the wrapped value is not Enumerable, it returns an error.
	NthValue(int) (AnyResult, error)

	// WithPostCall returns a new AnyResult with the given post-call function attached to it.
	WithPostCall(fn cache.PostCallFunc) AnyResult
}

AnyResult is a Typed value wrapped with an ID constructor. The wrapped value may be any graphql type, including scalars, objects, arrays, etc. It's a Result but as an interface and without any type params, allowing it to be passed around without knowing the concrete type at compile-time.

type Argument added in v0.18.6 

type Argument struct {
	Spec InputSpec
}

func Arg added in v0.18.6 

func Arg(name string) Argument

func (Argument) Default added in v0.18.6 

func (arg Argument) Default(input Input) Argument

func (Argument) Deprecated added in v0.18.6 

func (arg Argument) Deprecated(paras ...string) Argument

func (Argument) Doc added in v0.18.6 

func (arg Argument) Doc(paras ...string) Argument

func (Argument) Experimental added in v0.18.6 

func (arg Argument) Experimental(paras ...string) Argument

func (Argument) Internal added in v0.18.11 

func (arg Argument) Internal() Argument

func (Argument) Sensitive added in v0.18.6 

func (arg Argument) Sensitive() Argument

func (Argument) View added in v0.18.6 

func (arg Argument) View(view ViewFilter) Argument

type AroundFunc 

type AroundFunc func(
	context.Context,
	AnyObjectResult,
	*call.ID,
) (context.Context, func(res AnyResult, cached bool, err error))

AroundFunc is a function that is called around every non-cached selection.

It's a little funny looking. I may have goofed it. This will be cleaned up soon.

type Array 

type Array[T Typed] []T

Array is an array of GraphQL values.

func MapArrayInput 

func MapArrayInput[T Input, R Typed](opt ArrayInput[T], fn func(T) (R, error)) (Array[R], error)

func NewBoolArray 

func NewBoolArray(elems ...bool) Array[Boolean]

func NewBooleanArray added in v0.18.13 

func NewBooleanArray(elems ...bool) Array[Boolean]

func NewFloatArray 

func NewFloatArray[T constraints.Float](elems ...T) Array[Float]

func NewIntArray 

func NewIntArray[T constraints.Integer](elems ...T) Array[Int]

func NewStringArray 

func NewStringArray(elems ...string) Array[String]

func ToArray 

func ToArray[A any, T Typed](fn func(A) T, elems ...A) Array[T]

ToArray creates a new Array by applying the given function to each element of the given slice.

func (Array[T]) Element added in v0.16.3 

func (arr Array[T]) Element() Typed

func (Array[T]) Len 

func (arr Array[T]) Len() int

func (Array[T]) Nth 

func (arr Array[T]) Nth(i int) (Typed, error)

func (Array[T]) NthValue added in v0.18.13 

func (arr Array[T]) NthValue(i int, enumID *call.ID) (AnyResult, error)

func (Array[T]) Type 

func (i Array[T]) Type() *ast.Type

type ArrayInput 

type ArrayInput[I Input] []I

Array is an array of GraphQL values.

func (ArrayInput[I]) DecodeInput 

func (a ArrayInput[I]) DecodeInput(val any) (Input, error)

func (ArrayInput[S]) Decoder 

func (a ArrayInput[S]) Decoder() InputDecoder

func (ArrayInput[I]) SetField 

func (d ArrayInput[I]) SetField(val reflect.Value) error

func (ArrayInput[S]) ToArray 

func (a ArrayInput[S]) ToArray() Array[S]

func (ArrayInput[S]) ToLiteral 

func (i ArrayInput[S]) ToLiteral() call.Literal

func (ArrayInput[S]) Type 

func (a ArrayInput[S]) Type() *ast.Type

type Boolean 

type Boolean bool

Boolean is a GraphQL Boolean scalar.

func NewBoolean 

func NewBoolean(val bool) Boolean

func (Boolean) Bool 

func (b Boolean) Bool() bool

func (Boolean) DecodeInput 

func (Boolean) DecodeInput(val any) (Input, error)

func (Boolean) Decoder 

func (Boolean) Decoder() InputDecoder

func (Boolean) MarshalJSON 

func (b Boolean) MarshalJSON() ([]byte, error)

func (Boolean) SetField 

func (b Boolean) SetField(v reflect.Value) error

func (Boolean) ToLiteral 

func (b Boolean) ToLiteral() call.Literal

func (Boolean) Type 

func (Boolean) Type() *ast.Type

func (Boolean) TypeDefinition 

func (b Boolean) TypeDefinition(view call.View) *ast.Definition

func (Boolean) TypeName 

func (Boolean) TypeName() string

func (*Boolean) UnmarshalJSON 

func (b *Boolean) UnmarshalJSON(p []byte) error

type CacheCallOpt added in v0.18.3 

type CacheCallOpt interface {
	SetCacheCallOpt(*CacheCallOpts)
}

func WithTelemetry added in v0.18.3 

func WithTelemetry(telemetry TelemetryFunc) CacheCallOpt

type CacheCallOptFunc added in v0.18.3 

type CacheCallOptFunc func(*CacheCallOpts)

func (CacheCallOptFunc) SetCacheCallOpt added in v0.18.3 

func (f CacheCallOptFunc) SetCacheCallOpt(opts *CacheCallOpts)

type CacheCallOpts added in v0.18.3 

type CacheCallOpts struct {
	Telemetry TelemetryFunc
}

func (CacheCallOpts) SetCacheCallOpt added in v0.18.3 

func (o CacheCallOpts) SetCacheCallOpt(opts *CacheCallOpts)

type CacheConfig added in v0.16.3 

type CacheConfig struct {
	Digest      digest.Digest
	UpdatedArgs map[string]Input
}

CacheConfig is the configuration for caching a field. Currently just custom digest but intended to support more in time (TTL, etc).

func CacheAsRequested added in v0.18.9 

func CacheAsRequested[T Typed, A CacheControllableArgs](ctx context.Context, i ObjectResult[T], a A, cc CacheConfig) (*CacheConfig, error)

func CachePerCall added in v0.16.3 

func CachePerCall[P Typed, A any](
	_ context.Context,
	_ ObjectResult[P],
	_ A,
	cacheCfg CacheConfig,
) (*CacheConfig, error)

CachePerCall results in the API always running when called, but the returned result from that call is cached. For instance, the API may return a snapshot of some live mutating state; in that case the first call to get the snapshot should always run but if the returned object is passed around it should continue to be that snapshot rather than the API always re-running.

func CachePerClient added in v0.16.3 

func CachePerClient[P Typed, A any](
	ctx context.Context,
	inst ObjectResult[P],
	args A,
	cacheCfg CacheConfig,
) (*CacheConfig, error)

CachePerClient is a CacheKeyFunc that scopes the cache key to the client by mixing in the client ID to the original digest of the operation. It should be used when the operation should be run for each client, but not more than once for a given client. Canonical examples include loading client filesystem data or referencing client-side sockets/ports.

func CachePerClientObject added in v0.16.3 

func CachePerClientObject[A any](
	ctx context.Context,
	_ AnyObjectResult,
	_ A,
	cacheCfg CacheConfig,
) (*CacheConfig, error)

CachePerClientObject is the same as CachePerClient but when you have a dagql.Object instead of a dagql.Result.

func CachePerSession added in v0.18.4 

func CachePerSession[P Typed, A any](
	ctx context.Context,
	inst ObjectResult[P],
	args A,
	cacheCfg CacheConfig,
) (*CacheConfig, error)

CachePerSession is a CacheKeyFunc that scopes the cache key to the session by mixing in the session ID to the original digest of the operation. It should be used when the operation should be run for each session, but not more than once for a given session.

func CachePerSessionObject added in v0.18.5 

func CachePerSessionObject[A any](
	ctx context.Context,
	_ AnyObjectResult,
	_ A,
	cacheCfg CacheConfig,
) (*CacheConfig, error)

CachePerSessionObject is the same as CachePerSession but when you have a dagql.Object instead of a dagql.Result.

type CacheControlType added in v0.18.9 

type CacheControlType int
const (
	CacheTypeUnset CacheControlType = iota
	CacheTypePerClient
	CacheTypePerCall
)

type CacheControllableArgs added in v0.18.9 

type CacheControllableArgs interface {
	CacheType() CacheControlType
}

this could all be un-generic'd and repeated per-API. might be cleaner at the end of the day.

type CacheKeyType added in v0.18.3 

type CacheKeyType = digest.Digest

type CacheResult added in v0.18.3 

type CacheResult = cache.Result[CacheKeyType, CacheValueType]

type CacheSpec added in v0.16.3 

type CacheSpec struct {
	// If set, this GetCacheConfig will be called before ID evaluation to determine the
	// ID's digest. Otherwise the ID defaults to the digest of the call chain.
	GetCacheConfig GenericGetCacheConfigFunc

	// If set, the result of this field will never be cached and not have concurrent equal
	// calls deduped. The string value is a reason why the field should not be cached.
	DoNotCache string
}

type CacheValWithCallbacks added in v0.16.3 

type CacheValWithCallbacks = cache.ValueWithCallbacks[CacheValueType]

type CacheValueType added in v0.18.3 

type CacheValueType = AnyResult

type Class 

type Class[T Typed] struct {
	// contains filtered or unexported fields
}

Class is a class of Object types.

The class is defined by a set of fields, which are installed into the class dynamically at runtime.

func NewClass 

func NewClass[T Typed](srv *Server, opts_ ...ClassOpts[T]) Class[T]

NewClass returns a new empty class for a given type.

func (Class[T]) Call 

func (class Class[T]) Call(
	ctx context.Context,
	srv *Server,
	node ObjectResult[T],
	fieldName string,
	view call.View,
	args map[string]Input,
) (*CacheValWithCallbacks, error)

Call calls a field on the class against an instance.

func (Class[T]) Extend 

func (class Class[T]) Extend(spec FieldSpec, fun FieldFunc, cacheSpec CacheSpec)

func (Class[T]) Field 

func (class Class[T]) Field(name string, view call.View) (Field[T], bool)

func (Class[T]) FieldSpec added in v0.16.2 

func (class Class[T]) FieldSpec(name string, view call.View) (FieldSpec, bool)

func (Class[T]) IDType 

func (class Class[T]) IDType() (IDType, bool)

func (Class[T]) Install 

func (class Class[T]) Install(fields ...Field[T])

func (Class[T]) New 

func (class Class[T]) New(val AnyResult) (AnyObjectResult, error)

New returns a new instance of the class.

func (Class[T]) ParseField 

func (class Class[T]) ParseField(ctx context.Context, view call.View, astField *ast.Field, vars map[string]any) (Selector, *ast.Type, error)

ParseField parses a field selection into a Selector and return type.

func (Class[T]) TypeDefinition 

func (class Class[T]) TypeDefinition(view call.View) *ast.Definition

TypeDefinition returns the schema definition of the class.

The definition is derived from the type name, description, and fields. The type may implement Definitive or Descriptive to provide more information.

Each currently defined field is installed on the returned definition.

func (Class[T]) TypeName 

func (class Class[T]) TypeName() string

func (Class[T]) Typed 

func (class Class[T]) Typed() Typed

type ClassOpts 

type ClassOpts[T Typed] struct {
	// NoIDs disables the default "id" field and disables the IDType method.
	NoIDs bool

	// Typed contains the Typed value whose Type() determines the class's type.
	//
	// In the simple case, we can just use a zero-value, but it is also allowed
	// to use a dynamic Typed value.
	Typed T
}

type DecoderFunc 

type DecoderFunc func(any) (Input, error)

func (DecoderFunc) DecodeInput 

func (f DecoderFunc) DecodeInput(val any) (Input, error)

type Definitive 

type Definitive interface {
	TypeDefinition(view call.View) *ast.Definition
}

Definitive is a type that knows how to define itself in the schema.

type Derefable 

type Derefable interface {
	Deref() (Typed, bool)
}

Derefable is a type that wraps another type.

In practice this is only used for Optional and Nullable. It should be used sparingly, since wrapping interfaces explodes very quickly.

type DerefableResult added in v0.18.13 

type DerefableResult interface {
	Derefable
	DerefToResult(constructor *call.ID, postCall cache.PostCallFunc) (AnyResult, bool)
}

DerefableResult is a Derefable that can return a result underlied by the specific type the Derefable wraps.

type Descriptive 

type Descriptive interface {
	TypeDescription() string
}

Descriptive is an interface for types that have a description.

The description is used in the schema. To provide a full definition, implement Definitive instead.

type DirectiveLocation 

type DirectiveLocation string

func (DirectiveLocation) Decoder 

func (DirectiveLocation) Decoder() InputDecoder

func (DirectiveLocation) ToLiteral 

func (d DirectiveLocation) ToLiteral() call.Literal

func (DirectiveLocation) Type 

func (DirectiveLocation) Type() *ast.Type

type DirectiveSpec 

type DirectiveSpec struct {
	Name         string              `field:"true"`
	Description  string              `field:"true"`
	Args         InputSpecs          `field:"true"`
	Locations    []DirectiveLocation `field:"true"`
	IsRepeatable bool                `field:"true"`
}

func (DirectiveSpec) DirectiveDefinition 

func (d DirectiveSpec) DirectiveDefinition(view call.View) *ast.DirectiveDefinition

type DynamicArrayInput 

type DynamicArrayInput struct {
	Elem   Input
	Values []Input
}

func (DynamicArrayInput) DecodeInput 

func (d DynamicArrayInput) DecodeInput(val any) (Input, error)

func (DynamicArrayInput) Decoder 

func (d DynamicArrayInput) Decoder() InputDecoder

func (DynamicArrayInput) Element added in v0.16.3 

func (d DynamicArrayInput) Element() Typed

func (DynamicArrayInput) Len 

func (d DynamicArrayInput) Len() int

func (DynamicArrayInput) Nth 

func (d DynamicArrayInput) Nth(i int) (Typed, error)

func (DynamicArrayInput) NthValue added in v0.18.13 

func (d DynamicArrayInput) NthValue(i int, enumID *call.ID) (AnyResult, error)

func (DynamicArrayInput) SetField 

func (d DynamicArrayInput) SetField(val reflect.Value) error

func (DynamicArrayInput) ToLiteral 

func (d DynamicArrayInput) ToLiteral() call.Literal

func (DynamicArrayInput) Type 

func (d DynamicArrayInput) Type() *ast.Type

type DynamicArrayOutput 

type DynamicArrayOutput struct {
	Elem   Typed
	Values []Typed
}

func (DynamicArrayOutput) Element added in v0.16.3 

func (d DynamicArrayOutput) Element() Typed

func (DynamicArrayOutput) Len 

func (d DynamicArrayOutput) Len() int

func (DynamicArrayOutput) MarshalJSON 

func (d DynamicArrayOutput) MarshalJSON() ([]byte, error)

func (DynamicArrayOutput) Nth 

func (d DynamicArrayOutput) Nth(i int) (Typed, error)

func (DynamicArrayOutput) NthValue added in v0.18.13 

func (d DynamicArrayOutput) NthValue(i int, enumID *call.ID) (AnyResult, error)

func (DynamicArrayOutput) SetField added in v0.9.9 

func (d DynamicArrayOutput) SetField(val reflect.Value) error

func (DynamicArrayOutput) Type 

func (d DynamicArrayOutput) Type() *ast.Type

type DynamicNullable 

type DynamicNullable struct {
	Elem  Typed
	Value Typed
	Valid bool
}

func (DynamicNullable) Deref 

func (n DynamicNullable) Deref() (Typed, bool)

func (DynamicNullable) DerefToResult added in v0.18.13 

func (n DynamicNullable) DerefToResult(
	constructor *call.ID,
	postCall cache.PostCallFunc,
) (AnyResult, bool)

func (DynamicNullable) MarshalJSON 

func (n DynamicNullable) MarshalJSON() ([]byte, error)

func (DynamicNullable) Type 

func (n DynamicNullable) Type() *ast.Type

func (*DynamicNullable) UnmarshalJSON 

func (n *DynamicNullable) UnmarshalJSON(p []byte) error

type DynamicOptional 

type DynamicOptional struct {
	Elem  Input
	Value Input
	Valid bool
}

func (DynamicOptional) DecodeInput 

func (o DynamicOptional) DecodeInput(val any) (Input, error)

func (DynamicOptional) Decoder 

func (o DynamicOptional) Decoder() InputDecoder

func (DynamicOptional) Deref 

func (o DynamicOptional) Deref() (Typed, bool)

func (DynamicOptional) MarshalJSON 

func (o DynamicOptional) MarshalJSON() ([]byte, error)

func (DynamicOptional) SetField 

func (o DynamicOptional) SetField(val reflect.Value) error

func (DynamicOptional) ToLiteral 

func (o DynamicOptional) ToLiteral() call.Literal

func (DynamicOptional) Type 

func (o DynamicOptional) Type() *ast.Type

type DynamicResultArrayOutput added in v0.18.13 

type DynamicResultArrayOutput struct {
	Elem   Typed
	Values []AnyResult
}

func (DynamicResultArrayOutput) Element added in v0.18.13 

func (d DynamicResultArrayOutput) Element() Typed

func (DynamicResultArrayOutput) Len added in v0.18.13 

func (d DynamicResultArrayOutput) Len() int

func (DynamicResultArrayOutput) MarshalJSON added in v0.18.13 

func (d DynamicResultArrayOutput) MarshalJSON() ([]byte, error)

func (DynamicResultArrayOutput) Nth added in v0.18.13 

func (d DynamicResultArrayOutput) Nth(i int) (Typed, error)

func (DynamicResultArrayOutput) NthValue added in v0.18.13 

func (d DynamicResultArrayOutput) NthValue(i int, _ *call.ID) (AnyResult, error)

func (DynamicResultArrayOutput) SetField added in v0.18.13 

func (d DynamicResultArrayOutput) SetField(val reflect.Value) error

func (DynamicResultArrayOutput) Type added in v0.18.13 

func (d DynamicResultArrayOutput) Type() *ast.Type

type EnumValue 

type EnumValue[T enumValue] struct {
	Value       T
	Underlying  T
	Description string
	View        ViewFilter
}

type EnumValueName added in v0.13.6 

type EnumValueName struct {
	Enum string
	Name string
}

func (*EnumValueName) DecodeInput added in v0.13.6 

func (e *EnumValueName) DecodeInput(val any) (Input, error)

func (*EnumValueName) Decoder added in v0.13.6 

func (e *EnumValueName) Decoder() InputDecoder

func (*EnumValueName) MarshalJSON added in v0.13.6 

func (e *EnumValueName) MarshalJSON() ([]byte, error)

func (*EnumValueName) ToLiteral added in v0.13.6 

func (e *EnumValueName) ToLiteral() call.Literal

func (*EnumValueName) Type added in v0.13.6 

func (e *EnumValueName) Type() *ast.Type

func (*EnumValueName) TypeDefinition added in v0.13.6 

func (e *EnumValueName) TypeDefinition(view call.View) *ast.Definition

func (*EnumValueName) TypeName added in v0.13.6 

func (e *EnumValueName) TypeName() string

type EnumValues 

type EnumValues[T enumValue] []EnumValue[T]

EnumValues is a list of possible values for an Enum.

func NewEnum 

func NewEnum[T enumValue](vals ...T) *EnumValues[T]

NewEnum creates a new EnumType with the given possible values.

func (*EnumValues[T]) Alias added in v0.18.11 

func (e *EnumValues[T]) Alias(val T, target T) T

func (*EnumValues[T]) AliasView added in v0.18.11 

func (e *EnumValues[T]) AliasView(val T, target T, view ViewFilter) T

func (*EnumValues[T]) DecodeInput 

func (e *EnumValues[T]) DecodeInput(val any) (Input, error)

func (*EnumValues[T]) Install 

func (e *EnumValues[T]) Install(srv *Server)

func (*EnumValues[T]) Literal 

func (e *EnumValues[T]) Literal(val T) call.Literal

func (*EnumValues[T]) Lookup 

func (e *EnumValues[T]) Lookup(val string) (T, error)

func (*EnumValues[T]) PossibleValues 

func (e *EnumValues[T]) PossibleValues(view call.View) ast.EnumValueList

func (*EnumValues[T]) Register 

func (e *EnumValues[T]) Register(val T, desc ...string) T

func (*EnumValues[T]) RegisterView added in v0.18.11 

func (e *EnumValues[T]) RegisterView(val T, view ViewFilter, desc ...string) T

func (*EnumValues[T]) Type 

func (e *EnumValues[T]) Type() *ast.Type

func (*EnumValues[T]) TypeDefinition 

func (e *EnumValues[T]) TypeDefinition(view call.View) *ast.Definition

func (*EnumValues[T]) TypeName 

func (e *EnumValues[T]) TypeName() string

type Enumerable 

type Enumerable interface {
	// Element returns the element of the Enumerable.
	Element() Typed
	// Len returns the number of elements in the Enumerable.
	Len() int
	// Nth returns the Nth element of the Enumerable, with 1 representing the
	// first entry.
	Nth(int) (Typed, error)

	NthValue(i int, enumID *call.ID) (AnyResult, error)
}

Enumerable is a value that has a length and allows indexing.

type ExactView added in v0.12.0 

type ExactView string

ExactView contains exactly one view.

func (ExactView) Contains added in v0.12.0 

func (exact ExactView) Contains(view call.View) bool

type ExtendedError 

type ExtendedError interface {
	error
	Extensions() map[string]any
}

ExtendedError is an error that can provide extra data in an error response.

type Field 

type Field[T Typed] struct {
	Spec      *FieldSpec
	CacheSpec CacheSpec
	Func      func(context.Context, ObjectResult[T], map[string]Input, call.View) (AnyResult, error)
}

Field defines a field of an Object type.

func Func 

func Func[T Typed, A any, R any](name string, fn FuncHandler[T, A, R]) Field[T]

Func is a helper for defining a field resolver and schema.

The function must accept a context.Context, the receiver, and a struct of arguments. All fields of the arguments struct must be Typed so that the schema may be derived, and Scalar to ensure a default value may be provided.

Arguments use struct tags to further configure the schema:

  • `name:"bar"` sets the name of the argument. By default this is the toLowerCamel'd field name.
  • `default:"foo"` sets the default value of the argument. The Scalar type determines how this value is parsed.
  • `doc:"..."` sets the description of the argument.

The function must return a Typed value, and an error.

To configure a description for the field in the schema, call .Doc on the result.

func FuncWithCacheKey added in v0.15.3 

func FuncWithCacheKey[T Typed, A any, R any](
	name string,
	fn FuncHandler[T, A, R],
	cacheFn GetCacheConfigFunc[T, A],
) Field[T]

FuncWithCacheKey is like Func but allows specifying a custom digest that will be used to cache the operation in dagql.

func NodeFunc 

func NodeFunc[T Typed, A any, R any](name string, fn NodeFuncHandler[T, A, R]) Field[T]

NodeFunc is the same as Func, except it passes the ObjectResult instead of the receiver so that you can access its ID.

func NodeFuncWithCacheKey added in v0.15.3 

func NodeFuncWithCacheKey[T Typed, A any, R any](
	name string,
	fn NodeFuncHandler[T, A, R],
	cacheFn GetCacheConfigFunc[T, A],
) Field[T]

NodeFuncWithCacheKey is like NodeFunc but allows specifying a custom digest that will be used to cache the operation in dagql.

func (Field[T]) Args added in v0.18.6 

func (field Field[T]) Args(args ...Argument) Field[T]

func (Field[T]) Deprecated 

func (field Field[T]) Deprecated(paras ...string) Field[T]

Deprecated marks the field as deprecated, meaning it should not be used by new code.

func (Field[T]) DoNotCache added in v0.16.3 

func (field Field[T]) DoNotCache(reason string, paras ...string) Field[T]

DoNotCache marks the field as not to be stored in the cache for the given reason why

func (Field[T]) Doc 

func (field Field[T]) Doc(paras ...string) Field[T]

Doc sets the description of the field. Each argument is joined by two empty lines.

func (Field[T]) Experimental added in v0.18.4 

func (field Field[T]) Experimental(paras ...string) Field[T]

Deprecated marks the field as experimental

func (Field[T]) Extend added in v0.12.0 

func (field Field[T]) Extend() Field[T]

func (Field[T]) FieldDefinition 

func (field Field[T]) FieldDefinition(view call.View) *ast.FieldDefinition

FieldDefinition returns the schema definition of the field.

func (Field[T]) Sensitive added in v0.16.2 

func (field Field[T]) Sensitive() Field[T]

func (Field[T]) View added in v0.12.0 

func (field Field[T]) View(view ViewFilter) Field[T]

View sets a view for this field.

type FieldFunc 

type FieldFunc func(context.Context, AnyResult, map[string]Input) (AnyResult, error)

FieldFunc is a function that implements a field on an object while limited to the object's external interface.

type FieldSpec 

type FieldSpec struct {
	// Name is the name of the field.
	Name string
	// Description is the description of the field.
	Description string
	// Args is the list of arguments that the field accepts.
	Args InputSpecs
	// Type is the type of the field's result.
	Type Typed
	// Sensitive indicates that the value returned by this field is sensitive and
	// should not be displayed in telemetry.
	Sensitive bool
	// DeprecatedReason deprecates the field and provides a reason.
	DeprecatedReason string
	// ExperimentalReason marks the field as experimental and provides a reason.
	ExperimentalReason string
	// Module is the module that provides the field's implementation.
	Module *call.Module
	// Directives is the list of GraphQL directives attached to this field.
	Directives []*ast.Directive

	// ViewFilter is filter that specifies under which views this field is
	// accessible. If not view is present, the default is the "global" view.
	ViewFilter ViewFilter
	// contains filtered or unexported fields
}

FieldSpec is a specification for a field.

func (FieldSpec) FieldDefinition 

func (spec FieldSpec) FieldDefinition(view call.View) *ast.FieldDefinition

type Fields 

type Fields[T Typed] []Field[T]

Fields defines a set of fields for an Object type.

func (Fields[T]) Install 

func (fields Fields[T]) Install(server *Server)

Install installs the field's Object type if needed, and installs all fields into the type.

type Float 

type Float float64

Float is a GraphQL Float scalar.

func NewFloat 

func NewFloat[T constraints.Float](val T) Float

func (Float) DecodeInput 

func (Float) DecodeInput(val any) (Input, error)

func (Float) Decoder 

func (Float) Decoder() InputDecoder

func (Float) Float64 

func (f Float) Float64() float64

func (Float) MarshalJSON 

func (f Float) MarshalJSON() ([]byte, error)

func (Float) SetField 

func (f Float) SetField(v reflect.Value) error

func (Float) ToLiteral 

func (f Float) ToLiteral() call.Literal

func (Float) Type 

func (Float) Type() *ast.Type

func (Float) TypeDefinition 

func (f Float) TypeDefinition(view call.View) *ast.Definition

func (Float) TypeName 

func (Float) TypeName() string

func (*Float) UnmarshalJSON 

func (f *Float) UnmarshalJSON(p []byte) error

type FuncHandler added in v0.16.3 

type FuncHandler[T Typed, A any, R any] func(ctx context.Context, self T, args A) (R, error)

type GenericGetCacheConfigFunc added in v0.16.3 

type GenericGetCacheConfigFunc func(context.Context, AnyResult, map[string]Input, call.View, CacheConfig) (*CacheConfig, error)

type GetCacheConfigFunc added in v0.16.3 

type GetCacheConfigFunc[T Typed, A any] func(context.Context, ObjectResult[T], A, CacheConfig) (*CacheConfig, error)

type ID 

type ID[T Typed] struct {
	// contains filtered or unexported fields
}

ID is a type-checked ID scalar.

func NewDynamicID 

func NewDynamicID[T Typed](id *call.ID, typed T) ID[T]

func NewID 

func NewID[T Typed](id *call.ID) ID[T]

func WalkedIDs added in v0.12.1 

func WalkedIDs[T Typed](idWalker *IDWalker) []ID[T]

func (*ID[T]) Decode 

func (i *ID[T]) Decode(str string) error

func (ID[T]) DecodeInput 

func (i ID[T]) DecodeInput(val any) (Input, error)

New creates a new ID with the given value.

It accepts either an *call.ID or a string. The string is expected to be the base64-encoded representation of an *call.ID.

func (ID[T]) Decoder 

func (i ID[T]) Decoder() InputDecoder

func (ID[T]) Display 

func (i ID[T]) Display() string

func (ID[T]) Encode 

func (i ID[T]) Encode() (string, error)

func (ID[T]) ID 

func (i ID[T]) ID() *call.ID

ID returns the ID of the value.

func (ID[T]) Load 

func (i ID[T]) Load(ctx context.Context, server *Server) (res ObjectResult[T], _ error)

Load loads the instance with the given ID from the server.

func (ID[T]) MarshalJSON 

func (i ID[T]) MarshalJSON() ([]byte, error)

func (ID[T]) SetField 

func (i ID[T]) SetField(v reflect.Value) error

func (ID[T]) String 

func (i ID[T]) String() string

String returns the ID in ClassID@sha256:... format.

func (ID[T]) ToLiteral 

func (i ID[T]) ToLiteral() call.Literal

func (ID[T]) Type 

func (i ID[T]) Type() *ast.Type

Type returns the GraphQL type of the value.

func (ID[T]) TypeDefinition 

func (i ID[T]) TypeDefinition(view call.View) *ast.Definition

TypeDefinition returns the GraphQL definition of the type.

func (ID[T]) TypeName 

func (i ID[T]) TypeName() string

TypeName returns the name of the type with "ID" appended, e.g. `FooID`.

func (*ID[T]) UnmarshalJSON 

func (i *ID[T]) UnmarshalJSON(p []byte) error

type IDType 

type IDType interface {
	Input
	IDable
	ScalarType
}

type IDWalker added in v0.12.1 

type IDWalker struct {
	// contains filtered or unexported fields
}

func WalkID added in v0.12.1 

func WalkID(id *call.ID, skipTopLevel bool) (*IDWalker, error)

type IDable 

type IDable interface {
	// ID returns the ID of the value.
	ID() *call.ID
}

type Input 

type Input interface {
	// All Inputs are typed.
	Typed
	// All Inputs are able to be represented as a Literal.
	call.Literate
	// All Inputs now how to decode new instances of themselves.
	Decoder() InputDecoder
}

Input represents any value which may be passed as an input.

type InputDecoder 

type InputDecoder interface {
	// Decode converts a value to the Input type, if possible.
	DecodeInput(any) (Input, error)
}

InputDecoder is a type that knows how to decode values into Inputs.

type InputObject 

type InputObject[T Type] struct {
	Value T
}

func (InputObject[T]) Decoder 

func (InputObject[T]) Decoder() InputDecoder

func (InputObject[T]) ToLiteral 

func (input InputObject[T]) ToLiteral() call.Literal

func (InputObject[T]) Type 

func (InputObject[T]) Type() *ast.Type

type InputObjectSpec 

type InputObjectSpec struct {
	Name        string
	Description string
	Fields      InputSpecs
}

func MustInputSpec 

func MustInputSpec(val Type) InputObjectSpec

func (InputObjectSpec) Install 

func (spec InputObjectSpec) Install(srv *Server)

func (InputObjectSpec) Type 

func (spec InputObjectSpec) Type() *ast.Type

func (InputObjectSpec) TypeDefinition 

func (spec InputObjectSpec) TypeDefinition(view call.View) *ast.Definition

func (InputObjectSpec) TypeName 

func (spec InputObjectSpec) TypeName() string

type InputSpec 

type InputSpec struct {
	// Name is the name of the argument.
	Name string
	// Description is the description of the argument.
	Description string
	// Type is the type of the argument.
	Type Input
	// Default is the default value of the argument.
	Default Input
	// DeprecatedReason deprecates the input and provides a reason.
	DeprecatedReason string
	// ExperimentalReason marks the field as experimental and provides a reason.
	ExperimentalReason string
	// Sensitive indicates that the value of this arg is sensitive and should be
	// omitted from telemetry.
	Sensitive bool
	// Directives is the list of GraphQL directives attached to this input.
	Directives []*ast.Directive

	// ViewFilter is filter that specifies under which views this field is
	// accessible. If not view is present, the default is the "global" view.
	ViewFilter ViewFilter

	// Internal indicates that this input can only be set by internal server
	// calls, never by external clients. It may appear in IDs sent to/from
	// clients, but can't be set in new graphql queries.
	// This argument will not be exposed in the introspection schema.
	Internal bool
}

InputSpec specifies a field argument, or an input field.

type InputSpecs 

type InputSpecs struct {
	// contains filtered or unexported fields
}

func InputSpecsForType added in v0.17.2 

func InputSpecsForType(obj any, optIn bool) (InputSpecs, error)

func NewInputSpecs added in v0.18.6 

func NewInputSpecs(specs ...InputSpec) InputSpecs

func (*InputSpecs) Add added in v0.18.6 

func (specs *InputSpecs) Add(target ...InputSpec)

func (InputSpecs) ArgumentDefinitions 

func (specs InputSpecs) ArgumentDefinitions(view call.View) []*ast.ArgumentDefinition

func (InputSpecs) Decode added in v0.17.2 

func (specs InputSpecs) Decode(inputs map[string]Input, dest any, view call.View) error

func (InputSpecs) FieldDefinitions 

func (specs InputSpecs) FieldDefinitions(view call.View) (defs []*ast.FieldDefinition)

func (InputSpecs) Input added in v0.18.6 

func (specs InputSpecs) Input(name string, view call.View) (InputSpec, bool)

func (InputSpecs) Inputs added in v0.18.6 

func (specs InputSpecs) Inputs(view call.View) (args []InputSpec)

type Inputs 

type Inputs []NamedInput

func (Inputs) Lookup 

func (args Inputs) Lookup(name string) (Input, bool)

type InstallHook added in v0.17.0 

type InstallHook interface {
	InstallObject(ObjectType)
}

type Int 

type Int int64

Int is a GraphQL Int scalar.

func NewInt 

func NewInt[T constraints.Integer](val T) Int

func (Int) DecodeInput 

func (Int) DecodeInput(val any) (Input, error)

func (Int) Decoder 

func (Int) Decoder() InputDecoder

func (Int) Int 

func (i Int) Int() int

func (Int) Int64 

func (i Int) Int64() int64

func (Int) MarshalJSON 

func (i Int) MarshalJSON() ([]byte, error)

func (Int) SetField 

func (i Int) SetField(v reflect.Value) error

func (Int) ToLiteral 

func (i Int) ToLiteral() call.Literal

func (Int) Type 

func (Int) Type() *ast.Type

func (Int) TypeDefinition 

func (i Int) TypeDefinition(view call.View) *ast.Definition

func (Int) TypeName 

func (Int) TypeName() string

func (*Int) UnmarshalJSON 

func (i *Int) UnmarshalJSON(p []byte) error

type InterfaceValue added in v0.18.13 

type InterfaceValue interface {
	// UnderlyingObject returns the underlying object of the InterfaceValue
	UnderlyingObject() (Typed, error)
}

InterfaceValue is a value that wraps some underlying object with a interface to that object's API. This type exists to support unwrapping it and getting the underlying object.

type NamedInput 

type NamedInput struct {
	Name  string
	Value Input
}

func (NamedInput) String 

func (arg NamedInput) String() string

type NodeFuncHandler added in v0.16.3 

type NodeFuncHandler[T Typed, A any, R any] func(ctx context.Context, self ObjectResult[T], args A) (R, error)

type Nullable 

type Nullable[T Typed] struct {
	Value T
	Valid bool
}

Nullable wraps a type and allows it to be null.

This is used for optional arguments and return values.

func MapOpt 

func MapOpt[I Input, R Typed](opt Optional[I], fn func(I) (R, error)) (Nullable[R], error)

func NonNull 

func NonNull[T Typed](val T) Nullable[T]

func Null 

func Null[T Typed]() Nullable[T]

func (Nullable[T]) Deref 

func (n Nullable[T]) Deref() (Typed, bool)

func (Nullable[T]) DerefToResult added in v0.18.13 

func (n Nullable[T]) DerefToResult(
	constructor *call.ID,
	postCall cache.PostCallFunc,
) (AnyResult, bool)

func (Nullable[T]) MarshalJSON 

func (n Nullable[T]) MarshalJSON() ([]byte, error)

func (Nullable[T]) Type 

func (n Nullable[T]) Type() *ast.Type

func (*Nullable[T]) UnmarshalJSON 

func (n *Nullable[T]) UnmarshalJSON(p []byte) error

type ObjectResult added in v0.18.13 

type ObjectResult[T Typed] struct {
	Result[T]
	// contains filtered or unexported fields
}

func LoadIDResults added in v0.18.13 

func LoadIDResults[T Typed](ctx context.Context, srv *Server, ids []ID[T]) ([]ObjectResult[T], error)

func NewObjectResultForCurrentID added in v0.18.13 

func NewObjectResultForCurrentID[T Typed](
	ctx context.Context,
	srv *Server,
	self T,
) (ObjectResult[T], error)

func NewObjectResultForID added in v0.18.13 

func NewObjectResultForID[T Typed](
	self T,
	srv *Server,
	id *call.ID,
) (res ObjectResult[T], _ error)

func (ObjectResult[T]) Call added in v0.18.13 

func (r ObjectResult[T]) Call(ctx context.Context, s *Server, newID *call.ID) (AnyResult, error)

Call calls the field on the instance specified by the ID.

func (ObjectResult[T]) DerefValue added in v0.18.13 

func (r ObjectResult[T]) DerefValue() (AnyResult, bool)

func (ObjectResult[T]) MarshalJSON added in v0.18.13 

func (r ObjectResult[T]) MarshalJSON() ([]byte, error)

func (ObjectResult[T]) ObjectType added in v0.18.13 

func (r ObjectResult[T]) ObjectType() ObjectType

ObjectType returns the ObjectType of the instance.

func (ObjectResult[T]) Select added in v0.18.13 

func (r ObjectResult[T]) Select(ctx context.Context, s *Server, sel Selector) (AnyResult, error)

Select calls the field on the instance specified by the selector

func (ObjectResult[T]) SetField added in v0.18.13 

func (r ObjectResult[T]) SetField(field reflect.Value) error

func (ObjectResult[T]) WithObjectDigest added in v0.18.13 

func (r ObjectResult[T]) WithObjectDigest(customDigest digest.Digest) ObjectResult[T]

type ObjectResultArray added in v0.18.13 

type ObjectResultArray[T Typed] []ObjectResult[T]

func (ObjectResultArray[T]) Element added in v0.18.13 

func (arr ObjectResultArray[T]) Element() Typed

func (ObjectResultArray[T]) Len added in v0.18.13 

func (arr ObjectResultArray[T]) Len() int

func (ObjectResultArray[T]) Nth added in v0.18.13 

func (arr ObjectResultArray[T]) Nth(i int) (Typed, error)

func (ObjectResultArray[T]) NthValue added in v0.18.13 

func (arr ObjectResultArray[T]) NthValue(i int, enumID *call.ID) (AnyResult, error)

func (ObjectResultArray[T]) Type added in v0.18.13 

func (i ObjectResultArray[T]) Type() *ast.Type

type ObjectType 

type ObjectType interface {
	Type
	// Typed returns a Typed value whose Type refers to the object type.
	Typed() Typed
	// IDType returns the scalar type for the object's IDs.
	IDType() (IDType, bool)
	// New creates a new instance of the type.
	New(val AnyResult) (AnyObjectResult, error)
	// ParseField parses the given field and returns a Selector and an expected
	// return type.
	ParseField(ctx context.Context, view call.View, astField *ast.Field, vars map[string]any) (Selector, *ast.Type, error)
	// Extend registers an additional field onto the type.
	//
	// Unlike natively added fields, the extended func is limited to the external
	// Object interface.
	// cacheKeyFun is optional, if not set the default dagql ID cache key will be used.
	Extend(spec FieldSpec, fun FieldFunc, cacheSpec CacheSpec)
	// FieldSpec looks up a field spec by name.
	FieldSpec(name string, view call.View) (FieldSpec, bool)
}

ObjectType represents a GraphQL Object type.

type OnReleaser added in v0.16.3 

type OnReleaser interface {
	OnRelease(context.Context) error
}

A type that has a callback attached that needs to always run when the result is removed from the cache

type Optional 

type Optional[I Input] struct {
	Value I
	// true if the value is set
	Valid bool
}

Optional wraps a type and allows it to be null.

This is used for optional arguments and return values.

func NoOpt 

func NoOpt[I Input]() Optional[I]

NoOpt returns an empty Optional value.

func Opt 

func Opt[I Input](v I) Optional[I]

func (Optional[I]) AsPtr added in v0.18.18 

func (n Optional[I]) AsPtr() *I

func (Optional[I]) DecodeInput 

func (o Optional[I]) DecodeInput(val any) (Input, error)

func (Optional[I]) Decoder 

func (o Optional[I]) Decoder() InputDecoder

func (Optional[I]) Deref 

func (o Optional[I]) Deref() (Typed, bool)

func (Optional[I]) GetOr 

func (n Optional[I]) GetOr(v I) I

GetOr returns the value of the Optional, or the given value if the Optional is empty.

func (Optional[I]) MarshalJSON 

func (o Optional[I]) MarshalJSON() ([]byte, error)

func (Optional[I]) SetField added in v0.18.18 

func (o Optional[I]) SetField(val reflect.Value) error

func (Optional[I]) ToLiteral 

func (o Optional[I]) ToLiteral() call.Literal

func (Optional[I]) ToNullable 

func (o Optional[I]) ToNullable() Nullable[I]

func (Optional[I]) Type 

func (o Optional[I]) Type() *ast.Type

func (*Optional[I]) UnmarshalJSON 

func (o *Optional[I]) UnmarshalJSON(p []byte) error

type PanicError added in v0.10.0 

type PanicError struct {
	Cause     any
	Self      AnyResult
	Selection Selection
	Stack     []byte
}

func (PanicError) Error added in v0.10.0 

func (err PanicError) Error() string

type PostCallable added in v0.16.2 

type PostCallable interface {
	// Return the postcall func (or nil if not set)
	GetPostCall() cache.PostCallFunc
}

PostCallable is a type that has a callback attached that needs to always run before returned to a caller whether or not the type is being returned from cache or not

type Result added in v0.18.13 

type Result[T Typed] struct {
	// contains filtered or unexported fields
}

func NewResultForCurrentID added in v0.18.13 

func NewResultForCurrentID[T Typed](
	ctx context.Context,
	self T,
) (Result[T], error)

NewResultForCurrentID creates a new Result that's set to the current ID from the given self value.

func NewResultForID added in v0.18.13 

func NewResultForID[T Typed](
	self T,
	id *call.ID,
) (res Result[T], _ error)

NewResultForID creates a new Result with the given ID and self value.

func (Result[T]) DerefValue added in v0.18.13 

func (r Result[T]) DerefValue() (AnyResult, bool)

func (Result[T]) GetPostCall added in v0.18.13 

func (r Result[T]) GetPostCall() cache.PostCallFunc

func (Result[T]) ID added in v0.18.13 

func (r Result[T]) ID() *call.ID

ID returns the ID of the instance.

func (Result[T]) MarshalJSON added in v0.18.13 

func (r Result[T]) MarshalJSON() ([]byte, error)

func (Result[T]) NthValue added in v0.18.13 

func (r Result[T]) NthValue(nth int) (AnyResult, error)

func (Result[T]) ResultWithPostCall added in v0.18.13 

func (r Result[T]) ResultWithPostCall(fn cache.PostCallFunc) Result[T]

func (Result[T]) Self added in v0.18.13 

func (r Result[T]) Self() T

func (Result[T]) SetField added in v0.18.13 

func (r Result[T]) SetField(field reflect.Value) error

func (Result[T]) String added in v0.18.13 

func (r Result[T]) String() string

String returns the instance in Class@sha256:... format.

func (Result[T]) Type added in v0.18.13 

func (o Result[T]) Type() *ast.Type

func (Result[T]) Unwrap added in v0.18.13 

func (r Result[T]) Unwrap() Typed

Unwrap returns the inner value of the instance.

func (Result[T]) WithDigest added in v0.18.13 

func (r Result[T]) WithDigest(customDigest digest.Digest) Result[T]

WithDigest returns an updated instance with the given metadata set. customDigest overrides the default digest of the instance to the provided value. NOTE: customDigest must be used with care as any instances with the same digest will be considered equivalent and can thus replace each other in the cache. Generally, customDigest should be used when there's a content-based digest available that won't be caputured by the default, call-chain derived digest.

func (Result[T]) WithPostCall added in v0.18.13 

func (r Result[T]) WithPostCall(fn cache.PostCallFunc) AnyResult

type ResultArray added in v0.18.13 

type ResultArray[T Typed] []Result[T]

func (ResultArray[T]) Element added in v0.18.13 

func (arr ResultArray[T]) Element() Typed

func (ResultArray[T]) Len added in v0.18.13 

func (arr ResultArray[T]) Len() int

func (ResultArray[T]) Nth added in v0.18.13 

func (arr ResultArray[T]) Nth(i int) (Typed, error)

func (ResultArray[T]) NthValue added in v0.18.13 

func (arr ResultArray[T]) NthValue(i int, enumID *call.ID) (AnyResult, error)

func (ResultArray[T]) Type added in v0.18.13 

func (i ResultArray[T]) Type() *ast.Type

type Scalar added in v0.11.3 

type Scalar[T ScalarValue] struct {
	Name  string
	Value T
}

Scalar is a GraphQL scalar.

func NewScalar added in v0.11.3 

func NewScalar[T ScalarValue](name string, val T) Scalar[T]

func (Scalar[T]) DecodeInput added in v0.11.3 

func (s Scalar[T]) DecodeInput(val any) (Input, error)

func (Scalar[T]) Decoder added in v0.11.3 

func (s Scalar[T]) Decoder() InputDecoder

func (Scalar[T]) MarshalJSON added in v0.11.3 

func (s Scalar[T]) MarshalJSON() ([]byte, error)

func (Scalar[T]) ToLiteral added in v0.11.3 

func (s Scalar[T]) ToLiteral() call.Literal

func (Scalar[T]) Type added in v0.11.3 

func (s Scalar[T]) Type() *ast.Type

func (Scalar[T]) TypeDefinition added in v0.11.3 

func (s Scalar[T]) TypeDefinition(view call.View) *ast.Definition

func (Scalar[T]) TypeName added in v0.11.3 

func (s Scalar[T]) TypeName() string

func (*Scalar[T]) UnmarshalJSON added in v0.11.3 

func (s *Scalar[T]) UnmarshalJSON(p []byte) error

type ScalarType 

type ScalarType interface {
	Type
	InputDecoder
}

ScalarType represents a GraphQL Scalar type.

type ScalarValue added in v0.11.3 

type ScalarValue interface {
	ScalarType
	Input
}

type Selection 

type Selection struct {
	Alias         string
	Selector      Selector
	Subselections []Selection
}

Selection represents a selection of a field on an object.

func (Selection) Name 

func (sel Selection) Name() string

Name returns the name of the selection, which is either the alias or the field name.

type Selector 

type Selector struct {
	Field string
	Args  []NamedInput
	Nth   int
	View  call.View
}

Selector specifies how to retrieve a value from an Result.

func (Selector) String 

func (sel Selector) String() string

type SerializedString added in v0.18.13 

type SerializedString[T any] struct {
	Self T
}

func NewSerializedString added in v0.18.13 

func NewSerializedString[T any](val T) SerializedString[T]

func (SerializedString[T]) DecodeInput added in v0.18.13 

func (SerializedString[T]) DecodeInput(val any) (Input, error)

func (SerializedString[T]) Decoder added in v0.18.13 

func (s SerializedString[T]) Decoder() InputDecoder

func (SerializedString[T]) MarshalJSON added in v0.18.13 

func (s SerializedString[T]) MarshalJSON() ([]byte, error)

func (SerializedString[T]) SetField added in v0.18.13 

func (s SerializedString[T]) SetField(v reflect.Value) error

func (SerializedString[T]) String added in v0.18.13 

func (s SerializedString[T]) String() string

func (SerializedString[T]) ToLiteral added in v0.18.13 

func (s SerializedString[T]) ToLiteral() call.Literal

func (SerializedString[T]) Type added in v0.18.13 

func (SerializedString[T]) Type() *ast.Type

func (*SerializedString[T]) UnmarshalJSON added in v0.18.13 

func (s *SerializedString[T]) UnmarshalJSON(p []byte) error

type Server 

type Server struct {

	// View is the default view that is applied to queries on this server.
	//
	// WARNING: this is *not* the view of the current query (for that, inspect
	// the current id)
	View call.View

	// Cache is the inner cache used by the server. It can be replicated to
	// another *Server to inherit and share caches.
	//
	// TODO: copy-on-write
	Cache *SessionCache
	// contains filtered or unexported fields
}

Server represents a GraphQL server whose schema is dynamically modified at runtime.

func CurrentDagqlServer added in v0.18.4 

func CurrentDagqlServer(ctx context.Context) *Server

func NewServer 

func NewServer[T Typed](root T, c *SessionCache) *Server

NewServer returns a new Server with the given root object.

func (*Server) AddInstallHook added in v0.17.0 

func (s *Server) AddInstallHook(hook InstallHook)

Attach an install hook

func (*Server) Around 

func (s *Server) Around(rec AroundFunc)

Around installs a function to be called around every non-cached selection.

func (*Server) AsSchema added in v0.18.13 

func (s *Server) AsSchema() *ServerSchema

func (*Server) Complexity 

func (s *Server) Complexity(ctx context.Context, typeName, field string, childComplexity int, args map[string]any) (int, bool)

Complexity returns the complexity of the given field.

func (*Server) Exec 

func (s *Server) Exec(ctx1 context.Context) graphql.ResponseHandler

Exec implements graphql.ExecutableSchema.

func (*Server) ExecOp 

func (s *Server) ExecOp(ctx context.Context, gqlOp *graphql.OperationContext) (map[string]any, error)

func (*Server) InstallDirective 

func (s *Server) InstallDirective(directive DirectiveSpec)

InstallDirective installs the given Directive type into the schema.

func (*Server) InstallObject 

func (s *Server) InstallObject(class ObjectType) ObjectType

InstallObject installs the given Object type into the schema, or returns the previously installed type if it was already present

func (*Server) InstallScalar 

func (s *Server) InstallScalar(scalar ScalarType) ScalarType

InstallScalar installs the given Scalar type into the schema, or returns the previously installed type if it was already present

func (*Server) InstallTypeDef 

func (s *Server) InstallTypeDef(def TypeDef)

InstallTypeDef installs an arbitrary type definition into the schema.

func (*Server) Load 

func (s *Server) Load(ctx context.Context, id *call.ID) (AnyObjectResult, error)

Load loads the object with the given ID.

func (*Server) LoadType added in v0.16.3 

func (s *Server) LoadType(ctx context.Context, id *call.ID) (AnyResult, error)

func (*Server) ObjectType 

func (s *Server) ObjectType(name string) (ObjectType, bool)

ObjectType returns the ObjectType with the given name, if it exists.

func (*Server) Query 

func (s *Server) Query(ctx context.Context, query string, vars map[string]any) (map[string]any, error)

Query is a convenience method for executing a query against the server without having to go through HTTP. This can be useful for introspection, for example.

func (*Server) Resolve 

func (s *Server) Resolve(ctx context.Context, self AnyObjectResult, sels ...Selection) (map[string]any, error)

Resolve resolves the given selections on the given object.

Each selection is resolved in parallel, and the results are returned in a map whose keys correspond to the selection's field name or alias.

func (*Server) Root 

func (s *Server) Root() AnyObjectResult

Root returns the root object of the server. It is suitable for passing to Resolve to resolve a query.

func (*Server) ScalarType 

func (s *Server) ScalarType(name string) (ScalarType, bool)

ScalarType returns the ScalarType with the given name, if it exists.

func (*Server) Schema 

func (s *Server) Schema() *ast.Schema

Schema returns the current schema of the server.

func (*Server) SchemaDigest added in v0.18.11 

func (s *Server) SchemaDigest() digest.Digest

SchemaDigest returns the digest of the current schema.

func (*Server) Select 

func (s *Server) Select(ctx context.Context, self AnyObjectResult, dest any, sels ...Selector) error

Select evaluates a series of chained field selections starting from the given object and assigns the final result value into dest.

func (*Server) TypeDef 

func (s *Server) TypeDef(name string) (TypeDef, bool)

InputType returns the InputType with the given name, if it exists.

func (*Server) WithCache added in v0.18.13 

func (s *Server) WithCache(c *SessionCache) *Server

type ServerSchema added in v0.18.13 

type ServerSchema struct {
	// contains filtered or unexported fields
}

func (*ServerSchema) View added in v0.18.13 

func (s *ServerSchema) View() call.View

func (*ServerSchema) WithCache added in v0.18.13 

func (s *ServerSchema) WithCache(c *SessionCache) *Server

type SessionCache added in v0.18.3 

type SessionCache struct {
	// contains filtered or unexported fields
}

func NewSessionCache added in v0.18.3 

func NewSessionCache(
	baseCache cache.Cache[CacheKeyType, CacheValueType],
) *SessionCache

func (*SessionCache) GetOrInitialize added in v0.18.3 

func (c *SessionCache) GetOrInitialize(
	ctx context.Context,
	key CacheKeyType,
	fn func(context.Context) (CacheValueType, error),
	opts ...CacheCallOpt,
) (CacheResult, error)

func (*SessionCache) GetOrInitializeValue added in v0.18.3 

func (c *SessionCache) GetOrInitializeValue(
	ctx context.Context,
	key CacheKeyType,
	val CacheValueType,
	opts ...CacheCallOpt,
) (CacheResult, error)

func (*SessionCache) GetOrInitializeWithCallbacks added in v0.18.3 

func (c *SessionCache) GetOrInitializeWithCallbacks(
	ctx context.Context,
	key CacheKeyType,
	skipDedupe bool,
	fn func(context.Context) (*CacheValWithCallbacks, error),
	opts ...CacheCallOpt,
) (res CacheResult, err error)

func (*SessionCache) ReleaseAndClose added in v0.18.13 

func (c *SessionCache) ReleaseAndClose(ctx context.Context) error

type Setter 

type Setter interface {
	SetField(reflect.Value) error
}

Setter allows a type to populate fields of a struct.

This is how builtins are supported.

type String 

type String string

String is a GraphQL String scalar.

func NewString 

func NewString(val string) String

func (String) DecodeInput 

func (String) DecodeInput(val any) (Input, error)

func (String) Decoder 

func (String) Decoder() InputDecoder

func (String) MarshalJSON 

func (s String) MarshalJSON() ([]byte, error)

func (String) SetField 

func (s String) SetField(v reflect.Value) error

func (String) String 

func (s String) String() string

func (String) ToLiteral 

func (s String) ToLiteral() call.Literal

func (String) Type 

func (String) Type() *ast.Type

func (String) TypeDefinition 

func (s String) TypeDefinition(view call.View) *ast.Definition

func (String) TypeName 

func (String) TypeName() string

func (*String) UnmarshalJSON 

func (s *String) UnmarshalJSON(p []byte) error

type TelemetryFunc added in v0.18.3 

type TelemetryFunc func(context.Context) (context.Context, func(AnyResult, bool, error))

type Type 

type Type interface {
	// TypeName returns the name of the type.
	TypeName() string
}

Type is an object that defines a new GraphQL type.

type TypeDef 

type TypeDef interface {
	Type
	Definitive
}

TypeDef is a type whose sole practical purpose is to define a GraphQL type, so it explicitly includes the Definitive interface.

type Typed 

type Typed interface {
	// Type returns the GraphQL type of the value.
	Type() *ast.Type
}

Typed is any value that knows its GraphQL type.

type ViewFilter added in v0.18.6 

type ViewFilter interface {
	Contains(call.View) bool
}
var GlobalView ViewFilter = nil

GlobalView is the default global view. Everyone can see it, and it behaves identically everywhere.

type Wrapper 

type Wrapper interface {
	Unwrap() Typed
}

Wrapper is an interface for types that wrap another type.

Source Files

View all Source files

Directories

Path Synopsis
callpbv1
Package idtui provides terminal user interface frontends for Dagger operations.
 Package idtui provides terminal user interface frontends for Dagger operations.
multiprefixw
internal
ioctx
Package ioctx provides a way to pass standard input, output, and error streams through a context.Context.
 Package ioctx provides a way to pass standard input, output, and error streams through a context.Context.
pipes
points

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.