Namespace DynaSharp

Classes

AccessDeniedException

The credentials are valid but lack permission for the operation. Not retried: grant the IAM action, such as dynamodb:PutItem on the table.

AttrExtensions

What a handle can do depending on the type of its attribute.

AwsRegion

An AWS region, such as eu-central-2, and the DynamoDB and DynamoDB Streams endpoints that serve it.

BatchGetIncompleteException<T>

A batch get ended with keys left that DynamoDB did not answer. Items holds what was read and UnprocessedKeys the rest.

BatchIncompleteException

A batch write ended with writes left. A batch is not atomic, so the writes that were taken stay applied: Written says how many and UnprocessedItems holds the rest.

CancellationReason

Why one action of a cancelled transaction did not take effect, reported by CancellationReasons.

CapacityDetail

The capacity units consumed on a table or an index, as part of ConsumedCapacity.

Condition

A condition that can be kept in a field, assembled at run time and combined with &, | and !: Condition.Of(Attr("status").Eq("open")).

ConditionExtensions

Combines conditions: Attr("a").Eq(1).And(Attr("b").Gt(2)), .Or(...) and .Negate().

ConditionalCheckFailedException

The condition expression of a write did not hold, so nothing was written. Not retried by the client, because the same request meets the same condition. Code that reads again and decides again can run in RetryOnConflictAsync<TResult>(Func<CancellationToken, ValueTask<TResult>>, CancellationToken), which repeats it for you. Key says which item it was about.

ConsumedCapacity

The capacity units an operation consumed, reported when the request asked for it with Total or Indexes.

ContinuationTokenSigner

The keys that sign and check the ContinuationToken of the paged reads of a client, so that a client of a web API can no longer pick its position: a token it made up or edited, or one of another query, fails before a request goes out. Set it as TokenSigner. Every instance of a service that hands out tokens and takes them back holds the same keys, as it would for cookies.

CreateTableCommand

Creates a table from what its entities declare: await orders.CreateTable().Including<Customer>().Including<Product>().SendAsync(ct);. CreateTable() starts one.

CreateTableResult

What a CreateTableCommand returns: the table, and what this call changed about it. A program that creates its table at every start learns here whether this start created it or turned time to live on, for a log line or a metric, without a call of its own.

CredentialsUnavailableException

Thrown when a credentials provider cannot find or obtain credentials.

DynamoDbClient

The client for Amazon DynamoDB: it owns the resolved configuration, the credentials and the HTTP connections that every request of the library runs on. The way in is Table<T>() for an entity that declares its table, Table<T>(string) to name it, and Table(string, string, string?) for a table without a model.

DynamoDbClientOptions

Configures a DynamoDbClient or a DynamoDbStreamsClient. Every setting is optional; unset settings are resolved from the environment the same way the AWS SDKs do.

DynamoDbException

An error returned by DynamoDB. Specific errors have derived types; all others surface as this type with their ErrorCode. IsTransient says whether trying again later can help.

DynamoDbMappingException

An item cannot be mapped to its .NET type: an attribute is missing, has a value the type cannot hold, or the item is of another type. The service did what it was asked, so this is never retried. In particular, an UpdateItem whose returned attribute is missing has been applied.

EntityTableExtensions

The verbs of a table or index of an entity that take what the entity builds: a partition key of Keys for a query, the entity itself for a get or a delete, and an index by the name the entity declares. These are extension methods because they depend on the type of the table: a table without a schema takes such a key too, for a mixed read.

EntityWriteExtensions

The clauses of a write of an entity that its write rules ask for: IfVersion and IgnoreVersion for an entity with a VersionAttribute, and StoreKeyInputs for an update that may create the item. These are extension methods so that a write of a table without a schema, which has neither, does not offer them.

ExpiredIteratorException

A shard iterator is older than the 15 minutes it is valid for. DynamoDB Streams reports it as ExpiredIteratorException.

Expr

The vocabulary of expressions without a schema, for using static DynaSharp.Expr;: Attr("status") and Attr<int>("orderCount"). Struct conditions cover comparisons, existence and begins_with, and an interpolated expression covers the rest of the grammar: $"size({Attr("tags")}) < {10}".

GuidExtensions

