# `Sofa.Design`
[🔗](https://github.com/skunkwerks/sofa/blob/0.8.1/lib/sofa/design.ex#L1)

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")

# `error`

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

# `all`

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

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

# `filter`

```elixir
@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`

```elixir
@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!`

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

Bang! version of `get/3`.

# `info`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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"`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
