ecoportal-api-graphql 1.3.10 → 1.3.12

data/lib/ecoportal/api/graphql/input/search_conf.rb

@@ -1,367 +1,436 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Input
-        # Builder for the searchConf hash argument used by pages, contractorEntities,
-        # personMembers, and other paginated queries.
-        #
-        # Usage:
-        #   conf = SearchConf.new
-        #     .filter(SearchConf::Exact.new(:external_id, 'ABC'))
-        #     .sort(:created_at, :desc)
-        #
-        #   # OR filter (find by one of several externalIds)
-        #   conf = SearchConf.new.filter(
-        #     SearchConf::Or.new(
-        #       SearchConf::Exact.new(:external_id, '1111'),
-        #       SearchConf::Exact.new(:external_id, '2222')
-        #     )
-        #   )
-        #
-        #   # Parametrize — reuse the same structure with a different value
-        #   base = SearchConf.new.filter(SearchConf::Exact.new(:external_id, 'X'))
-        #   copy = base.with(external_id: 'Y')
-        #
-        #   # Pass to any query:
-        #   org.pages(searchConf: conf.to_h, first: 10)
-        #
-        # Filter operations (snake_case — CamelCase silently returns no results):
-        #   SearchConf::Exact     — exact_filter
-        #   SearchConf::DateRange — date_filter
-        #   SearchConf::Register  — register_filter (org search only)
-        #   SearchConf::And       — and_filter (explicit AND group)
-        #   SearchConf::Or        — or_filter
-        class SearchConf
-          # ---------------------------------------------------------------------------
-          # AI-assisted filter generation (optional — requires 'anthropic' gem)
-          # ---------------------------------------------------------------------------
-          class << self
-            # Build a SearchConf from a natural-language description using Claude.
-            # See SearchConf::AIGenerator for full documentation and options.
-            #
-            # Usage:
-            #   require 'anthropic'
-            #   conf = SearchConf.from_description(
-            #     "active pages in Safety register updated this month",
-            #     register_id: 'REG_123'
-            #   )
-            def from_description(text, **opts)
-              require_relative 'search_conf/ai_generator'
-              AIGenerator.from_description(text, **opts)
-            end
-          end
-
-          # ---------------------------------------------------------------------------
-          # Composable — adds & and | operators to filter classes so they can be
-          # combined using natural Ruby operator syntax:
-          #   filter1 & filter2  →  SearchConf::And.new(filter1, filter2)
-          #   filter1 | filter2  →  SearchConf::Or.new(filter1, filter2)
-          # ---------------------------------------------------------------------------
-          module Composable
-            def &(other)
-              SearchConf::And.new(self, other)
-            end
-
-            def |(other)
-              SearchConf::Or.new(self, other)
-            end
-          end
-
-          # ---------------------------------------------------------------------------
-          # Filter: exact_filter
-          # ---------------------------------------------------------------------------
-          class Exact
-            include Composable
-
-            OPERATION = 'exact_filter'.freeze
-
-            def initialize(key, value)
-              @key   = key.to_s
-              @value = value
-            end
-
-            def to_h
-              { operation: OPERATION, params: { key: @key, value: @value } }
-            end
-
-            def substitute(subs)
-              key_sym = @key.to_sym
-              return self unless subs.key?(key_sym)
-
-              self.class.new(@key, subs[key_sym])
-            end
-          end
-
-          # ---------------------------------------------------------------------------
-          # Filter: date_filter
-          # ---------------------------------------------------------------------------
-          class DateRange
-            include Composable
-
-            OPERATION = 'date_filter'.freeze
-
-            def initialize(key, gte: nil, lte: nil, time_zone: 'UTC')
-              @key       = key.to_s
-              @gte       = gte
-              @lte       = lte
-              @time_zone = time_zone
-            end
-
-            def to_h
-              params = { key: @key, time_zone: @time_zone }
-              params[:gte] = @gte if @gte
-              params[:lte] = @lte if @lte
-              { operation: OPERATION, params: params }
-            end
-
-            def substitute(subs)
-              self.class.new(
-                @key,
-                gte:       subs.fetch(:gte, @gte),
-                lte:       subs.fetch(:lte, @lte),
-                time_zone: subs.fetch(:time_zone, @time_zone)
-              )
-            end
-          end
-
-          # ---------------------------------------------------------------------------
-          # Filter: register_filter (org search only — scope to specific registers)
-          # ---------------------------------------------------------------------------
-          class Register
-            include Composable
-
-            OPERATION = 'register_filter'.freeze
-
-            def initialize(*ids)
-              @ids = ids.flatten
-            end
-
-            def to_h
-              { operation: OPERATION, params: { ids: @ids } }
-            end
-
-            def substitute(subs)
-              self.class.new(*Array(subs.fetch(:register_ids, @ids)))
-            end
-          end
-
-          # ---------------------------------------------------------------------------
-          # Filter: and_filter (explicit AND group; top-level filters array is implicit AND)
-          # ---------------------------------------------------------------------------
-          class And
-            include Composable
-
-            OPERATION = 'and_filter'.freeze
-
-            def initialize(*filters)
-              @filters = filters.flatten
-            end
-
-            def to_h
-              { operation: OPERATION, params: { filters: @filters.map(&:to_h) } }
-            end
-
-            def substitute(subs)
-              self.class.new(*@filters.map { |f| f.respond_to?(:substitute) ? f.substitute(subs) : f })
-            end
-          end
-
-          # ---------------------------------------------------------------------------
-          # Filter: or_filter
-          # ---------------------------------------------------------------------------
-          class Or
-            include Composable
-
-            OPERATION = 'or_filter'.freeze
-
-            def initialize(*filters)
-              @filters = filters.flatten
-            end
-
-            def to_h
-              { operation: OPERATION, params: { filters: @filters.map(&:to_h) } }
-            end
-
-            def substitute(subs)
-              self.class.new(*@filters.map { |f| f.respond_to?(:substitute) ? f.substitute(subs) : f })
-            end
-          end
-
-          # ---------------------------------------------------------------------------
-          # RawFilter — escape hatch for operations not yet wrapped as SearchConf classes.
-          # Supports & and | composition just like the typed filter classes.
-          # Usage:
-          #   SearchConf.new.filter(SearchConf::RawFilter.new('has_any_filter', key: 'external_id'))
-          # ---------------------------------------------------------------------------
-          class RawFilter
-            include Composable
-
-            def initialize(operation, **params)
-              @operation = operation
-              @params    = params
-            end
-
-            def to_h
-              { 'operation' => @operation, 'params' => @params.transform_keys(&:to_s) }
-            end
-
-            def substitute(_subs)
-              self
-            end
-          end
-
-          # ---------------------------------------------------------------------------
-          # Fluent DSL class methods — factory for filter expressions.
-          #
-          # SearchConf[:field]  →  FieldRef (then call .eq, .since, .matches, etc.)
-          # SearchConf.in_register(id)  →  Register filter
-          # SearchConf.raw(op, **params)  →  RawFilter
-          #
-          # Examples:
-          #   SearchConf[:external_id].eq('ABC')
-          #   SearchConf[:state].is(:active)
-          #   SearchConf[:updated_at].since('2025-01-01T00:00:00Z')
-          #   SearchConf[:state].is(:active) & SearchConf.in_register('REG')
-          #   SearchConf[:state].is(:active) | SearchConf[:state].is(:complete)
-          # ---------------------------------------------------------------------------
-          class << self
-            def [](key)
-              FieldRef.new(key.to_s)
-            end
-
-            def in_register(*ids)
-              Register.new(*ids.flatten)
-            end
-
-            def raw(operation, **params)
-              RawFilter.new(operation, **params)
-            end
-          end
-
-          # FieldRef — intermediate object produced by SearchConf[:field].
-          # Calling an operation method returns a concrete Composable filter object.
-          class FieldRef
-            def initialize(key)
-              @key = key
-            end
-
-            def eq(value)
-              Exact.new(@key, value)
-            end
-
-            def is(value)
-              eq(value.to_s)
-            end
-
-            def one_of(*values)
-              Or.new(*values.flatten.map { |v| eq(v.to_s) })
-            end
-
-            def not_eq(value)
-              RawFilter.new('isnt_exact_filter', key: @key, value: value)
-            end
-
-            def matches(text)
-              RawFilter.new('match_filter', key: @key, value: text)
-            end
-
-            def since(date, time_zone: 'UTC')
-              DateRange.new(@key, gte: date, time_zone: time_zone)
-            end
-
-            def before(date, time_zone: 'UTC')
-              DateRange.new(@key, lte: date, time_zone: time_zone)
-            end
-
-            def between(from, til, time_zone: 'UTC')
-              DateRange.new(@key, gte: from, lte: til, time_zone: time_zone)
-            end
-
-            # Human date mode — Search[:updated_at].in_period(:last_month)
-            # See search_filters.md for full list of mode values.
-            def in_period(mode, time_zone: 'Pacific/Auckland', **extra)
-              RawFilter.new('date_filter', key: @key, mode: mode.to_s, time_zone: time_zone, **extra)
-            end
-
-            def present
-              RawFilter.new('has_any_filter', key: @key)
-            end
-
-            alias_method :exists, :present
-
-            def blank
-              RawFilter.new('doesnt_exist_filter', field: @key)
-            end
-
-            def true?
-              RawFilter.new('boolean_filter', key: @key, value: true)
-            end
-
-            def false?
-              RawFilter.new('boolean_filter', key: @key, value: false)
-            end
-
-            def between_nums(min, max)
-              RawFilter.new('numeric_range_filter', key: @key, gte: min, lte: max)
-            end
-          end
-
-          # ---------------------------------------------------------------------------
-          # SearchConf builder
-          # ---------------------------------------------------------------------------
-          def initialize
-            @filters      = []
-            @sorters      = []
-            @search_query = nil
-          end
-
-          # Add one or more filter objects. Multiple calls accumulate (implicit AND at top level).
-          def filter(*filter_objs)
-            @filters.concat(filter_objs.flatten)
-            self
-          end
-
-          # Add a sorter. direction: :asc or :desc.
-          # Multiple sorters are supported (applied in order).
-          def sort(key, direction = :desc)
-            @sorters << { key: key.to_s, direction: direction.to_s }
-            self
-          end
-
-          # Set a full-text search string.
-          def query(text)
-            @search_query = text
-            self
-          end
-
-          # Returns a new SearchConf with filter values substituted.
-          # Substitution keys match the filter's field key (e.g. external_id:, gte:, lte:).
-          # Filters that don't recognise a key are returned unchanged.
-          def with(**substitutions)
-            clone.tap do |copy|
-              copy.instance_variable_set(
-                :@filters,
-                @filters.map { |f| f.respond_to?(:substitute) ? f.substitute(substitutions) : f }
-              )
-            end
-          end
-
-          # Serialises to the Hash structure expected by searchConf arguments.
-          # Sorters: single object when one sorter (API convention), array when multiple.
-          def to_h
-            h = {}
-            h[:filters] = @filters.map(&:to_h) unless @filters.empty?
-            h[:sorters] = @sorters.length == 1 ? @sorters.first : @sorters unless @sorters.empty?
-            h[:query]   = @search_query if @search_query
-            h
-          end
-
-          # Allow JSON serialisation directly (via json gem as_json protocol).
-          def as_json(_ = nil)
-            to_h
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Input
+        # Builder for the searchConf hash argument used by pages, contractorEntities,
+        # personMembers, and other paginated queries.
+        #
+        # Usage:
+        #   conf = SearchConf.new
+        #     .filter(SearchConf::Exact.new(:external_id, 'ABC'))
+        #     .sort(:created_at, :desc)
+        #
+        #   # OR filter (find by one of several externalIds)
+        #   conf = SearchConf.new.filter(
+        #     SearchConf::Or.new(
+        #       SearchConf::Exact.new(:external_id, '1111'),
+        #       SearchConf::Exact.new(:external_id, '2222')
+        #     )
+        #   )
+        #
+        #   # Parametrize — reuse the same structure with a different value
+        #   base = SearchConf.new.filter(SearchConf::Exact.new(:external_id, 'X'))
+        #   copy = base.with(external_id: 'Y')
+        #
+        #   # Pass to any query:
+        #   org.pages(searchConf: conf.to_h, first: 10)
+        #
+        # Filter operations (snake_case — CamelCase silently returns no results):
+        #   SearchConf::Exact     — exact_filter
+        #   SearchConf::DateRange — date_filter
+        #   SearchConf::Register  — register_filter (org search only)
+        #   SearchConf::And       — and_filter (explicit AND group)
+        #   SearchConf::Or        — or_filter
+        class SearchConf
+          # ---------------------------------------------------------------------------
+          # AI-assisted filter generation (optional — requires 'anthropic' gem)
+          # ---------------------------------------------------------------------------
+          class << self
+            # Build a SearchConf from a natural-language description using Claude.
+            # See SearchConf::AIGenerator for full documentation and options.
+            #
+            # Usage:
+            #   require 'anthropic'
+            #   conf = SearchConf.from_description(
+            #     "active pages in Safety register updated this month",
+            #     register_id: 'REG_123'
+            #   )
+            def from_description(text, **opts)
+              require_relative 'search_conf/ai_generator'
+              AIGenerator.from_description(text, **opts)
+            end
+          end
+
+          # ---------------------------------------------------------------------------
+          # Composable — adds & and | operators to filter classes so they can be
+          # combined using natural Ruby operator syntax:
+          #   filter1 & filter2  →  SearchConf::And.new(filter1, filter2)
+          #   filter1 | filter2  →  SearchConf::Or.new(filter1, filter2)
+          # ---------------------------------------------------------------------------
+          module Composable
+            def &(other)
+              SearchConf::And.new(self, other)
+            end
+
+            def |(other)
+              SearchConf::Or.new(self, other)
+            end
+          end
+
+          # ---------------------------------------------------------------------------
+          # Filter: exact_filter
+          # ---------------------------------------------------------------------------
+          class Exact
+            include Composable
+
+            OPERATION = 'exact_filter'.freeze
+
+            def initialize(key, value)
+              @key   = key.to_s
+              @value = value
+            end
+
+            def to_h
+              { operation: OPERATION, params: { key: @key, value: @value } }
+            end
+
+            def substitute(subs)
+              key_sym = @key.to_sym
+              return self unless subs.key?(key_sym)
+
+              self.class.new(@key, subs[key_sym])
+            end
+          end
+
+          # ---------------------------------------------------------------------------
+          # A register FIELD key carries a `<type>.<hash>` shape (e.g. 'date.zab1bddc3');
+          # system/top-level keys (created_at, external_id, state) have no such prefix.
+          # Field filters need the nested `membranes.<type>` path — see
+          # .ai-assistance/code/filter_contract_matrix.md.
+          # ---------------------------------------------------------------------------
+          module MembranePath
+            module_function
+
+            def field_key?(key)
+              key.to_s.include?('.')
+            end
+
+            def membrane_path_for(key)
+              "membranes.#{key.to_s.split('.').first}"
+            end
+          end
+
+          # ---------------------------------------------------------------------------
+          # Filter: date_filter (system date) / range_date_filter (register Date FIELD)
+          # ---------------------------------------------------------------------------
+          class DateRange
+            include Composable
+
+            def initialize(key, gte: nil, lte: nil, time_zone: 'UTC')
+              @key       = key.to_s
+              @gte       = gte
+              @lte       = lte
+              @time_zone = time_zone
+            end
+
+            # A register Date FIELD ('date.zXXXX') filters via range_date_filter on its nested
+            # membranes.date path; a system date (created_at/updated_at) uses date_filter (no
+            # path). Both share gte/lte/time_zone. See filter_contract_matrix.md (date rows) +
+            # backend Pages::RangeDateFilter.
+            def to_h
+              field  = MembranePath.field_key?(@key)
+              params = { key: @key, time_zone: @time_zone }
+              params[:path] = MembranePath.membrane_path_for(@key) if field
+              params[:gte]  = @gte if @gte
+              params[:lte]  = @lte if @lte
+              { operation: field ? 'range_date_filter' : 'date_filter', params: params }
+            end
+
+            def substitute(subs)
+              self.class.new(
+                @key,
+                gte:       subs.fetch(:gte, @gte),
+                lte:       subs.fetch(:lte, @lte),
+                time_zone: subs.fetch(:time_zone, @time_zone)
+              )
+            end
+          end
+
+          # ---------------------------------------------------------------------------
+          # Filter: has_any_filter / doesnt_have_any_filter — register FIELD value membership
+          # (Select, CrossReference, People, …). Distinct from `one_of` (an OR of exact_filter,
+          # for SYSTEM keys): a register field matches via the nested membranes.<type> path +
+          # a field_key subfield ('selected' for selects). See filter_contract_matrix.md +
+          # backend Pages::*::HasAnyFilter.
+          # ---------------------------------------------------------------------------
+          class HasAny
+            include Composable
+
+            def initialize(key, values, field_key: 'selected', exclude: false)
+              @key       = key.to_s
+              @values    = Array(values)
+              @field_key = field_key
+              @exclude   = exclude
+            end
+
+            def to_h
+              op = @exclude ? 'doesnt_have_any_filter' : 'has_any_filter'
+              {
+                operation: op,
+                params:    {
+                  key:       @key,
+                  path:      MembranePath.membrane_path_for(@key),
+                  field_key: @field_key,
+                  values:    @values
+                }
+              }
+            end
+
+            def substitute(subs)
+              self.class.new(@key, subs.fetch(:values, @values), field_key: @field_key, exclude: @exclude)
+            end
+          end
+
+          # ---------------------------------------------------------------------------
+          # Filter: register_filter (org search only — scope to specific registers)
+          # ---------------------------------------------------------------------------
+          class Register
+            include Composable
+
+            OPERATION = 'register_filter'.freeze
+
+            def initialize(*ids)
+              @ids = ids.flatten
+            end
+
+            def to_h
+              { operation: OPERATION, params: { ids: @ids } }
+            end
+
+            def substitute(subs)
+              self.class.new(*Array(subs.fetch(:register_ids, @ids)))
+            end
+          end
+
+          # ---------------------------------------------------------------------------
+          # Filter: and_filter (explicit AND group; top-level filters array is implicit AND)
+          # ---------------------------------------------------------------------------
+          class And
+            include Composable
+
+            OPERATION = 'and_filter'.freeze
+
+            def initialize(*filters)
+              @filters = filters.flatten
+            end
+
+            def to_h
+              { operation: OPERATION, params: { filters: @filters.map(&:to_h) } }
+            end
+
+            def substitute(subs)
+              self.class.new(*@filters.map { |f| f.respond_to?(:substitute) ? f.substitute(subs) : f })
+            end
+          end
+
+          # ---------------------------------------------------------------------------
+          # Filter: or_filter
+          # ---------------------------------------------------------------------------
+          class Or
+            include Composable
+
+            OPERATION = 'or_filter'.freeze
+
+            def initialize(*filters)
+              @filters = filters.flatten
+            end
+
+            def to_h
+              { operation: OPERATION, params: { filters: @filters.map(&:to_h) } }
+            end
+
+            def substitute(subs)
+              self.class.new(*@filters.map { |f| f.respond_to?(:substitute) ? f.substitute(subs) : f })
+            end
+          end
+
+          # ---------------------------------------------------------------------------
+          # RawFilter — escape hatch for operations not yet wrapped as SearchConf classes.
+          # Supports & and | composition just like the typed filter classes.
+          # Usage:
+          #   SearchConf.new.filter(SearchConf::RawFilter.new('has_any_filter', key: 'external_id'))
+          # ---------------------------------------------------------------------------
+          class RawFilter
+            include Composable
+
+            def initialize(operation, **params)
+              @operation = operation
+              @params    = params
+            end
+
+            def to_h
+              { 'operation' => @operation, 'params' => @params.transform_keys(&:to_s) }
+            end
+
+            def substitute(_subs)
+              self
+            end
+          end
+
+          # ---------------------------------------------------------------------------
+          # Fluent DSL class methods — factory for filter expressions.
+          #
+          # SearchConf[:field]  →  FieldRef (then call .eq, .since, .matches, etc.)
+          # SearchConf.in_register(id)  →  Register filter
+          # SearchConf.raw(op, **params)  →  RawFilter
+          #
+          # Examples:
+          #   SearchConf[:external_id].eq('ABC')
+          #   SearchConf[:state].is(:active)
+          #   SearchConf[:updated_at].since('2025-01-01T00:00:00Z')
+          #   SearchConf[:state].is(:active) & SearchConf.in_register('REG')
+          #   SearchConf[:state].is(:active) | SearchConf[:state].is(:complete)
+          # ---------------------------------------------------------------------------
+          class << self
+            def [](key)
+              FieldRef.new(key.to_s)
+            end
+
+            def in_register(*ids)
+              Register.new(*ids.flatten)
+            end
+
+            def raw(operation, **params)
+              RawFilter.new(operation, **params)
+            end
+          end
+
+          # FieldRef — intermediate object produced by SearchConf[:field].
+          # Calling an operation method returns a concrete Composable filter object.
+          class FieldRef
+            def initialize(key)
+              @key = key
+            end
+
+            def eq(value)
+              Exact.new(@key, value)
+            end
+
+            def is(value)
+              eq(value.to_s)
+            end
+
+            def one_of(*values)
+              Or.new(*values.flatten.map { |v| eq(v.to_s) })
+            end
+
+            # Register FIELD value membership → has_any_filter (Select/CrossReference/People/…).
+            # Use this for a register field ('select_str.zXXXX'), NOT one_of (which ORs
+            # exact_filter and is for system keys). field_key defaults to 'selected' (selects);
+            # pass e.g. 'id' for cross_reference. See filter_contract_matrix.md.
+            def any_of(*values, field_key: 'selected')
+              HasAny.new(@key, values.flatten, field_key: field_key)
+            end
+
+            def none_of(*values, field_key: 'selected')
+              HasAny.new(@key, values.flatten, field_key: field_key, exclude: true)
+            end
+
+            def not_eq(value)
+              RawFilter.new('isnt_exact_filter', key: @key, value: value)
+            end
+
+            def matches(text)
+              RawFilter.new('match_filter', key: @key, value: text)
+            end
+
+            def since(date, time_zone: 'UTC')
+              DateRange.new(@key, gte: date, time_zone: time_zone)
+            end
+
+            def before(date, time_zone: 'UTC')
+              DateRange.new(@key, lte: date, time_zone: time_zone)
+            end
+
+            def between(from, til, time_zone: 'UTC')
+              DateRange.new(@key, gte: from, lte: til, time_zone: time_zone)
+            end
+
+            # Human date mode — Search[:updated_at].in_period(:last_month)
+            # See search_filters.md for full list of mode values.
+            def in_period(mode, time_zone: 'Pacific/Auckland', **extra)
+              RawFilter.new('date_filter', key: @key, mode: mode.to_s, time_zone: time_zone, **extra)
+            end
+
+            def present
+              RawFilter.new('has_any_filter', key: @key)
+            end
+
+            alias_method :exists, :present
+
+            def blank
+              RawFilter.new('doesnt_exist_filter', field: @key)
+            end
+
+            def true?
+              RawFilter.new('boolean_filter', key: @key, value: true)
+            end
+
+            def false?
+              RawFilter.new('boolean_filter', key: @key, value: false)
+            end
+
+            def between_nums(min, max)
+              RawFilter.new('numeric_range_filter', key: @key, gte: min, lte: max)
+            end
+          end
+
+          # ---------------------------------------------------------------------------
+          # SearchConf builder
+          # ---------------------------------------------------------------------------
+          def initialize
+            @filters      = []
+            @sorters      = []
+            @search_query = nil
+          end
+
+          # Add one or more filter objects. Multiple calls accumulate (implicit AND at top level).
+          def filter(*filter_objs)
+            @filters.concat(filter_objs.flatten)
+            self
+          end
+
+          # Add a sorter. direction: :asc or :desc.
+          # Multiple sorters are supported (applied in order).
+          def sort(key, direction = :desc)
+            @sorters << { key: key.to_s, direction: direction.to_s }
+            self
+          end
+
+          # Set a full-text search string.
+          def query(text)
+            @search_query = text
+            self
+          end
+
+          # Returns a new SearchConf with filter values substituted.
+          # Substitution keys match the filter's field key (e.g. external_id:, gte:, lte:).
+          # Filters that don't recognise a key are returned unchanged.
+          def with(**substitutions)
+            clone.tap do |copy|
+              copy.instance_variable_set(
+                :@filters,
+                @filters.map { |f| f.respond_to?(:substitute) ? f.substitute(substitutions) : f }
+              )
+            end
+          end
+
+          # Serialises to the Hash structure expected by searchConf arguments.
+          # Sorters: single object when one sorter (API convention), array when multiple.
+          def to_h
+            h = {}
+            h[:filters] = @filters.map(&:to_h) unless @filters.empty?
+            h[:sorters] = @sorters.length == 1 ? @sorters.first : @sorters unless @sorters.empty?
+            h[:query]   = @search_query if @search_query
+            h
+          end
+
+          # Allow JSON serialisation directly (via json gem as_json protocol).
+          def as_json(_ = nil)
+            to_h
+          end
+        end
+      end
+    end
+  end
+end