dataloader

README

Go-Dataloader

A generic Go implementation of the DataLoader utility originally developed by Facebook.

Overview

This dataloader implementation efficiently loads data in batches, reducing the number of requests to your database or service. It supports:

• Generic types for keys and values
• Batching of requests
• Caching results
• Customizable options
• Built-in tracing for observability

Cache

The default cache is not functional. You can implement your own cache, but it must be thread-safe, like golang-lru, otherwise, it will panic.

Documentation

Index

• Constants
• Variables
• type Cache
• type DefaultCache
  • func (DefaultCache[KeyT, ValT]) Add(_ KeyT, _ ValT) bool
  • func (DefaultCache[KeyT, ValT]) Get(_ KeyT) (ValT, bool)
  • func (DefaultCache[KeyT, ValT]) Purge()
  • func (DefaultCache[KeyT, ValT]) Remove(_ KeyT) bool
• type DefaultTracer
  • func (DefaultTracer[KeyT, ValT]) TraceBatch(ctx context.Context, keys []Item[KeyT, ValT]) (context.Context, func())
• type ExecFunc
• type Item
• type Loader
  • func NewDataLoader[KeyT comparable, ValT any](execFn ExecFunc[KeyT, ValT], option ...Option[KeyT, ValT]) *Loader[KeyT, ValT]
  • func (l *Loader[KeyT, ValT]) Clear(key KeyT)
  • func (l *Loader[KeyT, ValT]) ClearAll()
  • func (l *Loader[KeyT, ValT]) LoadOrExec(ctx context.Context, key Item[KeyT, ValT]) func() Result[ValT]
• type LoaderInterface
• type Option
  • func WithCache[KeyT comparable, ValT any](cache Cache[KeyT, ValT]) Option[KeyT, ValT]
  • func WithMaxBatch[KeyT comparable, ValT any](maxBatch int) Option[KeyT, ValT]
  • func WithTracer[KeyT comparable, ValT any](tracer Tracer[KeyT, ValT]) Option[KeyT, ValT]
  • func WithWait[KeyT comparable, ValT any](wait time.Duration) Option[KeyT, ValT]
• type Options
• type Result
• type Tracer

Constants

const (
	DEFAULT_WAIT     time.Duration = 30 * time.Millisecond
	DEFAULT_MAXBATCH int           = 200
)

Variables

var (
	ErrKeyNotFound        = errors.New("key not found")
	ErrPanicBatch         = errors.New("panic received in batch")
	ErrPanicAddValInCache = errors.New("panic received in add value in cache")
)

Types

type Cache

type Cache[KeyT comparable, ValT any] interface {
	// Get returns the value stored in the cache and a boolean indicating if the value was found
	Get(key KeyT) (value ValT, ok bool)
	// Add adds a value to the cache and returns a boolean indicating if the value was evicted
	Add(key KeyT, value ValT) (evicted bool)
	// Remove removes a value from the cache and returns a boolean indicating if the value was found
	Remove(key KeyT) bool
	// Purge removes all values from the cache
	Purge()
}

type DefaultCache

type DefaultCache[KeyT comparable, ValT any] struct{}

DefaultCache is a cache that does not store any values

func (DefaultCache[KeyT, ValT]) Add

func (DefaultCache[KeyT, ValT]) Add(_ KeyT, _ ValT) bool

func (DefaultCache[KeyT, ValT]) Get

func (DefaultCache[KeyT, ValT]) Get(_ KeyT) (ValT, bool)

func (DefaultCache[KeyT, ValT]) Purge

func (DefaultCache[KeyT, ValT]) Purge()

func (DefaultCache[KeyT, ValT]) Remove

func (DefaultCache[KeyT, ValT]) Remove(_ KeyT) bool

type DefaultTracer

type DefaultTracer[KeyT comparable, ValT any] struct{}

DefaultTracer is a tracer that does nothing

func (DefaultTracer[KeyT, ValT]) TraceBatch

func (DefaultTracer[KeyT, ValT]) TraceBatch(
	ctx context.Context, keys []Item[KeyT, ValT]) (
	context.Context, func())

type ExecFunc

type ExecFunc[KeyT comparable, ValT any] func(
	ctx context.Context, data []Item[KeyT, ValT]) (
	map[KeyT]ValT, map[KeyT]error)

ExecFunc is a function that receives a context and a slice of items, and returns a map of values and a map of errors.

type Item

type Item[KeyT comparable, ValT any] struct {
	Key KeyT
	Val ValT
}

Item is a struct that contains a key-value pair.

type Loader

type Loader[KeyT comparable, ValT any] struct {
	*Options[KeyT, ValT]
	// contains filtered or unexported fields
}

Loader is a struct that contains the options and the batcher.

func NewDataLoader

func NewDataLoader[KeyT comparable, ValT any](
	execFn ExecFunc[KeyT, ValT], option ...Option[KeyT, ValT]) *Loader[KeyT, ValT]

NewDataLoader creates a new instance of Loader

func (*Loader[KeyT, ValT]) Clear

func (l *Loader[KeyT, ValT]) Clear(key KeyT)

func (*Loader[KeyT, ValT]) ClearAll

func (l *Loader[KeyT, ValT]) ClearAll()

func (*Loader[KeyT, ValT]) LoadOrExec

func (l *Loader[KeyT, ValT]) LoadOrExec(ctx context.Context,
	key Item[KeyT, ValT]) func() Result[ValT]

type LoaderInterface

type LoaderInterface[KeyT comparable, ValT any] interface {
	// LoadOrExec loads or executes data depending on the ExecFunc function,
	// it returns a function that returns the result of the operation
	LoadOrExec(ctx context.Context, data Item[KeyT, ValT]) func() Result[ValT]
	// Clear clears a key from the cache
	Clear(key KeyT)
	// ClearAll clears all keys from the cache
	ClearAll()
}

type Option

type Option[KeyT comparable, ValT any] func(*Options[KeyT, ValT])

Option is a function that can be used to set options on a Loader

func WithCache

func WithCache[KeyT comparable, ValT any](cache Cache[KeyT, ValT]) Option[KeyT, ValT]

WithCache sets the cache for the loader

func WithMaxBatch

func WithMaxBatch[KeyT comparable, ValT any](maxBatch int) Option[KeyT, ValT]

WithMaxBatch sets the maximum number of keys to send in one batch

func WithTracer

func WithTracer[KeyT comparable, ValT any](tracer Tracer[KeyT, ValT]) Option[KeyT, ValT]

WithTracer sets the tracer for the loader

func WithWait

func WithWait[KeyT comparable, ValT any](wait time.Duration) Option[KeyT, ValT]

WithWait sets the wait time for the loader

type Options

type Options[KeyT comparable, ValT any] struct {
	// contains filtered or unexported fields
}

type Result

type Result[ValT any] struct {
	Val ValT
	Err error
}

Result is a struct that contains the result of a function.

type Tracer

type Tracer[KeyT comparable, ValT any] interface {
	// TraceBatch is called before a batch is executed
	TraceBatch(ctx context.Context, keys []Item[KeyT, ValT]) (context.Context, func())
}