Scrypath.Composition (scrypath v0.3.7)

Copy Markdown View Source

Public plain-data composition seam for reusable search presets and additive scopes.

Host apps define feature-level or context-owned fragments such as %{defaults: ...} and %{fixed: ...}. This module composes those fragments into the same plain-data criteria vocabulary already accepted by Scrypath.search/3.

Scrypath.Composition is data-only:

  • it never executes search
  • it never exposes %Scrypath.Query{}
  • it does not move composition ownership onto schemas or Scrypath.Phoenix

The composed result stays a plain map that includes final criteria plus coarse visibility buckets: applied, defaulted, fixed, and optional sources or warnings.

Summary

Types

criteria()

Caller-facing criteria vocabulary aligned with Scrypath.search/3.

fixed_criteria()

Allowed fragment fixed constraints for filter-bearing fields only.

fragment()

Public fragment envelope used to compose presets and scopes.

fragment_criteria()

Allowed fragment defaults for all public search fields.

many_entry_spec()

Public multi-search entry spec consumed by compose_many/2.

many_result()

Public multi-search composition result. Shared composition lowers defaults only, per-entry composition stays canonical, and to_search_many_args/1 emits the existing tuple/shared-option contract for Scrypath.search_many/2.

result()

Stable public result returned by compose/2.

Functions

compose(fragments, criteria \\ %{})

Composes one fragment or a list of fragments with caller criteria.

compose!(fragments, criteria \\ %{})

Like compose/2, but raises ArgumentError instead of returning {:error, reason}.

compose_many(entries, opts \\ [])

Composes multi-search entries into the existing tuple/shared-option contract.

compose_many!(entries, opts \\ [])

Like compose_many/2, but raises ArgumentError instead of returning {:error, reason}.

to_search_args(composition)

Converts the composed plain-data result into {text, keyword_opts} for a context-owned Scrypath.search/3 call.

to_search_many_args(composition)

Lowers a multi-search composition result into {entries, shared_opts} for a context-owned Scrypath.search_many/2 call.

Types

criteria()

@type criteria() :: %{
  optional(:text) => String.t(),
  optional(:filter) => keyword(),
  optional(:sort) => keyword(),
  optional(:page) => keyword(),
  optional(:facets) => [atom()],
  optional(:facet_filter) => keyword(),
  optional(:per_query) => map()
}

Caller-facing criteria vocabulary aligned with Scrypath.search/3.

fixed_criteria()

@type fixed_criteria() :: %{
  optional(:filter) => keyword(),
  optional(:facet_filter) => keyword()
}

Allowed fragment fixed constraints for filter-bearing fields only.

fragment()

@type fragment() :: %{
  optional(:defaults) => fragment_criteria(),
  optional(:fixed) => fixed_criteria(),
  optional(:sources) => map(),
  optional(:warnings) => map()
}

Public fragment envelope used to compose presets and scopes.

fragment_criteria()

@type fragment_criteria() :: criteria()

Allowed fragment defaults for all public search fields.

many_entry_spec()

@type many_entry_spec() :: %{
  :schema => module() | :all,
  :text => String.t(),
  optional(:fragments) => fragment() | [fragment()],
  optional(:criteria) => criteria()
}

Public multi-search entry spec consumed by compose_many/2.

many_result()

@type many_result() :: %{shared: result(), entries: [map()]}

Public multi-search composition result. Shared composition lowers defaults only, per-entry composition stays canonical, and to_search_many_args/1 emits the existing tuple/shared-option contract for Scrypath.search_many/2.

result()

@type result() :: Scrypath.Composition.Result.t()

Stable public result returned by compose/2.

Functions

compose(fragments, criteria \\ %{})

@spec compose(fragment() | [fragment()], criteria()) ::
  {:ok, result()} | {:error, term()}

Composes one fragment or a list of fragments with caller criteria.

compose!(fragments, criteria \\ %{})

@spec compose!(fragment() | [fragment()], criteria()) :: result()

Like compose/2, but raises ArgumentError instead of returning {:error, reason}.

compose_many(entries, opts \\ [])

@spec compose_many(
  [many_entry_spec() | tuple()],
  keyword()
) :: {:ok, many_result()} | {:error, term()}

Composes multi-search entries into the existing tuple/shared-option contract.

Shared composition lowers defaults only. Shared fixed constraints are not supported, and multi-search-only rails such as federation weights or max_schemas stay outside this helper.

compose_many!(entries, opts \\ [])

@spec compose_many!(
  [many_entry_spec() | tuple()],
  keyword()
) :: many_result()

Like compose_many/2, but raises ArgumentError instead of returning {:error, reason}.

to_search_args(composition)

@spec to_search_args(result()) :: {String.t(), keyword()}

Converts the composed plain-data result into {text, keyword_opts} for a context-owned Scrypath.search/3 call.

to_search_many_args(composition)

@spec to_search_many_args(many_result()) :: {list(), keyword()}

Lowers a multi-search composition result into {entries, shared_opts} for a context-owned Scrypath.search_many/2 call.