The bounds of the version-7 Guid values of one millisecond, for a range of time over a key of CreateVersion7(DateTimeOffset) ids.

IdempotentParameterMismatchException

A transaction was sent with a ClientRequestToken that DynamoDB saw within the last 10 minutes with other parameters. Not retried: the same request meets the same answer. Use a new token for a different transaction.

Index<T>

A secondary index of a table. An index can be read and not written, and the type says so: it has no Put, Update or Delete, so what DynamoDB would reject at run time does not compile.

InternalServerErrorException

DynamoDB failed internally (HTTP 500). The client has retried it, so this reaches the caller when every attempt failed.

Item

A DynamoDB item without a schema: attribute names and their values. Everything DynaSharp reads is one of these, and it goes wherever the API takes attributes, since it is an IReadOnlyDictionary<TKey, TValue>.

ItemCollectionMetrics

The size estimate of an item collection that a write operation modified, reported when the request asked for it with Size.

ItemCollectionSizeLimitExceededException

An item collection, all the items with one partition key value, exceeds the 10 GB that a table with a local secondary index allows. Not retried: data must go first.

ItemTableExtensions

The verbs of a table or index without a schema that take the values of a key as they are stored, and the attribute-by-attribute Put() with its With. These are extension methods so that a table of an entity does not offer them: a key given as its values would skip its key template, and a put by attribute would write an item without its discriminator.

KeyFormatException

A value cannot be part of a key: it is empty, contains a delimiter that its format does not take, a control character or U+10FFFF, is not well-formed text, or does not fit its numeric or timestamp format. It is an ArgumentException, so a key built from user input fails as a bad argument.

LimitExceededException

Too many concurrent control-plane operations, such as tables being created at once, or a resource quota is reached. The client has retried it, so this reaches the caller when every attempt failed.

MixedExtensions

Turns a read of a table without a schema into a mixed read. These are extension methods so that the rest does not compile: a read of Table<Order> has filtered on its discriminator already, so no other type could reach it.

ProvisionedThroughputExceededException

DynamoDB throttled the request: the table or an index is over its provisioned read or write capacity. The client has retried it with backoff, so this reaches the caller when the table stayed throttled.

ReplicatedWriteConflictException

A write was rejected because an item it addresses is being modified by a request in another Region of a global table. The client has retried it, so this reaches the caller when every attempt met the conflict.

RequestLimitExceededException

The account-level throughput quota is exceeded. The client has retried it with backoff, so this reaches the caller when the account stayed over its quota.

ResourceInUseException

The table or index is being created, updated or deleted, or already exists. Not retried: wait for the table with WaitUntilActiveAsync(CancellationToken), or let IfNotExists() take an existing table as success.

ResourceNotFoundException

The table or index does not exist, or is not yet ACTIVE. Not retried: check the name and the region, or wait for a new table with WaitUntilActiveAsync(CancellationToken).

TableDrift

One way in which a table that IfNotExists() found differs from what the command declares, in Drift. The command changes nothing about it: it is for a log line, a health check or a test that pins the schema, and for code that acts on it, such as an UpdateTable that adds a missing global index.

TableNotActiveException

A wait for a table and its global secondary indexes to turn ACTIVE ran out of time: LastStatus and PendingIndex say what held it up, and a longer wait is usually the answer.

Table<T>

A DynamoDB table, and the entry to everything that reads and writes it: Table<Order> reads and writes the entity Order, Table<Item> the same table without a schema.

ThrottlingException

Control-plane requests, such as CreateTable or DescribeTable, arrive too fast. The client has retried it with backoff, so this reaches the caller when the throttling went on.

TransactGetResult

What a TransactGetCommand returns: one snapshot of all its items, each read on demand with Read<T>(TransactSlot<T>).

TransactWriteExtensions

The verbs of a transaction: what starts the next action after TransactWriteCommand and after every step, what all steps share, and the send. They are extension methods because they are the same on each of them.

TransactionCanceledException

The whole transaction was cancelled, so none of its actions took effect. Not retried by the client, because repeating the same transaction usually meets the same cause. ReasonFor(TransactMarker) says what became of an action, ItemFor(TransactMarker) what its condition saw, Failures which actions failed, and CancellationReasons holds what DynamoDB sent.

