Documentation
¶
Overview ¶
Package converter wraps value conversions with lifecycle metrics, tracing, logging, and completion callbacks.
Stages call converters concurrently for individual items, so converter implementations, conversion functions, and callbacks must be safe for concurrent use.
Index ¶
- Constants
- type Convert
- type Converter
- func (c *Converter[In, Out]) GetCounterCreated() *expvar.Int
- func (c *Converter[In, Out]) GetCounterDone() *expvar.Int
- func (c *Converter[In, Out]) GetCounterFailed() *expvar.Int
- func (c *Converter[In, Out]) GetCounterRunning() *expvar.Int
- func (c *Converter[In, Out]) GetCreatedAt() time.Time
- func (c *Converter[In, Out]) GetDescription() string
- func (c *Converter[In, Out]) GetDuration() *expvar.Int
- func (c *Converter[In, Out]) GetLogger() sypl.ISypl
- func (c *Converter[In, Out]) GetMetrics() map[string]string
- func (c *Converter[In, Out]) GetName() string
- func (c *Converter[In, Out]) GetOnFinished() OnFinished[In, Out]
- func (c *Converter[In, Out]) GetStatus() *expvar.String
- func (c *Converter[In, Out]) GetType() string
- func (c *Converter[In, Out]) Run(ctx context.Context, in In) (Out, error)
- func (c *Converter[In, Out]) SetOnFinished(onFinished OnFinished[In, Out])
- type Func
- type IConverter
- func Default[In, Out any](fn Convert[In, Out], opts ...Func[In, Out]) (IConverter[In, Out], error)
- func MustDefault[In, Out any](fn Convert[In, Out], opts ...Func[In, Out]) IConverter[In, Out]
- func New[In, Out any](name, description string, fn Convert[In, Out], opts ...Func[In, Out]) (IConverter[In, Out], error)
- type OnFinished
Examples ¶
Constants ¶
const Type = "converter"
Type identifies converter entities.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Convert ¶
Convert converts `in`, returning the converted data and any error. It must be safe for concurrent use because stages invoke it from multiple goroutines.
type Converter ¶
type Converter[In, Out any] struct { // Description describes the converter. Description string `json:"description"` // Func converts one input and must be safe for concurrent use. Func Convert[In, Out] `json:"-" validate:"required"` // Logger records converter lifecycle events. Logger sypl.ISypl `json:"-" validate:"required"` // Name identifies the converter. Name string `json:"name" validate:"required"` // Lifecycle metrics. CounterCreated *expvar.Int `json:"counterCreated"` CounterRunning *expvar.Int `json:"counterRunning"` CounterFailed *expvar.Int `json:"counterFailed"` CounterDone *expvar.Int `json:"counterDone"` CreatedAt time.Time `json:"createdAt"` Duration *expvar.Int `json:"duration"` Status *expvar.String `json:"status"` // contains filtered or unexported fields }
Converter wraps a conversion function with lifecycle observability.
func (*Converter[In, Out]) GetCounterCreated ¶
GetCounterCreated returns the converter's created counter.
func (*Converter[In, Out]) GetCounterDone ¶
GetCounterDone returns the converter's done counter.
func (*Converter[In, Out]) GetCounterFailed ¶
GetCounterFailed returns the converter's failed counter.
func (*Converter[In, Out]) GetCounterRunning ¶
GetCounterRunning returns the converter's running counter.
func (*Converter[In, Out]) GetCreatedAt ¶
GetCreatedAt returns when the converter was constructed.
func (*Converter[In, Out]) GetDescription ¶
GetDescription returns the converter's description.
func (*Converter[In, Out]) GetDuration ¶
GetDuration returns the most recent successful conversion duration in milliseconds. A failed conversion does not replace it.
func (*Converter[In, Out]) GetMetrics ¶
GetMetrics returns a snapshot of the converter's metrics as strings.
func (*Converter[In, Out]) GetOnFinished ¶
func (c *Converter[In, Out]) GetOnFinished() OnFinished[In, Out]
GetOnFinished returns the `OnFinished` function.
func (*Converter[In, Out]) Run ¶
Run converts one value and updates lifecycle observability. It may be called concurrently; Func and OnFinished callbacks must therefore be concurrency safe.
func (*Converter[In, Out]) SetOnFinished ¶
func (c *Converter[In, Out]) SetOnFinished(onFinished OnFinished[In, Out])
SetOnFinished sets the `OnFinished` function.
type Func ¶
type Func[In, Out any] func(p IConverter[In, Out]) IConverter[In, Out]
Func configures a converter and returns the implementation to retain. An option must return a usable implementation; returning one whose embedded interface is nil will panic when it is used, as it would anywhere in Go.
func WithOnFinished ¶
func WithOnFinished[In, Out any](onFinished OnFinished[In, Out]) Func[In, Out]
WithOnFinished returns a Func that sets the completion callback.
type IConverter ¶
type IConverter[In, Out any] interface { shared.IMeta shared.IMetrics // GetOnFinished returns the `OnFinished` function. GetOnFinished() OnFinished[In, Out] // SetOnFinished sets the `OnFinished` function. SetOnFinished(onFinished OnFinished[In, Out]) // Run converts one input value. Run(ctx context.Context, in In) (Out, error) }
IConverter defines converter lifecycle, metrics, and execution. Implementations must be safe for concurrent use because stages call Run from multiple goroutines.
func Default ¶
func Default[In, Out any]( fn Convert[In, Out], opts ...Func[In, Out], ) (IConverter[In, Out], error)
Default creates a converter whose name and description are Type.
func MustDefault ¶
func MustDefault[In, Out any]( fn Convert[In, Out], opts ...Func[In, Out], ) IConverter[In, Out]
MustDefault creates a default converter or panics if validation fails.
func New ¶
func New[In, Out any]( name, description string, fn Convert[In, Out], opts ...Func[In, Out], ) (IConverter[In, Out], error)
New creates a converter. It applies options in order, retains each returned implementation, and then validates the result. Nil options and results are rejected. An option must return a usable implementation; returning one whose embedded interface is nil will panic when it is used, as it would anywhere in Go. Structural validation runs before lifecycle metric getters; the final implementation must expose non-nil lifecycle metrics. fn must be safe for concurrent use.
Example ¶
Demonstrates a converter that changes a value's type.
type person struct {
Name string
Age int
}
format, err := New(
"example-person-string",
"formats a person as text",
func(_ context.Context, in person) (string, error) {
return fmt.Sprintf("%s (%d)", in.Name, in.Age), nil
},
)
if err != nil {
log.Fatalln(err)
}
out, err := format.Run(context.Background(), person{Name: "Ada", Age: 37})
if err != nil {
log.Fatalln(err)
}
fmt.Println(out)
Output: Ada (37)
type OnFinished ¶
type OnFinished[In, Out any] func(ctx context.Context, c IConverter[In, Out], originalIn In, convertedOut Out)
OnFinished runs after a conversion succeeds. It may be called concurrently.