dynamobind

func ClientFromContext ¶ added in v0.2.10

func ClientFromContext(ctx context.Context) (*dynamodb.Client, error)

ClientFromContext returns the client installed by WithClient.

It is the escape hatch for reaching the driver directly, for an operation this package does not wrap. Everything this package does wrap resolves through TableFromContext instead, so the name mapping is applied.

func Load ¶

func Load[T any, PT interface {
	*T
	ItemDecoder
}](ctx context.Context, table string, key dynamodb.Key, opts ...dynamodb.GetOption) (T, error)

Load reads one item by key and decodes it into T.

A key that matches nothing keeps the driver's dynamodb.ErrItemNotFound rather than returning a zero value, so a miss cannot be mistaken for an empty item.

func LoadAll ¶

func LoadAll[T any, PT interface {
	*T
	ItemDecoder
}](ctx context.Context, table string, keys []dynamodb.Key, opts ...dynamodb.BatchOption) ([]T, []dynamodb.Key, error)

LoadAll reads every key, splitting the input into requests of at most MaxBatchGet keys.

DynamoDB does not promise to return batch items in request order, and a key that matches nothing is simply absent rather than an error, so len(items) can be smaller than len(keys) with no error and no unprocessed key. Keys DynamoDB declined to read come back in unprocessed, unretried.

func Query ¶

func Query[T any, PT interface {
	*T
	ItemDecoder
}](ctx context.Context, table, keyCond string, opts ...dynamodb.QueryOption) iter.Seq2[T, error]

Query iterates every item of a query, requesting pages as the range advances.

One range can issue many requests. The iterator reports no page boundary, no Count, no ScannedCount, and no final LastEvaluatedKey, so a query that scans far more than it returns looks the same as one that does not, and an interrupted run cannot be resumed. Use QueryPage when any of that matters.

Iteration stops at the first error, which is yielded once with the zero value of T. A break stops it without issuing a further request.

func Remove ¶

func Remove[T Keyer](ctx context.Context, table string, v T, opts ...dynamodb.WriteOption) error

Remove deletes the item identified by v's key. Only the key of v is read.

func RemoveReturning ¶

func RemoveReturning[T Keyer, PT interface {
	*T
	ItemDecoder
}](ctx context.Context, table string, v T, opts ...dynamodb.WriteOption) (T, bool, error)

RemoveReturning is Remove, and also decodes the item it deleted.

The bool is false when the key held no item, which is not an error.

func Scan ¶

func Scan[T any, PT interface {
	*T
	ItemDecoder
}](ctx context.Context, table string, opts ...dynamodb.ScanOption) iter.Seq2[T, error]

Scan iterates every item of a table or index scan.

An unfiltered scan walks the whole table, one page per request. Everything said about Query's hidden request count applies here and costs more.

func Store ¶

func Store[T ItemEncoder](ctx context.Context, table string, v T, opts ...dynamodb.WriteOption) error

Store writes v as a whole item, replacing any item with the same key.

It is PutItem, not a partial update: every attribute of the stored item comes from v. Use Update for a partial change.

func StoreAll ¶

func StoreAll[T ItemEncoder](ctx context.Context, table string, vs []T) ([]T, error)

StoreAll writes every value, splitting the input into requests of at most MaxBatchWrite items.

What DynamoDB declined comes back in unprocessed, unretried: the driver already retries the transport, and whether a partial success is worth a second attempt is the caller's decision, not this package's. Passing unprocessed back to StoreAll is the retry, and it belongs in caller code where a backoff can live.

func StoreReturning ¶

func StoreReturning[T ItemEncoder, PT interface {
	*T
	ItemDecoder
}](ctx context.Context, table string, v T, opts ...dynamodb.WriteOption) (T, bool, error)

StoreReturning is Store, and also decodes the item it replaced.

The bool is false when the key held no item, which is not an error. It asks the driver for ALL_OLD, so it costs a write capacity unit more than Store on a table that charges for it.

func TableFromContext ¶ added in v0.2.10

func TableFromContext(ctx context.Context, table string) (*dynamodb.Client, string, error)

TableFromContext resolves a declared table name into the client and the name to send. Every Context-resolving entry of this package calls it.

func TypeError ¶

func TypeError(attribute, expected string, got dynamodb.AttributeValue) error

TypeError reports an attribute whose stored kind is not the one the field needs. Generated decoders call it.

func Update ¶

func Update[T Keyer](ctx context.Context, table string, v T, update string, opts ...dynamodb.WriteOption) error

Update applies a DynamoDB update expression to the item identified by v's key.

The expression is passed to the driver verbatim; nothing here generates or validates it. Only the key is typed, which is the part a struct tag can actually supply. Attribute values in the expression come from dynamodb.WithExpressionValues as usual:

err := dynamobind.Update(ctx, "readings", key, "SET celsius = :c",
	dynamodb.WithExpressionValues(map[string]dynamodb.AttributeValue{":c": dynamodb.N(21.5)}))

func ValueError ¶

func ValueError(attribute, message string, cause error) error

ValueError reports an attribute whose kind is right but whose value cannot be represented by the field, such as a number too large for the Go type. Generated decoders call it.

func WithClient ¶ added in v0.2.10

func WithClient(ctx context.Context, c *dynamodb.Client, options ...ClientOption) context.Context

WithClient returns a child Context carrying a DynamoDB client and, with WithTableNames, how its tables are named. Framework middleware installs it once, and every entry of this package resolves it.

func WithHandle ¶ added in v0.3.7

func WithHandle(ctx context.Context, h Handle) context.Context

WithHandle returns a child Context carrying an already-built Handle.

It is WithClient for a caller that holds a Handle: a framework resolving one out of its own Context value, or a setup path that builds the Handle once and installs it in several Contexts.