TransactionConflictException

A request was rejected because an ongoing transaction includes the item it addresses. Not retried by the client: repeat the request after a short wait, which RetryOnConflictAsync<TResult>(Func<CancellationToken, ValueTask<TResult>>, CancellationToken) does.

TransactionInProgressException

A transaction with the same ClientRequestToken is still running. The client retries it like a throttling error, with the same token, so a retry either finds the first attempt completed or lets it finish.

TrimmedDataAccessException

The records a request asks for are gone: they are older than the 24 hours that DynamoDB Streams keeps them. DynamoDB Streams reports it as TrimmedDataAccessException.

UnrecognizedClientException

The access key id or session token is invalid or expired. Not retried: check the credentials the client was given, see Credentials.

ValidationException

DynamoDB rejected the request: a malformed expression, a key that does not match the schema, an empty key, an item over 400 KB. Not retried: the request must change.

Structs

Attr

An attribute of an item without a schema, by name or document path, as Attr(string) makes it. The conditions it makes are the ones DynamoDB has for any attribute; it also goes into a hole of an interpolated expression, where it stands for the name.

Attr<T, TConverter>

An attribute with a .NET type and the converter that writes it. The source generator emits one per property (Customer.Attrs.Email), Attr<T>(string) makes one for a number, and any other can be created by hand. A value of the wrong type is a compile error. The docs call such an attribute a handle: Order.Attrs.Total is the handle of the Total property.

AttributeValue

A single DynamoDB attribute value: string, number, binary, boolean, null, list, map or set.

BatchGetCommand<T>

A BatchGetItem under construction: many keys of one table, of any number. Chain the keys and options and end with SendAsync(CancellationToken) in one expression. Reads of another table go through a batch of that table, or through client.BatchGetItemAsync of DynaSharp.Requests.

BatchGetResult<T>

What a batch get returns.

BatchWriteCommand<T>

A BatchWriteItem under construction: puts and deletes of any number, also of other types and other tables in the same batch, as in shop.BatchWrite().Put(item).Delete(pk, sk).Put(orders, order). It is not atomic, runs in requests of 25 writes, sends again what DynamoDB left unprocessed, and gives up with a BatchIncompleteException. Chain the writes and end with SendAsync(CancellationToken) in one expression.

BatchWriteResult

What a batch write returns. Getting this far means every write of the batch was applied: what cannot be written ends in a BatchIncompleteException.

ConditionStep

A delete or a condition check in a transaction: what can follow it are its condition, the verbs of the next action, and sending. A check without a condition is rejected by DynamoDB. See TransactWriteExtensions for the rest.

ContinuationToken

A position in a Query or Scan, for paging across requests: take Next, hand ToString() to the client, and on the next request pass Parse(string?) of what came back to PageAsync. The text is safe in a URL. It is encoded, not encrypted, and signed only by a client with TokenSigner: without one, a client can read it and choose its position in the partition. The default value is the start of the read.

DeleteCommand<T>

A DeleteItem under construction. Deleting what does not exist is no error unless IfExists() asks for one. Chain the options and end with SendAsync(CancellationToken) in one expression.

FanOutQueryCommand<T>

A Query of several partitions at once, merged by sort key, the read of write shards and time buckets: orders.Query(shards, SortKeyCondition.Ge(from)).Descending().ItemsAsync(ct). Chain the options and end with ItemsAsync(CancellationToken), PageAsync(int, ContinuationToken, CancellationToken) or CountAsync(CancellationToken) in one expression.

GetCommand<T>

A GetItem under construction. Chain the options and end with ItemAsync(CancellationToken) or SendAsync(CancellationToken) in one expression.

GetResult<T>

What a get returns.

GetSelectCommand<TValue, TConverter>

A GetItem of one attribute, as Select<TValue, TConverter>(Attr<TValue, TConverter>) leaves it. Nothing can be added any more, which the type enforces, so Consistent and the other clauses come before Select: all that is left is to send it. See GetCommand<T> for what a command is and what it cannot do.

Item.Enumerator

Enumerates the attributes of an item.

MixedQueryCommand<TMixed>

A Query that reads several entity types of one partition, the adjacency list of a single table: shop.Query(pk).Of<Customer, Order>(). It has the clauses of QueryCommand<T> and every way to send it but CountAsync, because a count has nothing to dispatch.

