Documentation
¶
Overview ¶
Package iterators provide iterator implementations.
Summary ¶
An iterator goal is to decouple the facts about the origin of the data, to the consumer who use the data. Most common scenario is to hide the fact if data is from a Certain DB, STDIN or from somewhere else. This helps to design data consumers that doesn't rely on the data source concrete implementation, while still able to do composition and different kind of actions on the received data stream. An Interface represent multiple data that can be 0 and infinite. As a general rule of thumb, if the consumer is not the final destination of the data stream, the consumer should use the pipeline pattern, in order to avoid bottleneck with local resources.
frameless.Iterator define a separate object that encapsulates accessing and traversing an aggregate object. Clients use an iterator to access and traverse an aggregate without knowing its representation (data structures). frameless.Iterator design inspirited by https://golang.org/pkg/encoding/json/#Decoder
Why an Object with empty interface instead of type safe channels to represent streams ¶
There are multiple approach to the same problem, and I only prefer this approach, because the error handling is easier trough this. In channel based pipeline pattern, you have to make sure that the information about the error is passed trough either trough some kind of separate error channel, or trough the message object it self that being passed around. If the pipeline can be composited during a certain use case, you can pass around a context.Context object to represent this. In the case of Interface pattern, this failure communicated during the individual iteration, which leaves it up to you to propagate the error forward, or handle at the place.
Resources ¶
https://en.wikipedia.org/wiki/Iterator_pattern https://en.wikipedia.org/wiki/Pipeline_(software)
Index ¶
- Constants
- func Collect[T any](i Iterator[T]) (vs []T, err error)
- func Count[T any](i Iterator[T]) (total int, err error)
- func First[T any](i Iterator[T]) (value T, found bool, err error)
- func ForEach[T any](i Iterator[T], fn func(T) error) (rErr error)
- func Last[T any](i Iterator[T]) (value T, found bool, err error)
- func Pipe[T any]() (*PipeIn[T], *PipeOut[T])
- func Reduce[T, Result any, BLK ...](i Iterator[T], initial Result, blk BLK) (rv Result, rErr error)
- type BatchConfig
- type BatchIter
- type Callback
- type CallbackIterator
- type ConcurrentAccessIterator
- type EmptyIter
- type Encoder
- type EncoderFunc
- type ErrorIter
- type FilterIter
- type FuncIter
- type ISQLRows
- type Iterator
- type MapIter
- type MapTransformFunc
- type PipeIn
- type PipeOut
- type SQLRowMapper
- type SQLRowMapperFunc
- type SQLRowScanner
- type SQLRowsIter
- type ScannerIter
- type SingleValueIter
- type SliceIter
- type StubIter
Examples ¶
Constants ¶
const Break errutils.Error = `iterators:break`
const ( // ErrClosed is the value that will be returned if a iterator has been closed but next decode is called ErrClosed errutils.Error = "Closed" )
Variables ¶
This section is empty.
Functions ¶
func Count ¶
Count will iterate over and count the total iterations number
Good when all you want is count all the elements in an iterator but don't want to do anything else.
func Pipe ¶
Pipe return a receiver and a sender. This can be used with resources that
Example ¶
package main
import (
"github.com/adamluzsi/frameless/ports/iterators"
)
func main() {
var (
i *iterators.PipeIn[int]
o *iterators.PipeOut[int]
)
i, o = iterators.Pipe[int]()
_ = i // use it to send values
_ = o // use it to consume values on each iteration (iter.Next())
}
Output:
Types ¶
type BatchConfig ¶
type BatchConfig struct {
// Size is the max amount of element that a batch will contains.
// Default batch Size is 100.
Size int
// Timeout is batching wait timout duration that the batching process is willing to wait for, before starting to build a new batch.
// Default batch Timeout is 100 Millisecond.
Timeout time.Duration
}
type BatchIter ¶
type BatchIter[T any] struct { Iterator Iterator[T] Config BatchConfig // contains filtered or unexported fields }
type CallbackIterator ¶
func (*CallbackIterator[T]) Close ¶
func (i *CallbackIterator[T]) Close() error
type ConcurrentAccessIterator ¶
type ConcurrentAccessIterator[T any] struct { Iterator[T] // contains filtered or unexported fields }
func WithConcurrentAccess ¶
func WithConcurrentAccess[T any](i Iterator[T]) *ConcurrentAccessIterator[T]
WithConcurrentAccess allows you to convert any iterator into one that is safe to use from concurrent access. The caveat with this is that this protection only allows 1 Decode call for each Next call.
func (*ConcurrentAccessIterator[T]) Next ¶
func (i *ConcurrentAccessIterator[T]) Next() bool
func (*ConcurrentAccessIterator[T]) Value ¶
func (i *ConcurrentAccessIterator[T]) Value() T
type EmptyIter ¶
type EmptyIter[T any] struct{}
EmptyIter iterator can help achieve Null Object Pattern when no value is logically expected and iterator should be returned
type Encoder ¶
type Encoder interface {
//
// Encode encode a simple message back to the wrapped communication channel
// message is an interface type because the channel communication layer and content and the serialization is up to the Encoder to implement
//
// If the message is a complex type that has multiple fields,
// an exported struct that represent the content must be declared at the controller level
// and all the presenters must based on that input for they test
Encode(interface{}) error
}
Encoder is a scope isolation boundary. One use-case for this is for example the Presenter object that encapsulate the external resource presentation mechanism from it's user.
Scope:
receive Entities, that will be used by the creator of the Encoder
type EncoderFunc ¶
type EncoderFunc func(interface{}) error
EncoderFunc is a wrapper to convert standalone functions into a presenter
func (EncoderFunc) Encode ¶
func (lambda EncoderFunc) Encode(i interface{}) error
Encode implements the Encoder Interface
type ErrorIter ¶
type ErrorIter[T any] struct { // contains filtered or unexported fields }
ErrorIter iterator can be used for returning an error wrapped with iterator interface. This can be used when external resource encounter unexpected non recoverable error during query execution.
type FilterIter ¶
type FilterIter[T any] struct { Iterator Iterator[T] Filter func(T) bool // contains filtered or unexported fields }
func Filter ¶
func Filter[T any](i Iterator[T], filter func(T) bool) *FilterIter[T]
Example ¶
package main
import (
"log"
"github.com/adamluzsi/frameless/ports/iterators"
)
func main() {
var iter iterators.Iterator[int]
iter = iterators.Slice([]int{0, 1, 2, 3, 4, 5, 6, 7, 8, 9})
iter = iterators.Filter[int](iter, func(n int) bool { return n > 2 })
defer iter.Close()
for iter.Next() {
n := iter.Value()
_ = n
}
if err := iter.Err(); err != nil {
log.Fatal(err)
}
}
Output:
func (*FilterIter[T]) Close ¶
func (i *FilterIter[T]) Close() error
func (*FilterIter[T]) Err ¶
func (i *FilterIter[T]) Err() error
func (*FilterIter[T]) Next ¶
func (i *FilterIter[T]) Next() bool
func (*FilterIter[T]) Value ¶
func (i *FilterIter[T]) Value() T
type FuncIter ¶
type Iterator ¶
type Iterator[V any] interface { // Closer is required to make it able to cancel iterators where resources are being used behind the scene // for all other cases where the underling io is handled on a higher level, it should simply return nil io.Closer // Err return the error cause. Err() error // Next will ensure that Value returns the next item when executed. // If the next value is not retrievable, Next should return false and ensure Err() will return the error cause. Next() bool // Value returns the current value in the iterator. // The action should be repeatable without side effects. Value() V }
Iterator define a separate object that encapsulates accessing and traversing an aggregate object. Clients use an iterator to access and traverse an aggregate without knowing its representation (data structures). Interface design inspirited by https://golang.org/pkg/encoding/json/#Decoder https://en.wikipedia.org/wiki/Iterator_pattern
Example ¶
package main
import (
"github.com/adamluzsi/frameless/ports/iterators"
)
func main() {
var iter iterators.Iterator[int]
defer iter.Close()
for iter.Next() {
v := iter.Value()
_ = v
}
if err := iter.Err(); err != nil {
// handle error
}
}
Output:
type MapIter ¶
type MapIter[T any, V any] struct { Iterator Iterator[T] Transform MapTransformFunc[T, V] // contains filtered or unexported fields }
func Map ¶
func Map[T any, V any](iter Iterator[T], transform MapTransformFunc[T, V]) *MapIter[T, V]
Map allows you to do additional transformation on the values. This is useful in cases, where you have to alter the input value, or change the type all together. Like when you read lines from an input stream, and then you map the line content to a certain data structure, in order to not expose what steps needed in order to deserialize the input stream, thus protect the business rules from this information.
type MapTransformFunc ¶
type PipeIn ¶
type PipeIn[T any] struct { // contains filtered or unexported fields }
PipeIn provides access to feed a pipe receiver with entities
func (*PipeIn[T]) Close ¶
Close will close the feed and err channels, which eventually notify the receiver that no more value expected
type PipeOut ¶
type PipeOut[T any] struct { // contains filtered or unexported fields }
PipeOut implements iterator interface while it's still being able to receive values, used for streaming
func (*PipeOut[T]) Close ¶
Close sends a signal back that no more value should be sent because receiver stop listening
func (*PipeOut[T]) Err ¶
Err returns an error object that the pipe sender want to present for the pipe receiver
type SQLRowMapper ¶
type SQLRowMapper[T any] interface { Map(s SQLRowScanner) (T, error) }
type SQLRowMapperFunc ¶
type SQLRowMapperFunc[T any] func(SQLRowScanner) (T, error)
func (SQLRowMapperFunc[T]) Map ¶
func (fn SQLRowMapperFunc[T]) Map(s SQLRowScanner) (T, error)
type SQLRowScanner ¶
type SQLRowScanner interface {
Scan(...interface{}) error
}
type SQLRowsIter ¶
type SQLRowsIter[T any] struct { Rows ISQLRows Mapper SQLRowMapper[T] // contains filtered or unexported fields }
SQLRowsIter allow you to use the same iterator pattern with sql.Rows structure. it allows you to do dynamic filtering, pipeline/middleware pattern on your sql results by using this wrapping around it. it also makes testing easier with the same Interface interface.
func SQLRows ¶
func SQLRows[T any](rows ISQLRows, mapper SQLRowMapper[T]) *SQLRowsIter[T]
func (*SQLRowsIter[T]) Close ¶
func (i *SQLRowsIter[T]) Close() error
func (*SQLRowsIter[T]) Err ¶
func (i *SQLRowsIter[T]) Err() error
func (*SQLRowsIter[T]) Next ¶
func (i *SQLRowsIter[T]) Next() bool
func (*SQLRowsIter[T]) Value ¶
func (i *SQLRowsIter[T]) Value() T
type ScannerIter ¶
type ScannerIter[T string | []byte] struct { *bufio.Scanner Closer io.Closer // contains filtered or unexported fields }
func (*ScannerIter[T]) Close ¶
func (i *ScannerIter[T]) Close() error
func (*ScannerIter[T]) Err ¶
func (i *ScannerIter[T]) Err() error
func (*ScannerIter[T]) Next ¶
func (i *ScannerIter[T]) Next() bool
func (*ScannerIter[T]) Value ¶
func (i *ScannerIter[T]) Value() T
type SingleValueIter ¶
type SingleValueIter[T any] struct { V T // contains filtered or unexported fields }
func SingleValue ¶
func SingleValue[T any](v T) *SingleValueIter[T]
SingleValue creates an iterator that can return one single element and will ensure that Next can only be called once.
func (*SingleValueIter[T]) Close ¶
func (i *SingleValueIter[T]) Close() error
func (*SingleValueIter[T]) Err ¶
func (i *SingleValueIter[T]) Err() error
func (*SingleValueIter[T]) Next ¶
func (i *SingleValueIter[T]) Next() bool
func (*SingleValueIter[T]) Value ¶
func (i *SingleValueIter[T]) Value() T
type SliceIter ¶
type SliceIter[T any] struct { Slice []T // contains filtered or unexported fields }
Source Files