Sofa.Design (sofa v0.7.0)

Copy Markdown View Source

Design documents: the _design/ documents that hold views, filters and validation functions, built as pipelines and saved like any document.

If the only tool you have is CouchDB, then everything looks like {:ok, :relax}

See https://docs.couchdb.org/en/stable/api/ddoc/common.html and the design documents guide. A design document is an ordinary %Sofa.Doc{} whose id starts with _design/, so Sofa.Doc.save/2, Sofa.Doc.get/3 and Sofa.Attachment all apply. This module builds them and reads their index information.

Examples

JavaScript functions are written with the ~JS sigil, see sigil_JS/2:

import Sofa.Design, only: [sigil_JS: 2]

by_title = ~JS"""
function(doc) {
  if (doc.title) emit(doc.title, null);
}
"""

by_ingredient = ~JS"""
function(doc) {
  doc.ingredients.forEach(function(i) { emit(i, 1); });
}
"""

validate = ~JS"""
function(newDoc, oldDoc, userCtx) {
  if (!newDoc.title) throw({forbidden: 'needs a title'});
}
"""

Sofa.Design.new("recipes")
|> Sofa.Design.view("by_title", by_title)
|> Sofa.Design.view("by_ingredient", by_ingredient, "_sum")
|> Sofa.Design.filter("important", ~JS"function(doc, req) { return doc.important === true; }")
|> Sofa.Design.validate(validate)
|> Sofa.Doc.save(db)

{:ok, %{"name" => "recipes", "view_index" => %{"language" => "javascript"}}} = Sofa.Design.info(db, "recipes")
Sofa.View.query(db, "recipes", "by_title")

Summary

Functions

Every design document of the database, as %Sofa.Doc{} structs.

Adds a filter function, for Sofa.Changes and replication with filter: "{name}/{filter}".

Fetches a design document by name, with or without the _design/ prefix.

The index information of a design document, via _info: its name and a "view_index" map with the signature, sizes, update sequence and whether an update or compaction is running, as documented.

A new design document named _design/{name}, in JavaScript unless language: says otherwise. Further options go into the body as given: views:, filters:, updates:, validate_doc_update:, options:, autoupdate:.

A JavaScript function as a string, for views, filters, updates and validation. Nothing is interpolated or escaped, so the function reads exactly as CouchDB will store it.

Adds an update function, as called via /{db}/_design/{ddoc}/_update/{name}.

Sets the validate_doc_update function, which CouchDB runs on every write to the database.

Adds a view with a map function and, optionally, a reduce function such as "_sum".

Types

error()

@type error() :: Sofa.Response.error() | term()

Functions

all(sofa)

@spec all(Sofa.t()) :: {:ok, [Sofa.Doc.t()]} | {:error, error()}

Every design document of the database, as %Sofa.Doc{} structs.

filter(doc, name, fun)

@spec filter(Sofa.Doc.t(), String.t(), String.t()) :: Sofa.Doc.t()

Adds a filter function, for Sofa.Changes and replication with filter: "{name}/{filter}".

get(sofa, name, opts \\ [])

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

Fetches a design document by name, with or without the _design/ prefix.

get!(sofa, name, opts \\ [])

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

Bang! version of get/3.

info(sofa, name)

@spec info(Sofa.t(), String.t()) :: {:ok, map()} | {:error, error()}

The index information of a design document, via _info: its name and a "view_index" map with the signature, sizes, update sequence and whether an update or compaction is running, as documented.

new(name, opts \\ [])

@spec new(String.t(), keyword()) :: Sofa.Doc.t()

A new design document named _design/{name}, in JavaScript unless language: says otherwise. Further options go into the body as given: views:, filters:, updates:, validate_doc_update:, options:, autoupdate:.

sigil_JS(javascript, list)

@spec sigil_JS(String.t(), []) :: String.t()

A JavaScript function as a string, for views, filters, updates and validation. Nothing is interpolated or escaped, so the function reads exactly as CouchDB will store it.

import Sofa.Design, only: [sigil_JS: 2]

~JS"""
function(doc) {
  if (doc.title) emit(doc.title, null);
}
"""

The single-line form ~JS"function(doc) { emit(doc._id, 1); }" suits short functions. The sigil takes no modifiers.

update(doc, name, fun)

@spec update(Sofa.Doc.t(), String.t(), String.t()) :: Sofa.Doc.t()

Adds an update function, as called via /{db}/_design/{ddoc}/_update/{name}.

validate(doc, fun)

@spec validate(Sofa.Doc.t(), String.t()) :: Sofa.Doc.t()

Sets the validate_doc_update function, which CouchDB runs on every write to the database.

view(doc, name, map, reduce \\ nil)

@spec view(Sofa.Doc.t(), String.t(), String.t(), String.t() | nil) :: Sofa.Doc.t()

Adds a view with a map function and, optionally, a reduce function such as "_sum".