Arcana.CollectionScope (Arcana v4.0.0)

Represents the collections included in a read.

Public inputs are normalized before they reach query code:

:all includes every collection
a collection name includes only that collection
a list of names includes those collections
an empty list matches no collections

Collection names must be non-empty binaries. Normalization preserves their order while removing duplicates.

Summary

Functions

from_opts(opts, default)

Reads a collection scope from keyword options.

from_opts!(opts, default)

Reads and normalizes a collection scope from options or raises ArgumentError.

intersect(scope, scope)

Returns the intersection of two normalized collection scopes.

normalize(name)

Normalizes a public collection scope.

normalize!(input)

Normalizes a collection scope or raises ArgumentError.

subset?(arg1, arg2)

Returns whether every collection in scope is included in allowed.

Types

error_reason()

@type error_reason() ::
  {:invalid_collection_scope, term()} | {:unsupported_collection_option, atom()}

input()

@type input() :: :all | name() | [name()]

name()

@type name() :: String.t()

t()

@type t() :: :all | {:only, [name()]}

Functions

from_opts(opts, default)

@spec from_opts(
  keyword(),
  input()
) :: {:ok, t()} | {:error, error_reason()}

Reads a collection scope from keyword options.

The :collection option accepts every public scope shape. When it is absent, default is normalized instead. The removed :collections alias is rejected so an outdated scoped caller cannot silently widen to the default.

from_opts!(opts, default)

@spec from_opts!(
  keyword(),
  input()
) :: t()

Reads and normalizes a collection scope from options or raises ArgumentError.

intersect(scope, scope)

@spec intersect(t(), t()) :: t()

Returns the intersection of two normalized collection scopes.

When both scopes list names, their order follows the first scope.

normalize(name)

@spec normalize(term()) :: {:ok, t()} | {:error, error_reason()}

Normalizes a public collection scope.

Returns {:error, {:invalid_collection_scope, input}} when a name is blank or an input has an unsupported shape.

normalize!(input)

@spec normalize!(term()) :: t()

Normalizes a collection scope or raises ArgumentError.

subset?(arg1, arg2)

@spec subset?(t(), t()) :: boolean()

Returns whether every collection in scope is included in allowed.

This is useful at authorization boundaries where silently intersecting an explicit request would accept only part of a forged scope.