MixedScanCommand<TMixed>

A Scan that reads several entity types of a table or index: shop.Scan().Of<Customer, Order>(). It has the clauses of ScanCommand<T> and every way to send it but CountAsync, and MixedQueryCommand<TMixed> says what the mix adds.

Mixed<T1, T2>

One item of a mixed read: an item of one of several types, from shop.Query(pk).Of<Customer, Order>(). Ask with item.Is(out Customer customer), or handle every case with Match<TResult>(Func<T1, TResult>, Func<T2, TResult>), which is what stays correct when a type is added.

Mixed<T1, T2, T3>

One item of a mixed read of 3 types. See Mixed<T1, T2>.

Mixed<T1, T2, T3, T4>

One item of a mixed read of 4 types. See Mixed<T1, T2>.

Page<T>

One page of a Query or Scan: what one response of DynamoDB holds. A page ends at 1 MB of data read, or at the limit, whichever comes first. A page of a fan-out is the exception: it is a stretch of the merge, of the size that was asked for, made of as many responses as that took.

ParallelScanCommand<T>

A scan of several segments at once, from Parallel(int). All it can do is give the merged items: pages of several segments have no single key to continue from, so what PageAsync would mean does not compile. Paging across requests goes through Segment(int, int), one segment at a time.

PartitionKey<TEntity>

A partition key that remembers its entity, which is what the generated Order.Keys.Pk.Of(userId) and Order.Keys.ByStatusPk.Of(status) return. orders.Query(Order.Keys.Pk.Of(id)) checks the key against the table, so orders.Query(Customer.Keys.Pk.Of(id)) is a compile error. A table without a schema takes the key of any entity, because it reads several: shop.Query(Order.Keys.Pk.Of(id)).Of<Customer, Order>().

PutCommand<T>

A PutItem under construction, which replaces the whole item under its key. Chain the options and end with SendAsync(CancellationToken) in one expression.

PutStep

A put in a transaction: what can follow it are its condition, the verbs of the next action, and sending. Attributes of an update do not exist here, so .Add after .Put does not compile. See TransactWriteExtensions for the rest.

QueryCommand<T>

A Query under construction: the items of one partition, in the order of the sort key. Chain the options and end with ItemsAsync(CancellationToken), ItemAsync(CancellationToken), PagesAsync(CancellationToken), PageAsync(ContinuationToken, CancellationToken) or CountAsync(CancellationToken) in one expression.

QuerySelectCommand<TValue, TConverter>

A Query of one attribute, as Select<TValue, TConverter>(Attr<TValue, TConverter>) leaves it. Nothing can be added any more, which the type enforces, so Filter, Limit, Descending and the other clauses come before Select: what is left is to send it, with the same methods as QueryCommand<T>.

ReturnCommand<TValue, TConverter>

An update that returns one attribute, as Return<TValue, TConverter>(Attr<TValue, TConverter>) leaves it. Nothing can be added any more, which the type enforces: all that is left is to send it.

ScanCommand<T>

A Scan under construction: every item of a table or index, in no useful order, at the cost of reading them all. Chain the options and end with ItemsAsync(CancellationToken), PagesAsync(CancellationToken), PageAsync(ContinuationToken, CancellationToken) or CountAsync(CancellationToken) in one expression.

ScanSelectCommand<TValue, TConverter>

A Scan of one attribute, as Select<TValue, TConverter>(Attr<TValue, TConverter>) leaves it. Nothing can be added any more, which the type enforces, so Filter, Limit, Segment and the other clauses come before Select: what is left is to send it, with the same methods as ScanCommand<T>. It charges what any scan charges.

SelectResult<TValue>

What a read of one attribute gives when there may be no item: GetItem without one, or a query in which nothing matches. It has the shape of GetResult<T> with one difference: there, Found says that Item is not null, which an attribute cannot promise, because a nullable one can be missing from an item that exists.

SortKeyCondition

A condition on the sort key of a query. Only what DynamoDB allows in a key condition can be expressed: one comparison, a range or a prefix, and no <>. The default value means no condition, which reads the whole partition.

TransactGetCommand

