Copyright	Copyright (c) 2015, Michael Alan Dorman
License	MIT
Maintainer	mdorman@jaunder.io
Stability	experimental
Portability	POSIX
Safe Haskell	None
Language	Haskell2010

Database.Couch.Types

Contents

Basic types to distinguish CouchDB information
- Handling encoding
Request Context
Building requests
- Handling Query Parameters
  - Helpers for converting values to Query Parameters
- Handling Header values
  - Helpers for converting values to Headers
Parameters for different requests.
Specifying how to monitor updates
Document revision map
View specification type
Design document type
A type for view information
Parameters for view retrieval.
Results of a request
- Some success values
- Error values These will come to cover the gamut from failure to parse a particular JSON value to document conflicts. We try to differentiate in useful ways without being slavish about it.

Description

These types are intended for interacting with a CouchDB database. We generally favor giving things distinct types for different uses, though this is not a hard and fast rule.

Synopsis

Basic types to distinguish CouchDB information

newtype Db Source

The name of a database

Constructors

Db
Fields unwrapDb :: Text

Instances

Eq Db
Show Db
IsString Db
ToJSON Db
FromJSON Db

newtype DocId Source

The id of a document

Constructors

DocId
Fields unwrapDocId :: Text

Instances

Eq DocId
Show DocId
IsString DocId
ToJSON DocId
FromJSON DocId

newtype DocRev Source

The revision of a document

Constructors

DocRev
Fields unwrapDocRev :: Text

Instances

Eq DocRev
Show DocRev
IsString DocRev
ToJSON DocRev
FromJSON DocRev

newtype Host Source

The name of a host

Constructors

Host
Fields unwrapHost :: Text

Instances

Eq Host
Show Host
IsString Host
ToJSON Host
FromJSON Host

newtype Password Source

The password of a user

Constructors

Password
Fields unwrapPassword :: Text

Instances

Eq Password
Show Password
IsString Password
ToJSON Password
FromJSON Password

newtype Port Source

A TCP port number

Constructors

Port
Fields unwrapPort :: Int

Instances

Eq Port
Show Port

newtype User Source

The name of a user

Constructors

User
Fields unwrapUser :: Text

Instances

Eq User
Show User
IsString User
ToJSON User
FromJSON User

Handling encoding

reqDocId :: DocId -> ByteString Source

Convert a DocId directly into a ByteString

reqDocRev :: DocRev -> ByteString Source

Convert a DocRev directly into a ByteString

reqPassword :: Password -> ByteString Source

Convert a Password directly into a ByteString

reqUser :: User -> ByteString Source

Convert a User directly into a ByteString

Request Context

data Context Source

This represents the context for each CouchDB request.

This contains all the bits that are unlikely to vary between requests.

Eventually, we should have routines that are smart enough to pull this out of a suitably-set-up Monad, so you could just stash it there and forget about it.

Constructors

Context

Fields

ctxManager :: Manager: The Manager that Network.HTTP.Client requests require. We store it here for easy access.
ctxHost :: Host: The host to connect to
ctxPort :: Port: The port to connect to
ctxCred :: Maybe Credentials: Any credentials that should be used in making requests
ctxCookies :: CookieJar: We can trade credentials for a session cookie that is more efficient, this is where it can be stored.
ctxDb :: Maybe Db: The database that should be used for database-specific requests.

reqDb :: Context -> ByteString Source

Pull the appropriately encoded database out of the context

reqHost :: Context -> ByteString Source

Pull the appropriately encoded host out of the context

reqPort :: Context -> Int Source

Pull the appropriately encoded port out of the context

data Credentials Source

The credentials for each CouchDB request.

