billstclair / elm-dynamodb / DynamoDB

Pure Elm client for the AWS DynamoDB NoSQL database service.

Types


type alias Request a =
AWS.Http.Request AWS.Http.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 : Types.Account -> Request a -> Task Types.Error a

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

Creating requests

getItem : Types.TableName -> Types.Key -> Request (Maybe Types.Item)

Get an item from a table.

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

getItemWithMetadata : Types.TableName -> Types.Key -> Request ( Http.Metadata, Maybe Types.Item )

Get an item, returning the Http request Metadata.

putItem : Types.TableName -> Types.Key -> Types.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 : Types.TableName -> Types.Key -> Types.Item -> Request Http.Metadata

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

deleteItem : Types.TableName -> Types.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 : Types.TableName -> Types.Key -> Request Http.Metadata

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


type alias ScanValue =
{ count : Basics.Int
, items : List Types.Item
, lastEvaluatedKey : Maybe Types.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 : Types.TableName -> Maybe Types.Key -> Maybe Basics.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

scanWithMetadata : Types.TableName -> Maybe Types.Key -> Maybe Basics.Int -> Request ( Http.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 : Types.TableName
, key : Types.Key
, returnedAttributeNames : Maybe (List String) 
}

Specify one item for transactGetItems.

All attributes are returned if returnedAttributeNames is Nothing.


type alias TransactGetItemValue =
{ tableName : Types.TableName
, key : Types.Key
, item : Maybe Types.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

transactGetItemsWithMetadata : List TransactGetItem -> Request ( Http.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.


type TransactWrite
    = TransactWriteDelete ({ tableName : Types.TableName, key : Types.Key })
    | TransactWritePut ({ tableName : Types.TableName, key : Maybe Types.Key, item : Types.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

transactWriteItemsWithMetadata : List TransactWrite -> Request Http.Metadata

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 -> Types.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 -> Types.Item -> Basics.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 -> Types.Item -> Basics.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, Types.AttributeValue ) -> Types.Item

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

removeKeyFields : Types.Key -> Types.Item -> Types.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 : Types.Key -> Types.Item -> Types.Item

Add key fields to an Item.

keyNames : Types.Key -> List String

Return a list of the key names in a Key.

Reading accounts into Elm

readAccounts : Maybe String -> Task Types.Error (List Types.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 Types.Error (List Types.Account)

Decode a JSON string encoding a list of Accounts

accountDecoder : Json.Decode.Decoder Types.Account

A Decoder for the Account type.

encodeAccount : Types.Account -> Json.Encode.Value

Encode an account as a JSON value.

Low-level functions

makeRequest : String -> Json.Encode.Value -> Json.Decode.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 -> Json.Encode.Value -> (Http.Metadata -> Json.Decode.Decoder a) -> Request a

Request creator with retained Metadata

Same as makeRequest, but the decoder takes metadata