A TransactGetItems under construction: up to 100 gets, of any tables and types, that see one snapshot. Chain them and end with SendAsync(CancellationToken) in one expression. Each get hands out a slot, which reads its item from the result.

TransactMarker

Names one action of a transaction, to find out what became of it when the transaction is cancelled: ReasonFor(TransactMarker) and ItemFor(TransactMarker). The verbs of TransactWriteCommand hand it out with out.

TransactSlot<T>

Names one get of a TransactGetCommand, with the type it reads, to read it from the TransactGetResult.

TransactWriteCommand

A TransactWriteItems between its actions: up to 100 puts, updates, deletes and condition checks, on any tables, that take effect together or not at all. The verbs are in TransactWriteExtensions, and each returns a step with the clauses of its own action and the verbs of the next one.

TransactWriteResult

What a transaction of writes returns. Getting this far means that all its actions were applied, as one.

TransactionActionFailure

An action that made a transaction fail. It holds neither keys nor values, so it is safe to log.

UpdateCommand<T>

An UpdateItem under construction. It changes single attributes, and it creates the item if none has the key, unless IfExists() says otherwise. Chain the changes and options in any order and end with SendAsync(CancellationToken) in one expression.

UpdateStep

An update in a transaction: what can follow it are its changes and its condition, in any order, the verbs of the next action, and sending. One attribute can appear in one change of an update only. See TransactWriteExtensions for the rest.

WriteResult<T>

What a put, an update or a delete returns.

Interfaces

IConditional<TSelf>

A command that takes a condition. It is the way to write a helper that works on all of them, without knowing the command:

public static TCommand OnlyIfOwned<TCommand>(this TCommand command, string owner)
    where TCommand : IConditional<TCommand>, allows ref struct =>
    command.If(Attr("owner").Eq(owner));

IFilterable<TSelf>

A read that takes a filter. It is the way to write a helper that works on queries and scans alike, without knowing the command:

public static TCommand NotDeleted<TCommand>(this TCommand command)
    where TCommand : IFilterable<TCommand>, allows ref struct =>
    command.Filter(Attr("deletedAt").NotExists());

IMixed<TSelf>

An item of a mixed read, Mixed<T1, T2> and its siblings of 3 and 4 types: what MixedQueryCommand<TMixed> and MixedScanCommand<TMixed> read. Only the Mixed types implement it.

IRetryable<TSelf>

A command that takes per-call options of the retry loop, for a helper that works on all of them, see IConditional<TSelf>.

ITransactWriteChain<TSelf>

A link of a transaction: TransactWriteCommand or a step. It is what the verbs of TransactWriteExtensions work on, so that the next action and the send read the same after every step. Nothing outside this library implements it.

ITransactWriteStep<TSelf>

A step of a transaction, which has an action: what takes a condition. TransactWriteCommand stands between actions, so a condition on it does not compile. Nothing outside this library implements it.

IUpdatable<TSelf>

A command that changes attributes, for a helper that works on all of them, see IConditional<TSelf>. Audit fields are the usual case: command.Set("updatedBy", user).

Enums

AttributeType

The data type of an AttributeValue, one per DynamoDB type descriptor.

ConflictKind

Which lost races RetryOnConflictAsync<TResult>(Func<CancellationToken, ValueTask<TResult>>, ConflictKind, int, CancellationToken) runs its delegate again on. Without it, a retry takes Any.

ReturnConsumedCapacity

Whether DynamoDB reports the capacity units an operation consumed.

ReturnItemCollectionMetrics

Whether a write operation reports the size of the item collection it modified.

ReturnValue

Which item attributes a write operation returns.

ReturnValuesOnConditionCheckFailure

Whether a failed condition check returns the item it was evaluated against, in Item, or for an action of a transaction in Item.

SelectKind

Which attributes a Query or Scan returns.

TableDriftKind

What a TableDrift is about: how a table that IfNotExists() found differs from what the command declares, in a way that lets part of the code work. A key that differs is no drift: it fails every read and write, so the command throws instead.

TableStatus

The lifecycle state of a table.

TransactionFailure

Why one action of a cancelled transaction did not take effect, as a value: ReasonFor(TransactMarker). Each member says whether repeating the same transaction can pass, because some causes go away by themselves and others never do.