couch-simple-0.0.1.0: A modern, lightweight, complete client for CouchDB

CopyrightCopyright (c) 2015, Michael Alan Dorman
LicenseMIT
Maintainermdorman@jaunder.io
Stabilityexperimental
PortabilityPOSIX
Safe HaskellNone
LanguageHaskell2010

Database.Couch.Explicit.Database

Contents

Description

This module is intended to be import qualified. No attempt has been made to keep names of types or functions from clashing with obvious or otherwise commonly-used names, or even other modules within this package.

The functions here are derived from (and presented in the same order as) the Database API documentation. For each function, we attempt to link back to the original documentation, as well as make a notation as to how complete and correct we feel our implementation is.

Each function takes a Context---which, among other things, holds the name of the database---as its final parameter, and returns a Result.

Synopsis

Documentation

exists :: (FromJSON a, MonadIO m) => Context -> m (Result a) Source

Check that the requested database exists

The return value is an object that should only contain a single key "ok", so it is easily decoded into a Bool with our asBool combinator:

>>> value :: Result Bool <- Database.exists ctx >>= asBool

Status: Complete

meta :: (FromJSON a, MonadIO m) => Context -> m (Result a) Source

Get most basic meta-information

The return value is an object whose fields often vary, so it is most easily decoded as a Value:

>>> value :: Result Value <- Database.meta ctx

Status: Complete

create :: (FromJSON a, MonadIO m) => Context -> m (Result a) Source

Create a database

The return value is an object whose fields often vary, so it is most easily decoded as a Value:

>>> value :: Result Value <- Database.meta ctx

Status: Complete

delete :: (FromJSON a, MonadIO m) => Context -> m (Result a) Source

Delete a database

The return value is an object that should only contain a single key "ok", so it is easily decoded into a Bool with our asBool combinator:

>>> value :: Result Bool <- Database.delete ctx >>= asBool

Status: Complete

createDoc Source

Arguments

:: (FromJSON a, MonadIO m, ToJSON b) 
=> Bool

Whether to create the document in batch mode

-> b

The document to create

-> Context 
-> m (Result a) 

Create a new document in a database

The return value is an object that can hold "id" and "rev" keys, but if you don't need those values, it is easily decoded into a Bool with our asBool combinator:

>>> value :: Result Bool <- Database.createDoc True someObject ctx >>= asBool

Status: Complete

allDocs Source

Arguments

:: (FromJSON a, MonadIO m) 
=> DbAllDocs

Parameters governing retrieval (dbAllDocs is an empty default)

-> Context 
-> m (Result a) 

Get a list of all database documents

The return value is a list of objects whose fields often vary, so it is easily decoded as a List of Value:

>>> value :: Result [Value] <- Database.allDocs dbAllDocs ctx

Status: Complete

someDocs Source

Arguments

:: (FromJSON a, MonadIO m) 
=> DbAllDocs

Parameters governing retrieval (dbAllDocs is an empty default)

-> [DocId]

List of ids documents to retrieve

-> Context 
-> m (Result a) 

Get a list of some database documents

The return value is a list of objects whose fields often vary, so it is easily decoded as a List of Value:

>>> value :: Result [Value] <- Database.someDocs ["a", "b", "c"] ctx

Status: Complete

bulkDocs Source

Arguments

:: (FromJSON a, MonadIO m, ToJSON a) 
=> DbBulkDocs

Parameters coverning retrieval (dbBulkDocs is an empty default)

-> [a]

List of documents to add or update

-> Context 
-> m (Result a) 

Create or update a list of documents

The return value is a list of objects whose fields often vary, so it is easily decoded as a List of Value:

>>> value :: Result [Value] <- Database.bulkDocs dbBulkDocs ["a", "b", "c"] ctx

Status: Complete

changes Source

Arguments

:: (FromJSON a, MonadIO m) 
=> DbChanges

Arguments governing changes contents (dbChanges is an empty default)

-> Context 
-> m (Result a) 

Get a list of all document modifications

This call does not stream out results; so while it allows you to specify parameters for streaming, it's a dirty, dirty lie.

The return value is an object whose fields often vary, so it is most easily decoded as a Value:

>>> value :: Result Value <- Database.changes ctx

Status: Limited

compact :: (FromJSON a, MonadIO m) => Context -> m (Result a) Source

Compact a database

The return value is an object that should only contain a single key "ok", so it is easily decoded into a Bool with our asBool combinator:

>>> value :: Result Bool <- Database.compact ctx >>= asBool

Status: Complete

compactDesignDoc Source

Arguments

:: (FromJSON a, MonadIO m) 
=> DocId

The DocId of the design document to compact

-> Context 
-> m (Result a) 

Compact the views attached to a particular design document

The return value is an object that should only contain a single key "ok", so it is easily decoded into a Bool with our asBool combinator:

>>> value :: Result Bool <- Database.compactDesignDoc "ddoc" ctx >>= asBool

