ICouch v0.6.2 ICouch.Changes View Source

Module to handle changes feeds in CouchDB.

Changes structs should not be created or manipulated directly, please use ICouch.open_changes/2.

Similar to a view, a changes feed can be in a "fetched" state or in an "unfetched" state which can be tested with the fetched?/1 function and changed with the fetch/1, fetch!/1 and unfetch/1 function. In contrast to a view, the sequence number is updated on each fetch so a consecutive fetch will start off at the last sequence number.

The changes struct implements the enumerable protocol for easy handling with Elixir's Enum module - however, this only works with fetched changes and will fail with an ArgumentError otherwise.

Link to this section Summary

Types

changes_option_key()

changes_option_value()

t()

Functions

db_endpoint(changes)

Internal function to build a db endpoint.

delete_option(changes, key)

Deletes an option in changes.

fetch(changes)

Fetches all results of changes, turning it into a "fetched changes feed".

fetch!(changes)

Same as fetch/1 but returns the fetched changes feed directly on success or raises an error on failure.

fetched?(changes)

Tests whether changes is in "fetched" state or not.

get_option(changes, key)

Returns the value of an option in changes or nil if it was not set.

put_option(changes, key, value)

Adds or updates a single option in changes.

set_options(changes, options)

Replaces changes's options with the given ones.

unfetch(changes)

Resets changes back to the "unfetched" state.

Link to this section Types

changes_option_key()

changes_option_key() ::
  :doc_ids
  | :conflicts
  | :descending
  | :filter
  | :include_docs
  | :attachments
  | :att_encoding_info
  | :limit
  | :since
  | :style
  | :view

changes_option_value()

changes_option_value() ::
  boolean() | String.t() | integer() | [String.t()] | :main_only | :all_docs

t()

t() :: %ICouch.Changes{
  db: ICouch.DB.t(),
  last_seq: String.t() | integer() | nil,
  params: map(),
  results: [map()] | nil
}

Link to this section Functions

db_endpoint(changes)

db_endpoint(changes :: t()) :: {String.t(), map()}

Internal function to build a db endpoint.

delete_option(changes, key)

delete_option(changes :: t(), key :: changes_option_key()) :: t()

Deletes an option in changes.

This will also set the changes feed back to the "unfetched" state.

Returns changes unchanged if the option was not set (and it already was "unfetched").

fetch(changes)

fetch(changes :: t()) :: {:ok, t()} | {:error, term()}

Fetches all results of changes, turning it into a "fetched changes feed".

The last sequence number will be set and used as next "since" parameter.

fetch!(changes)

fetch!(changes :: t()) :: t()

Same as fetch/1 but returns the fetched changes feed directly on success or raises an error on failure.

fetched?(changes)

fetched?(changes :: t()) :: boolean()

Tests whether changes is in "fetched" state or not.

get_option(changes, key)

get_option(changes :: t(), key :: changes_option_key()) ::
  changes_option_value() | nil

Returns the value of an option in changes or nil if it was not set.

The last_seq value can be retrieved with the since option.

put_option(changes, key, value)

put_option(
  changes :: t(),
  key :: changes_option_key(),
  value :: changes_option_value()
) :: t()

Adds or updates a single option in changes.

This will also set the changes feed back to the "unfetched" state. To modify the last_seq value, set the since option.

Note that when setting the doc_ids option, any given filter option will be ignored while fetching changes.

set_options(changes, options)

set_options(changes :: t(), options :: [ICouch.open_changes_option()]) ::
  t()

Replaces changes's options with the given ones.

This set the changes feed back to the "unfetched" state, but leaves the last_seq value untouched unless since is given as option.

Note that when setting the doc_ids option, any given filter option will be ignored while fetching changes.

unfetch(changes)

unfetch(changes :: t()) :: t()

Resets changes back to the "unfetched" state.

This will also reset the last_seq to nil.