Many operations in CouchDB require some sort of authentication. We will store the credentials in their various forms here (though we're sticking to HTTP Basic Authentication for now).

There are operations on the request that know how to modify the request appropriately depending on which credential type is in play.

Constructors

Basic
Fields credUser :: User credPass :: Password

Building requests

Handling Query Parameters

type QueryParameters = [(ByteString, Maybe ByteString)] Source

A quick type alias for query parameters.

class ToQueryParameters a where Source

A typeclass for types that can be converted to query parameters.

Methods

toQueryParameters :: a -> QueryParameters Source

Performs the actual conversion

Instances

ToQueryParameters ViewParams	Convert to query parameters
ToQueryParameters RetrieveDoc	Convert to query parameters
ToQueryParameters ModifyDoc	Convert to query parameters (partial)
ToQueryParameters DbAllDocs	Convert to query parameters
ToQueryParameters DbChanges	Convert to query parameters
ToQueryParameters DbUpdates	Convert to query parameters

Helpers for converting values to Query Parameters

toQP Source

Arguments

:: ByteString	The name of the query parameter
-> (a -> ByteString)	A function from the raw value to a `ByteString`
-> Maybe a	The raw value
-> Maybe (ByteString, Maybe ByteString)

Convert a value to a query parameter

boolToQP :: ByteString -> Maybe Bool -> Maybe (ByteString, Maybe ByteString) Source

Handle converting Bool values

docIdToQP :: ByteString -> Maybe DocId -> Maybe (ByteString, Maybe ByteString) Source

Handle converting DocId values

docRevToQP :: ByteString -> Maybe DocRev -> Maybe (ByteString, Maybe ByteString) Source

Handle converting DocRev values

intToQP :: ByteString -> Maybe Int -> Maybe (ByteString, Maybe ByteString) Source

Handle converting Int values

textToQP :: ByteString -> Maybe Text -> Maybe (ByteString, Maybe ByteString) Source

Handle converting Text values

Handling Header values

class ToHTTPHeaders a where Source

A typeclass for types that can be converted to headers.

Methods

toHTTPHeaders :: a -> [Header] Source

Performs the actual conversion

Instances

ToHTTPHeaders ModifyDoc

Convert to HTTP Headers (partial)

Helpers for converting values to Headers

toHH Source

Arguments

:: HeaderName	The name of the header
-> (a -> ByteString)	A function from the raw value to a `ByteString`
-> Maybe a	The raw value
-> Maybe Header

Convert a value to a Header

boolToHH :: HeaderName -> Maybe Bool -> Maybe Header Source

Handle converting Bool values

Parameters for different requests.

Parameters for monitoring server database creation

data DbUpdates Source

The basic structure

Constructors

DbUpdates
Fields feed :: Maybe FeedType timeOut :: Maybe Int heartBeat :: Maybe Bool

Instances

ToQueryParameters DbUpdates

Convert to query parameters

dbUpdatesParam :: DbUpdates Source

The default (empty) parameters

Parameters for monitoring database changes

data DbChanges Source

The basic structure

Constructors

DbChanges
Fields cDocIds :: Maybe [DocId] cConflicts :: Maybe Bool cDescending :: Maybe Bool cFeed :: Maybe FeedType cFilter :: Maybe Text cHeartBeat :: Maybe Int cIncludeDocs :: Maybe Bool cAttachments :: Maybe Bool cAttEncodingInfo :: Maybe Bool cLastEvent :: Maybe Text cSince :: Maybe SinceType cStyle :: Maybe StyleType cTimeout :: Maybe Int cView :: Maybe Text

Instances

ToQueryParameters DbChanges

Convert to query parameters

dbChangesParam :: DbChanges Source

The default (empty) parameters

Parameters for bulk retrieval of documents.

data DbAllDocs Source

The basic structure

Constructors

DbAllDocs
Fields adConflicts :: Maybe Bool adDescending :: Maybe Bool adEndKey :: Maybe Text adEndKeyDocId :: Maybe DocId adIncludeDocs :: Maybe Bool adInclusiveEnd :: Maybe Bool adKey :: Maybe Text adLimit :: Maybe Int adSkip :: Maybe Int adStale :: Maybe Bool adStartKey :: Maybe Text adStartKeyDocId :: Maybe DocId adUpdateSeq :: Maybe Bool

Instances

ToQueryParameters DbAllDocs

Convert to query parameters

dbAllDocs :: DbAllDocs Source

The default (empty) parameters for bulk retrieval of documents

Paramters for bulk creation and updating parameters

data DbBulkDocs Source

The basic structure

Constructors

DbBulkDocs
Fields bdAllOrNothing :: Maybe Bool bdFullCommit :: Maybe Bool bdNewEdits :: Maybe Bool

dbBulkDocs :: DbBulkDocs Source

The default (empty) parameters for bulk creation and update of documents

Parameters for modifying documents

data ModifyDoc Source

The basic structure

Constructors

ModifyDoc
Fields dpFullCommit :: Maybe Bool dpBatch :: Maybe Bool

Instances

ToHTTPHeaders ModifyDoc	Convert to HTTP Headers (partial)
ToQueryParameters ModifyDoc	Convert to query parameters (partial)

modifyDoc :: ModifyDoc Source

The default (empty) parameters

Parameters for retrieving documents

data RetrieveDoc Source

The basic structure

Constructors

RetrieveDoc
Fields dgdAttachments :: Maybe Bool dgdAttEncodingInfo :: Maybe Bool dgdAttsSince :: [DocRev] dgdConflicts :: Maybe Bool dgdDeletedConflicts :: Maybe Bool dgdLatest :: Maybe Bool dgdLocalSeq :: Maybe Bool dgdMeta :: Maybe Bool dgdOpenRevs :: [DocRev] dgdRev :: Maybe DocId dgdRevs :: Maybe Bool dgdRevsInfo :: Maybe Bool

Instances

ToQueryParameters RetrieveDoc

Convert to query parameters

retrieveDoc :: RetrieveDoc Source

The default (empty) parameters

Specifying how to monitor updates

data FeedType Source

Types of feeds available.

Constructors

Continuous
EventSource
Longpoll

feedTypeToQP :: Maybe FeedType -> Maybe (ByteString, Maybe ByteString) Source

Convert feed to Query Parameter

data SinceType Source

Possible values of since

Constructors

Now
Since Int

sinceTypeToQP :: Maybe SinceType -> Maybe (ByteString, Maybe ByteString) Source

Convert since to Query Parameter

data StyleType Source

Possible values for style

Constructors

StyleAll
StyleMain

styleTypeToQP :: Maybe StyleType -> Maybe (ByteString, Maybe ByteString) Source

Convert style to Query Parameter

Document revision map

data DocRevMap Source

The basic data type

Constructors

DocRevMap [(DocId, [DocRev])]

Instances

Eq DocRevMap
Show DocRevMap
Generic DocRevMap
ToJSON DocRevMap	encode to JSON
FromJSON DocRevMap	decode from JSON
type Rep DocRevMap

View specification type

data ViewSpec Source

The basic type

Constructors

ViewSpec
Fields vsMap :: Text vsReduce :: Maybe Text

Instances

Eq ViewSpec
Show ViewSpec
Generic ViewSpec
ToJSON ViewSpec	encode to JSON
FromJSON ViewSpec	decode from JSON
type Rep ViewSpec

Design document type

data DesignDoc Source

The basic type

Constructors

DesignDoc
Fields ddocId :: DocId ddocRev :: DocRev ddocLanguage :: Maybe Text ddocOptions :: Maybe (HashMap Text Text) ddocFilters :: Maybe (HashMap Text Text) ddocLists :: Maybe (HashMap Text Text) ddocShows :: Maybe (HashMap Text Text) ddocUpdates :: Maybe (HashMap Text Text) ddocValidation :: Maybe Text ddocViews :: Maybe (HashMap Text ViewSpec)

Instances

Eq DesignDoc
Show DesignDoc
Generic DesignDoc
ToJSON DesignDoc	encode to JSON
FromJSON DesignDoc	decode from JSON
type Rep DesignDoc

A type for view information

data ViewIndexInfo Source

The basic type

Constructors

ViewIndexInfo
Fields viCompactRunning :: Bool viDataSize :: Int viDiskSize :: Int viLanguage :: Text viPurgeSeq :: Int viSignature :: Text viUpdateSeq :: Int viUpdaterRunning :: Bool viWaitingClients :: Int viWaitingCommit :: Bool

Instances

Eq ViewIndexInfo
Show ViewIndexInfo
Generic ViewIndexInfo
FromJSON ViewIndexInfo	decode from JSON
type Rep ViewIndexInfo

Parameters for view retrieval.

data ViewParams Source

The basic type

Constructors

ViewParams

Fields

vpAttachments :: Maybe Bool
vpAttEncodingInfo :: Maybe Bool
vpConflicts :: Maybe Bool
vpDescending :: Maybe Bool
vpEndKey :: Maybe Text
vpEndKeyDocId :: Maybe DocId
vpGroup :: Maybe Bool
vpGroupLevel :: Maybe Int
vpIncludeDocs :: Maybe Bool
vpInclusiveEnd :: Maybe Bool
vpKey :: Maybe Text
vpLimit :: Maybe Int
vpReduce :: Maybe Bool
vpSkip :: Maybe Int
vpStale :: Maybe Bool
vpStartKey :: Maybe Text
vpStartKeyDocId :: Maybe DocId
vpUpdateSeq :: Maybe Bool

Instances

ToQueryParameters ViewParams

Convert to query parameters

viewParams :: ViewParams Source

The default (empty) parameters

Results of a request

type Result a = Either Error (a, Maybe CookieJar) Source

Calls in the Explicit interface will always return a Result, so we make it easy to type here.

Some success values

data CreateResult Source

Result type for creating a new document in a database.

Constructors

NoRev DocId	In batch mode, you don't get a rev back
WithRev DocId DocRev	Otherwise, you do get the rev back for your doc

Error values These will come to cover the gamut from failure to parse a particular JSON value to document conflicts. We try to differentiate in useful ways without being slavish about it.

data Error Source

These represent Failure modes for making CouchDB requests.

Constructors

AlreadyExists	The database already exists
Conflict	The document already exists, and without the appropriate rev
HttpError HttpException	The server complained about the content of our request. Sounds like the library is broken. :(
ImplementationError Text	The server complained about the content of our request. Sounds like the library is broken. :(
InvalidName Text	The name you tried to give for the DB is invalid
NotFound	The thing you were looking for was not found
ParseIncomplete	We ran out of input before we succeeded in parsing a JSON `Value`.
ParseFail Text	There was some sort of syntactic issue with the text we were attempting to parse.
Unauthorized	The credentials you used do not have access to this resource
Unknown	Don't understand the failure

Instances

Show Error