Status: Complete

sync :: (FromJSON a, MonadIO m) => Context -> m (Result a) Source

Ensure that all changes to the database have made it to disk

The return value is an object that can hold an "instance_start_time" key, but if you don't need those values, it is easily decoded into a Bool with our asBool combinator:

>>> value :: Result Bool <- Database.sync ctx >>= asBool

Status: Complete

cleanup :: (FromJSON a, MonadIO m) => Context -> m (Result a) Source

Cleanup any stray view definitions

The return value is an object that should only contain a single key "ok", so it is easily decoded into a Bool with our asBool combinator:

>>> value :: Result Bool <- Database.cleanup ctx >>= asBool

Status: Complete

getSecurity :: (FromJSON a, MonadIO m) => Context -> m (Result a) Source

Get security information for database

The return value is an object that has with a standard set of fields ("admin" and "members" keys, which each contain "users" and "roles"), the system does not prevent you from adding (and even using in validation functions) additional fields, so it is most easily decoded as a Value:

>>> value :: Result Value <- Database.getSecurity ctx

Status: Complete

setSecurity Source

Arguments

:: (FromJSON b, MonadIO m, ToJSON a) 
=> a

The security document content

-> Context 
-> m (Result b) 

Set security information for database

The input value is an object that has with a standard set of fields ("admin" and "members" keys, which each contain "users" and "roles"), but the system does not prevent you from adding (and even using in validation functions) additional fields, so we don't specify a specific type, and you can roll your own:

The return value is an object that should only contain a single key "ok", so it is easily decoded into a Bool with our asBool combinator:

>>> value :: Result Value <- Database.setSecurity (object [("users", object [("harry")])]) ctx >>= asBool

Status: Complete

tempView Source

Arguments

:: (FromJSON a, MonadIO m) 
=> Text

The text of your map function

-> Maybe Text

The text of your optional reduce function

-> Context 
-> m (Result a) 

Create a temporary view

The return value is an object whose fields often vary, so it is most easily decoded as a Value:

>>> value :: Result Value <- Database.tempView "function (doc) { emit (1); }" (Just "_count") Nothing ctx

Status: Complete

purge Source

Arguments

:: (FromJSON a, MonadIO m) 
=> DocRevMap

A DocRevMap of documents and versions to purge

-> Context 
-> m (Result a) 

Purge document revisions from the database

The return value is an object with two fields "purge_seq" and "purged", which contains an object with no fixed keys, so it is most easily decoded as a Value:

>>> value :: Result Value <- Database.purge $ DocRevMap [(DocId "junebug", [DocRev "1-1"])] Nothing ctx

However, the content of "purged" is effectively a DocRevMap, so the output can be parsed into an (Int, DocRevMap) pair using:

>>> (,) <$> (getKey "purge_seq" >>= toOutputType) <*> (getKey "purged" >>= toOutputType)

Status: Complete

missingRevs Source

Arguments

:: (FromJSON a, MonadIO m) 
=> DocRevMap

A DocRevMap of documents and versions available

-> Context 
-> m (Result a) 

Find document revisions not present in the database

The return value is an object with one field "missed_revs", which contains an object with no fixed keys, so it is most easily decoded as a Value:

>>> value :: Result Value <- Database.missingRevs $ DocRevMap [(DocId "junebug", [DocRev "1-1"])] ctx

However, the content of "missed_revs" is effectively a DocRevMap, so it can be parsed into a DocRevMap using:

>>> getKey "missed_revs" >>= toOutputType

Status: Complete

revsDiff Source

Arguments

:: (FromJSON a, MonadIO m) 
=> DocRevMap

A DocRevMap of documents and versions available

-> Context 
-> m (Result a) 

Find document revisions not present in the database

The return value is an object whose fields often vary, so it is most easily decoded as a Value:

>>> value :: Result Value <- Database.revsDiff $ DocRevMap [(DocId "junebug", [DocRev "1-1"])] ctx

Status: Complete

getRevsLimit :: (FromJSON a, MonadIO m) => Context -> m (Result a) Source

Get the revision limit setting

The return value is a JSON numeric value that can easily be decoded to an Int:

>>> value :: Result Integer <- Database.getRevsLimit ctx

Status: Complete

setRevsLimit Source

Arguments

:: (FromJSON a, MonadIO m) 
=> Int

The value at which to set the limit

-> Context 
-> m (Result a) 

Set the revision limit

Status: Complete

Internal combinators

allDocsBase :: ToQueryParameters a => a -> RequestBuilder () Source

Base bits for all _all_docs requests

compactBase :: RequestBuilder () Source

Base bits for all our _compact requests

docRevBase :: ToJSON a => a -> RequestBuilder () Source

Base bits for our revision examination functions

revsLimitBase :: RequestBuilder () Source

Base bits for our revisions limit functions

securityBase :: RequestBuilder () Source

Base bits for our security functions