aws-0.12.1: Amazon Web Services (AWS) for Haskell

CopyrightSoostone Inc, Chris Allen
LicenseBSD3
MaintainerOzgun Ataman <ozgun.ataman@soostone.com>
Stabilityexperimental
Safe HaskellNone
LanguageHaskell2010

Aws.DynamoDb.Core

Contents

Description

Shared types and utilities for DyanmoDb functionality.

Synopsis

Configuration and Regions

data Region

Constructors

Region 

ddbLocal :: Region

DynamoDb local connection (for development)

data DdbConfiguration qt

Constructors

DdbConfiguration 

Fields

ddbcRegion :: Region

The regional endpoint. Ex: ddbUsEast

ddbcProtocol :: Protocol

HTTP or HTTPS

ddbcPort :: Maybe Int

Port override (mostly for local dev connection)

DynamoDB values

data DValue

Value types natively recognized by DynamoDb. We pretty much exactly reflect the AWS API onto Haskell types.

Constructors

DNum Scientific 
DString Text 
DBinary ByteString

Binary data will automatically be base64 marshalled.

DNumSet (Set Scientific) 
DStringSet (Set Text) 
DBinSet (Set ByteString)

Binary data will automatically be base64 marshalled.

Converting to/from DValue

class DynData (DynRep a) => DynVal a where

Class of Haskell types that can be represented as DynamoDb values.

This is the conversion layer; instantiate this class for your own types and then use the toValue and fromValue combinators to convert in application code.

Each Haskell type instantiated with this class will map to a DynamoDb-supported type that most naturally represents it.

Associated Types

type DynRep a

Which of the DynData instances does this data type directly map to?

Methods

toRep :: a -> DynRep a

Convert to representation

fromRep :: DynRep a -> Maybe a

Convert from representation

Instances

DynVal Bool

Encoded as 0 and 1.

DynVal Double 
DynVal Int 
DynVal Int8 
DynVal Int16 
DynVal Int32 
DynVal Int64 
DynVal Integer 
DynVal Word8 
DynVal Word16 
DynVal Word32 
DynVal Word64 
DynVal ByteString 
DynVal Text 
DynVal UTCTime

Losslessly encoded via Integer picoseconds

DynVal Day

Encoded as number of days

DynVal DValue 
(DynData (DynRep [a]), DynVal a) => DynVal [a]

Any singular DynVal can be upgraded to a list.

(DynData (DynRep (Set a)), DynVal a, Ord a) => DynVal (Set a)

Any singular DynVal can be upgraded to a Set.

Serialize a => DynVal (Bin a) 

toValue :: DynVal a => a -> DValue

Encode a Haskell value.

fromValue :: DynVal a => DValue -> Maybe a

Decode a Haskell value.

newtype Bin a

Type wrapper for binary data to be written to DynamoDB. Wrap any Serialize instance in there and DynVal will know how to automatically handle conversions in binary form.

Constructors

Bin 

Fields

getBin :: a
 

Instances

Enum a => Enum (Bin a) 
Eq a => Eq (Bin a) 
Ord a => Ord (Bin a) 
Read a => Read (Bin a) 
Show a => Show (Bin a) 
Serialize a => DynVal (Bin a) 
type DynRep (Bin a) = DynBinary 

Defining new DynVal instances

class Ord a => DynData a where

An internally used closed typeclass for values that have direct DynamoDb representations. Based on AWS API, this is basically numbers, strings and binary blobs.

This is here so that any DynVal haskell value can automatically be lifted to a list or a Set without any instance code duplication.

Do not try to create your own instances.

Methods

fromData :: a -> DValue

toData :: DValue -> Maybe a

newtype DynBinary

Binary values stored in DynamoDb. Only used in defining new DynVal instances.

Constructors

DynBinary 

newtype DynNumber

Numeric values stored in DynamoDb. Only used in defining new DynVal instances.

Constructors

DynNumber 

newtype DynString

String values stored in DynamoDb. Only used in defining new DynVal instances.

Constructors

DynString 

Fields

unDynString :: Text
 

Working with key/value pairs

parseAttributeJson :: Value -> Parser [Attribute]

Parse a JSON object that contains attributes

attributeJson :: Attribute -> Pair

Convert into JSON pair

attributesJson :: [Attribute] -> Value

Convert into JSON object for AWS.

attrTuple :: Attribute -> (Text, DValue)

Convert attribute to a tuple representation

