query

Documentation

Overview

Package query provides support and utilities to handle and implement Domain Queries in your application.

Index

• type Envelope
  • func ToEnvelope[T Query](query T) Envelope[T]
• type Handler
• type HandlerFunc
  • func (f HandlerFunc[T, R]) Handle(ctx context.Context, query Envelope[T]) (R, error)
• type ProcessorHandler
• type Query
• type ScenarioGiven
  • func (sc ScenarioGiven[Q, R, T]) When(q Envelope[Q]) ScenarioWhen[Q, R, T]
• type ScenarioInit
  • func Scenario[Q Query, R any, T ProcessorHandler[Q, R]]() ScenarioInit[Q, R, T]
  • func (sc ScenarioInit[Q, R, T]) Given(events ...event.Persisted) ScenarioGiven[Q, R, T]
  • func (sc ScenarioInit[Q, R, T]) When(q Envelope[Q]) ScenarioWhen[Q, R, T]
• type ScenarioThen
  • func (sc ScenarioThen[Q, R, T]) AssertOn(t *testing.T, handlerFactory func(es event.Store) T)
• type ScenarioWhen
  • func (sc ScenarioWhen[Q, R, T]) Then(result R) ScenarioThen[Q, R, T]
  • func (sc ScenarioWhen[Q, R, T]) ThenError(err error) ScenarioThen[Q, R, T]
  • func (sc ScenarioWhen[Q, R, T]) ThenFails() ScenarioThen[Q, R, T]

Types

type Envelope

type Envelope[T Query] message.Envelope[T]

Envelope represents a message containing a Domain Query, and optionally includes additional fields in the form of Metadata.

func ToEnvelope

func ToEnvelope[T Query](query T) Envelope[T]

ToEnvelope is a convenience function that wraps the provided Query type into an Envelope, with no metadata attached to it.

type Handler

type Handler[T Query, R any] interface {
	Handle(ctx context.Context, query Envelope[T]) (R, error)
}

Handler is the interface that defines a Query Handler.

Handler accepts a specific kind of Query, evaluates it and returns the desired Result.

type HandlerFunc

type HandlerFunc[T Query, R any] func(ctx context.Context, query Envelope[T]) (R, error)

HandlerFunc is a functional type that implements the Handler interface. Useful for testing and stateless Handlers.

func (HandlerFunc[T, R]) Handle

func (f HandlerFunc[T, R]) Handle(ctx context.Context, query Envelope[T]) (R, error)

Handle implements xquery.Handler.

type ProcessorHandler

type ProcessorHandler[Q Query, R any] interface {
	Handler[Q, R]
	event.Processor
}

ProcessorHandler is a Query Handler that can both handle domain queries, and domain events to hydrate the query model.

To be used in the Scenario.

type Query

type Query message.Message

Query represents a Domain Query, a request for information. Queries should be phrased in the present, imperative tense, such as "ListUsers".

type ScenarioGiven

type ScenarioGiven[Q Query, R any, T ProcessorHandler[Q, R]] struct {
	// contains filtered or unexported fields
}

ScenarioGiven is the state of the scenario once a set of Domain Events have been provided using Given(), to represent the state of the system at the time of evaluating a Domain Event.

func (ScenarioGiven[Q, R, T]) When

func (sc ScenarioGiven[Q, R, T]) When(q Envelope[Q]) ScenarioWhen[Q, R, T]

When provides the Command to evaluate.

type ScenarioInit

type ScenarioInit[Q Query, R any, T ProcessorHandler[Q, R]] struct{}

ScenarioInit is the entrypoint of the Query Handler scenario API.

A Query Handler scenario can either set the current evaluation context by using Given(), or test a "clean-slate" scenario by using When() directly.

func Scenario

func Scenario[Q Query, R any, T ProcessorHandler[Q, R]]() ScenarioInit[Q, R, T]

Scenario can be used to test the result of Domain Queries being handled by a Query Handler.

Query Handlers in Event-sourced systems return read-only data on request by means of Domain Queries. This scenario API helps you with testing the values returned by a Query Handler when handling a specific Domain Query.

func (ScenarioInit[Q, R, T]) Given

func (sc ScenarioInit[Q, R, T]) Given(events ...event.Persisted) ScenarioGiven[Q, R, T]

Given sets the Query Handler scenario preconditions.

Domain Events are used in Event-sourced systems to represent a side effect that has taken place in the system. In order to set a given state for the system to be in while testing a specific Domain Query evaluation, you should specify the Domain Events that have happened thus far.

When you're testing Domain Queries with a clean-slate system, you should either specify no Domain Events, or skip directly to When().

func (ScenarioInit[Q, R, T]) When

func (sc ScenarioInit[Q, R, T]) When(q Envelope[Q]) ScenarioWhen[Q, R, T]

When provides the Domain Query to evaluate.

type ScenarioThen

type ScenarioThen[Q Query, R any, T ProcessorHandler[Q, R]] struct {
	ScenarioWhen[Q, R, T]
	// contains filtered or unexported fields
}

ScenarioThen is the state of the scenario once the preconditions and expectations have been fully specified.

func (ScenarioThen[Q, R, T]) AssertOn

func (sc ScenarioThen[Q, R, T]) AssertOn(
	t *testing.T,
	handlerFactory func(es event.Store) T,
)

AssertOn performs the specified expectations of the scenario, using the Query Handler instance produced by the provided factory function.

type ScenarioWhen

type ScenarioWhen[Q Query, R any, T ProcessorHandler[Q, R]] struct {
	ScenarioGiven[Q, R, T]
	// contains filtered or unexported fields
}

ScenarioWhen is the state of the scenario once the state of the system and the Domain Query to evaluate has been provided.

func (ScenarioWhen[Q, R, T]) Then

func (sc ScenarioWhen[Q, R, T]) Then(result R) ScenarioThen[Q, R, T]

Then sets a positive expectation on the scenario outcome, to produce the Query Result provided in input.

func (ScenarioWhen[Q, R, T]) ThenError

func (sc ScenarioWhen[Q, R, T]) ThenError(err error) ScenarioThen[Q, R, T]

ThenError sets a negative expectation on the scenario outcome, to produce an error value that is similar to the one provided in input.

Error assertion happens using errors.Is(), so the error returned by the Query Handler is unwrapped until the cause error to match the provided expectation.

func (ScenarioWhen[Q, R, T]) ThenFails

func (sc ScenarioWhen[Q, R, T]) ThenFails() ScenarioThen[Q, R, T]

ThenFails sets a negative expectation on the scenario outcome, to fail the Domain Query evaluation with no particular assertion on the error returned.

This is useful when the error returned is not important for the Domain Query you're trying to test.