@spec attach(t(), String.t(), binary(), keyword()) :: t()

Attaches content to a document, to be saved inline with it. The content type comes from the name unless given, see Sofa.Attachment.new/3.

Sofa.Doc.new("recipe")
|> Sofa.Doc.attach("recipe.txt", "1. Cook spaghetti")
|> Sofa.Doc.attach("photo", photo_bytes, content_type: "image/jpeg")
|> Sofa.Doc.save(db)

@spec coerce_to_elixir_type(String.t()) :: atom()

Coerces a CouchDB "type" field to an existing atom. It is assumed that there will be a related Elixir Module Type of the same name. Elixir prefixes Module names with Elixir. and then elides this in iex, tests, and elsewhere, but here we need to make that explicit.

The "user" type is special-cased as it is already present in CouchDB /_users database.

This function is expected to be paired up with Ecto Schemas to properly manage the appropriate fields in your document body.

@spec delete(Sofa.t(), t()) :: :ok | {:error, any()}

delete doc

@spec detach(t(), String.t()) :: t()

Removes an attachment from a document. CouchDB deletes it when the document is next saved without its stub.

@spec exists(Sofa.t(), String.t()) :: {:error, any()} | {:ok, t()}

Check if doc exists via HEAD /:db/:doc and returns either:

• {:error, not_found} # doc doesn't exist
• {:ok, %Sofa.Doc{}} # doc exists and has metadata

@spec exists?(Sofa.t(), String.t()) :: false | true

Check if doc exists via HEAD /:db/:doc and returns either true or false

@spec from_map(map()) :: t()

Converts CouchDB-native JSON-friendly map to internal %Sofa.Doc{} format

Examples

  iex> %{ "_id" => "smol", "_rev" => "1-cute", "yes" => true}
      |> from_map()

  %Sofa.Doc{
    attachments: nil,
    body: %{"yes" => true},
    id: "smol",
    rev: "1-cute",
    type: nil
  }

@spec get(Sofa.t(), String.t(), keyword()) :: {:error, any()} | t()

GET doc and returns standard HTTP status, or the requested doc

• {:error, :not_found} # doc doesn't exist, or similar HTTP status
• %Sofa.Doc{} # doc exists and has metadata

Options

The attachment-related query parameters of the CouchDB document API:

• attachments: true fetches attachment content inline, so each %Sofa.Attachment{} in attachments carries its data

• att_encoding_info: true adds encoding and encoded_length to the stubs of attachments CouchDB stored compressed

• atts_since: [revs] fetches content only for attachments added after the given revisions, as used when syncing

  Sofa.Doc.get(db, "SpaghettiWithMeatballs", attachments: true)

@spec get!(Sofa.t(), String.t(), keyword()) :: t()

Bang! version of get/3. Returns the document or raises Sofa.Error. Lets a pipeline start from a fetched document.

Sofa.Doc.get!(db, "SpaghettiWithMeatballs") |> Sofa.Doc.attach("photo.jpg", bytes) |> Sofa.Doc.save!(db)

@spec new(String.t() | %{id: String.t(), body: map()} | %{id: String.t()}) :: t()

Creates a new (empty) document

@spec put(Sofa.t(), t()) :: {:ok, t()} | {:error, any()}

Optimistically write/update doc assuming rev matches

@spec save(t(), Sofa.t()) :: {:ok, t()} | {:error, any()}

Saves a document, with the document first so it can end a pipeline that builds it. The same as put/2 otherwise.

Sofa.Doc.new(%{id: "smol", body: %{"cute" => true}}) |> Sofa.Doc.save(db)
#=> {:ok, %Sofa.Doc{id: "smol", rev: "1-..."}}

@spec save!(t(), Sofa.t()) :: t()

Bang! version of save/2. Returns the saved document, with its new rev, or raises Sofa.Error. Lets a pipeline carry on with the saved document.

doc = Sofa.Doc.new("smol") |> Sofa.Doc.save!(db)

@spec to_map(t()) :: map()

Converts internal %Sofa.Doc{} format to CouchDB-native JSON-friendly map

Examples

  iex> %Sofa.Doc{id: "smol", rev: "1-cute", body: %{"yes" => true}}
    |> to_map()

  %{ "_id" => "smol", "_rev" => "1-cute", "yes" => true}