attr :: DynVal a => Text -> a -> Attribute

Convenience function for constructing key-value pairs

attrAs :: DynVal a => Proxy a -> Text -> a -> Attribute

attr with type witness to help with cases where you're manually supplying values in code.

> item [ attrAs text "name" "john" ]

text :: Proxy Text

Type witness for Text. See attrAs.

int :: Proxy Integer

Type witness for Integer. See attrAs.

double :: Proxy Double

Type witness for Double. See attrAs.

data PrimaryKey

Primary keys consist of either just a Hash key (mandatory) or a hash key and a range key (optional).

Constructors

PrimaryKey 

hk :: Text -> DValue -> PrimaryKey

Construct a hash-only primary key.

>>> hk "user-id" "ABCD"
>>> hk "user-id" (mkVal 23)

hrk

Arguments

:: Text

Hash key name

-> DValue

Hash key value

-> Text

Range key name

-> DValue

Range key value

-> PrimaryKey 

Construct a hash-and-range primary key.

Working with objects (attribute collections)

type Item = Map Text DValue

A DynamoDb object is simply a key-value dictionary.

item :: [Attribute] -> Item

Pack a list of attributes into an Item.

attributes :: Map Text DValue -> [Attribute]

Unpack an Item into a list of attributes.

class ToDynItem a where

Types convertible to DynamoDb Item collections.

Use attr and attrAs combinators to conveniently define instances.

Methods

toItem :: a -> Item

Instances

class FromDynItem a where

Types parseable from DynamoDb Item collections.

User getAttr family of functions to applicatively or monadically parse into your custom types.

Methods

parseItem :: Item -> Parser a

Instances

fromItem :: FromDynItem a => Item -> Either String a

Parse an Item into target type using the FromDynItem instance.

newtype Parser a

A continuation-based parser type.

Constructors

Parser 

Fields

runParser :: forall f r. Failure f r -> Success a f r -> f r
 

getAttr

Arguments

:: (Typeable a, DynVal a) 
=> Text

Attribute name

-> Item

Item from DynamoDb

-> Parser a 

Convenience combinator for parsing fields from an Item returned by DynamoDb.

getAttr'

Arguments

:: (Typeable a, DynVal a) 
=> Text

Attribute name

-> Item

Item from DynamoDb

-> Parser (Maybe a) 

Parse attribute if it's present in the Item. Fail if attribute is present but conversion fails.

Common types used by operations

data Conditions

Conditions used by mutation operations (PutItem, UpdateItem, etc.). The default def instance is empty (no condition).

conditionsJson :: Text -> Conditions -> [Pair]

JSON encoding of conditions parameter in various contexts.

data Condition

A condition used by mutation operations (PutItem, UpdateItem, etc.).

Constructors

Condition 

Fields

condAttr :: Text

Attribute to use as the basis for this conditional

condOp :: CondOp

Operation on the selected attribute

data CondMerge

How to merge multiple conditions.

Constructors

CondAnd 
CondOr 

data UpdateReturn

What to return from the current update operation

Constructors

URNone

Return nothing

URAllOld

Return old values

URUpdatedOld

Return old values with a newer replacement

URAllNew

Return new values

URUpdatedNew

Return new values that were replacements

data QuerySelect

What to return from a Query or Scan query.

Constructors

SelectSpecific [Text]

Only return selected attributes

SelectCount

Return counts instead of attributes

SelectProjected

Return index-projected attributes

SelectAll

Default. Return everything.

Size estimation

class DynSize a where

A class to help predict DynamoDb size of values, attributes and entire items. The result is given in number of bytes.

Methods

dynSize :: a -> Int

nullAttr :: Attribute -> Bool

Will an attribute be considered empty by DynamoDb?

A PutItem (or similar) with empty attributes will be rejected with a ValidationException.

Responses & Errors

data DdbResponse

Response metadata that is present in every DynamoDB response.

Constructors

DdbResponse 

shouldRetry :: DdbErrCode -> Bool

Whether the action should be retried based on the received error.

data DdbError

Potential errors raised by DynamoDB

Constructors

DdbError 

Fields

ddbStatusCode :: Int

200 if successful, 400 for client errors and 500 for server-side errors.

ddbErrCode :: DdbErrCode
 
ddbErrMsg :: Text
 

Internal Helpers

data AmazonError

Constructors

AmazonError 

Fields

aeType :: Text
 
aeMessage :: Maybe Text