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

Functions

Internal function to build a db endpoint.

Deletes an option in changes.

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

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

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

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

Adds or updates a single option in changes.

Replaces changes's options with the given ones.

Resets changes back to the "unfetched" state.

Link to this section Types

Link to this type

changes_option_key()

View Source
changes_option_key() ::
  :doc_ids
  | :conflicts
  | :descending
  | :filter
  | :include_docs
  | :attachments
  | :att_encoding_info
  | :limit
  | :since
  | :style
  | :view
Link to this type

changes_option_value()

View Source
changes_option_value() ::
  boolean() | String.t() | integer() | [String.t()] | :main_only | :all_docs
Link to this type

t()

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

Link to this section Functions

Link to this function

db_endpoint(changes)

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

Internal function to build a db endpoint.

Link to this function

delete_option(changes, key)

View Source
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").

Link to this function

fetch(changes)

View Source
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.

Link to this function

fetch!(changes)

View Source
fetch!(changes :: t()) :: t()

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

Link to this function

fetched?(changes)

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

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

Link to this function

get_option(changes, key)

View Source
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.

Link to this function

put_option(changes, key, value)

View Source
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.

Link to this function

set_options(changes, options)

View Source
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.

Link to this function

unfetch(changes)

View Source
unfetch(changes :: t()) :: t()

Resets changes back to the "unfetched" state.

This will also reset the last_seq to nil.