billstclair/elm-dynamodb/2.1.0

NOTE: the latest version is 2.5.0

DynamoDB

Pure Elm client for the AWS DynamoDB NoSQL database service.

Types

type alias Request a =
Request AWSAppError a

A request that can be turned into a Task by DynamoDB.send.

a is the type of the successful Task result from DynamoDB.send.

Turning a Request into a Task

send : Account -> Request a -> Task Error a

Create a Task to send a signed request over the wire.

Creating requests

getItem : TableName -> Key -> Request (Maybe Item)
getItemWithMetadata : TableName -> Key -> Request ( Metadata, Maybe Item )

Get an item, returning the Http request Metadata.

putItem : TableName -> Key -> Item -> Request ()

Put an item into a table. There is no return value.

See https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html

putItemWithMetadata : TableName -> Key -> Item -> Request Metadata

Put an item into a table, returning the Http request Metadata.

deleteItem : TableName -> Key -> Request ()

Delete an item from a table. There is no return value.

See https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DeleteItem.html

deleteItemWithMetadata : TableName -> Key -> Request Metadata

Delete an item from a table, returning the Http request Metadata.

type alias ScanValue =
{ count : Int
, items : List Item
, lastEvaluatedKey : Maybe Key
}

The return value for scan and scanWithMetadata

Pass lastEvaluatedKey to a subsequent call to scan to get more.

This doesn't include ScannedCount, because that's the same as Count unless you do filtering, which isn't yet supported.

scan : TableName -> Maybe Key -> Maybe Int -> Request (Maybe ScanValue)

Scan a table for items.

If Maybe Key isn't Nothing, it's the ExclusiveStartKey.

If Maybe Int isn't Nothing, it's the Limit.

See https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Scan.html

TableName
-> Maybe Key
-> Maybe Int
-> Request ( Metadata, Maybe ScanValue )

Scan a table for items, returning the Http request Metadata.

If Maybe Key isn't Nothing, it's the ExclusiveStartKey.

If Maybe Int isn't Nothing, it's the Limit.

type alias TransactGetItem =
{ tableName : TableName
, key : Key
, returnedAttributeNames : Maybe (List String)
}

Specify one item for transactGetItems.

All attributes are returned if returnedAttributeNames is Nothing.

{ tableName : TableName
, key : Key
, item : Maybe Item
}

One of the return values from transactGetItems.

transactGetItems : List TransactGetItem -> Request (List TransactGetItemValue)

Do a bunch of TransactGetItem requests inside a transaction.

Will error if the list has more than 100 elements.

See https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactGetItems.html

List TransactGetItem
-> Request ( Metadata, List TransactGetItemValue )

Do a bunch of TransactGetItem requests inside a transaction, returning the Http request Metadata.

Will error if the list has more than 100 elements.

= TransactWriteDelete
{ tableName : TableName
, key : Key
}
| TransactWritePut
{ tableName : TableName
, key : Maybe Key
, item : Item
}

One action for the list passed to transactWriteItems.

TransactWriteDelete deletes the attribute with the given key.

TransactWritePut writes (or overwrites) the given item, merging the key name/value pairs into item, if key is not Nothing.

transactWriteItems : List TransactWrite -> Request ()

Do a bunch of TransactWrite requests inside a transaction. There is no return value.

Will error if the list has more than 100 elements.

See https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html

Do a bunch of TransactWrite requests inside a transaction, returning the Http request Metdata.

Will error if the list has more than 100 elements.

Accessing values in items

itemStringValue : String -> Item -> String

Return the value of an item's string attribute.

If the attribute does not exist or doesn't have a string value, return "".

itemFloatValue : String -> Item -> Float

Return the value of an item's float attribute.

If the attribute does not exist or doesn't have a float value, return NaN.

itemIntValue : String -> Item -> Int

Round an item's float value to an integer.

If the attribute does not exist or doesn't have a float value, returns NaN as an integer, which can only be detected via isNan (toFloat n).

Utility functions

makeItem : List ( String, AttributeValue ) -> Item

Create an Item from a list of (key, value) tuples.

removeKeyFields : Key -> Item -> Item

Remove the key fields from an Item.

The Item that comes back from getItem or getItemWithMetadata contains the key fields. Sometimes you'd rather not see them there.

addKeyFields : Key -> Item -> Item

Add key fields to an Item.

keyNames : Key -> List String

Return a list of the key names in a Key.

Reading accounts into Elm

readAccounts : Maybe String -> Task Error (List Account)

Read JSON from a URL and turn it into a list of Accounts.

If Nothing is passed for the first arg (the URL), will use the default of "accounts.json".

You're not going to want to store the secret keys in this JSON in plain text anywhere but your development machine. In applications, they will ususally be stored in LocalStorage.

Example JSON:

[{"name": "Dynamo DB",
  "region": "us-east-1",
  "access-key": "<20-character access key>",
  "secret-key": "<40-character secret key>",
  "tableName": "<your table name>"
 }
]
decodeAccounts : String -> Result Error (List Account)

Decode a JSON string encoding a list of Accounts

accountDecoder : Decoder Account

A Decoder for the Account type.

encodeAccount : Account -> Value

Encode an account as a JSON value.

Low-level functions

makeRequest : String -> Value -> Decoder a -> Request a

Low-level request creator.

Similar toAWS.Http.request, but assumes the HTTP result is JSON and uses AWS.Http.awsAppErrDecoder as the ErrorDecoder.

makeFullRequest : String -> Value -> (Metadata -> Decoder a) -> Request a

Request creator with retained Metadata

Same as makeRequest, but the decoder takes metadata