querylane 0.1.0 → 0.3.0

data/lib/querylane/query.rb

@@ -14,6 +14,9 @@ module Querylane
 
     attr_reader :definition, :source, :nodes, :error
 
+    # @return [Querylane::Configuration] the limits the query was read with
+    attr_reader :config
+
     # @param definition [Querylane::Definition]
     # @param source [String]
     # @return [Querylane::Query]
@@ -21,6 +24,41 @@ module Querylane
       new(definition, source.to_s, config)
     end
 
+    # English defaults of `querylane.errors.*` (the locale file repeats them).
+    MESSAGES = {
+      parked: "%{key}: is not available yet.",
+      unknown_operator: "%{key}: is not an operator.",
+      did_you_mean: "%{key}: is not an operator. Did you mean %{suggestion}:?",
+      filter_value: "\"%{value}\" is not a valid %{key}: value.",
+      filter_value_hidden: "That value is not a valid %{key}: value.",
+      flag_value: "%{value} is not a value of %{key}:. Try %{values}.",
+      text_in_or: "OR joins operators, not names. Search one name at a time.",
+      text_in_not: "- and NOT apply to operators, not names.",
+      text_in_group: "Parentheses group operators, not names.",
+      one_text_operator: "Search %{operators} one at a time, or combine with %{filters}.",
+      one_text_operator_alone: "Search %{operators} one at a time.",
+      list_or: " or ",
+      too_long: "Search is too long (%{max} characters at most).",
+      close_quote: "Close the quote.",
+      needs_value: "%{key}: needs a value.",
+      unexpected: "Unexpected %{text}.",
+      or_needs_terms: "OR needs a term on both sides.",
+      needs_term: "%{operator} needs a term.",
+      ended_early: "Search ended early.",
+      too_deep: "Too many nested parentheses (%{max} at most).",
+      close_parenthesis: "Add the closing ).",
+      empty_parentheses: "Empty parentheses.",
+      too_many_terms: "Too many terms (%{max} at most)."
+    }.freeze
+
+    # A query error message in the current locale.
+    #
+    # @param name [Symbol] a key of MESSAGES (`querylane.errors.<name>`)
+    # @return [String]
+    def self.message(name, **values)
+      I18n.t("querylane.errors.#{name}", **values, default: MESSAGES.fetch(name))
+    end
+
     def valid? = error.nil?
 
     def blank? = source.strip.empty?
@@ -67,6 +105,7 @@ module Querylane
     def initialize(definition, source, config)
       @definition = definition
       @source = source
+      @config = config
       @nodes = []
       @error = nil
       root = Parser.parse(source, config: config)
@@ -106,7 +145,7 @@ module Querylane
       end
       return text_term(definition.default_text, value, term, context, interpreted) if key.nil?
 
-      raise Invalid.new(I18n.t("querylane.errors.parked", key: key, default: "%{key}: is not available yet."), term.range) if definition.parked.include?(key.to_s.downcase)
+      raise Invalid.new(message(:parked, key: key), term.range) if definition.parked.include?(key.to_s.downcase)
 
       operator = definition.operator(key) || raise(unknown_key(key, term))
       resolve_operator(operator, value, term, context, interpreted)
@@ -121,22 +160,18 @@ module Querylane
     end
 
     def text_term(operator, value, term, context, interpreted)
-      if context
-        message = {
-          or: "OR joins operators, not names. Search one name at a time.",
-          not: "- and NOT apply to operators, not names.",
-          group: "Parentheses group operators, not names."
-        }.fetch(context)
-        raise Invalid.new(message, term.range)
-      end
+      raise Invalid.new(message(:"text_in_#{context}"), term.range) if context
+
       Term.new(:text, operator, value, term.quoted, term.range, interpreted, term.value)
     end
 
     def filter_term(operator, value, term, interpreted)
-      normalized = operator.normalize ? operator.normalize.call(value) : value
+      # A copy: a normalizer that edits its argument must not change the typed value.
+      normalized = operator.normalize ? operator.normalize.call(value.dup) : value
       if operator.format && !operator.format.match?(normalized)
-        shown = operator.sensitive ? "That value" : "\"#{value}\""
-        raise Invalid.new("#{shown} is not a valid #{operator.key}: value.", term.range)
+        # A sensitive value is never repeated, not even to the host's copy.
+        text = operator.sensitive ? message(:filter_value_hidden, key: operator.key) : message(:filter_value, key: operator.key, value: value)
+        raise Invalid.new([text, Copy.text(operator.invalid)].compact.join(" "), term.range)
       end
       Term.new(:filter, operator, normalized, term.quoted, term.range, interpreted, term.value)
     end
@@ -144,7 +179,7 @@ module Querylane
     def flag_term(operator, value, term, interpreted)
       symbol = value.to_s.downcase.to_sym
       unless operator.values.key?(symbol)
-        raise Invalid.new("#{value} is not a value of #{operator.key}:. Try #{operator.values.keys.join(", ")}.", term.range)
+        raise Invalid.new(message(:flag_value, key: operator.key, value: value, values: operator.values.keys.join(", ")), term.range)
       end
       Term.new(:flag, operator, symbol, term.quoted, term.range, interpreted, term.value)
     end
@@ -154,19 +189,26 @@ module Querylane
       return if operators.size <= 1
 
       second = text_terms.find { |term| term.operator == operators.last }
-      others = definition.filters.map { |filter| "#{filter.key}:" }.first(2).join(" or ")
-      raise Invalid.new("Search #{operators.map(&:key).join(" or ")} one at a time, or combine with #{others}.", second.range)
+      joiner = message(:list_or)
+      keys = operators.map(&:key).join(joiner)
+      # The first two filters, in declaration order (a host declares its best companions first).
+      others = definition.filters.first(2).map { |filter| "#{filter.key}:" }.join(joiner)
+      text = others.empty? ? message(:one_text_operator_alone, operators: keys) : message(:one_text_operator, operators: keys, filters: others)
+      raise Invalid.new(text, second.range)
     end
 
     # "stauts: is not an operator. Did you mean status:?", with the corrected term as the fix.
     def unknown_key(key, term)
       suggestion = definition.operator_keys.min_by { |candidate| distance(candidate, key) }
-      return Invalid.new("#{key}: is not an operator.", term.range) unless suggestion && distance(suggestion, key) <= 2
+      return Invalid.new(message(:unknown_operator, key: key), term.range) unless suggestion && distance(suggestion, key) <= 2
 
       fixed = source[term.range].sub(/\A[^:]+/, suggestion)
-      Invalid.new("#{key}: is not an operator. Did you mean #{suggestion}:?", term.range, fixed)
+      Invalid.new(message(:did_you_mean, key: key, suggestion: suggestion), term.range, fixed)
     end
 
+    # A query error from `querylane.errors.*`, English by default.
+    def message(name, **values) = Query.message(name, **values)
+
     # Levenshtein distance (short strings only).
     def distance(a, b)
       previous = (0..b.length).to_a

data/lib/querylane/request.rb

@@ -4,30 +4,47 @@ module Querylane
   # One search request, bounded and allowlisted against the definition.
   #
   # Params: query (Configuration#param_name), toggle ("facet:value"),
-  # remove (chip index), clear, instead, widen, relax, compose (with
+  # remove (chip index), as_words (chip index), clear, instead, widen, relax, compose (with
   # compose_submit), options, sort, page, per, revision.
   class Request
-    attr_reader :fix, :saved, :save_search, :saved_name, :group, :query, :toggle, :remove, :clear, :instead, :widen, :relax, :compose, :options, :sort, :page, :per, :revision
+    attr_reader :fix, :saved, :delete_saved, :save_search, :saved_name, :group, :query, :toggle, :remove, :as_words, :clear, :instead, :widen, :relax, :compose, :options, :sort, :page, :per, :revision
 
     # @param params [ActionController::Parameters, Hash]
     # @param definition [Querylane::Definition]
     def self.from_params(params, definition:, config: Querylane.configuration)
-      values = params.respond_to?(:to_unsafe_h) ? params.to_unsafe_h : params.to_h
-      values = values.transform_keys(&:to_s)
-      new(definition: definition, query: values[config.param_name.to_s], toggle: values["toggle"], remove: values["remove"], clear: values["clear"],
+      values = normalized_params(params)
+      values["page"] = values["delete_saved_page"] if values["delete_saved"].present? && values["delete_saved_page"].present?
+      new(definition: definition, query: values[config.param_name.to_s], toggle: values["toggle"], remove: values["remove"],
+        as_words: values["as_words"], clear: values["clear"],
         instead: values["instead"], widen: values["widen"], relax: values["relax"],
         compose: (values["compose"] if values["compose_submit"].present?), options: values["options"],
-        fix: values["fix"], group: values["group"], saved: values["saved"], save_search: values["save_search"], saved_name: values["saved_name"], sort: values["sort"], page: values["page"], per: values["per"], revision: values["revision"])
+        fix: values["fix"], group: values["group"], saved: values["saved"], delete_saved: values["delete_saved"], save_search: values["save_search"], saved_name: values["saved_name"], sort: values["sort"], page: values["page"], per: values["per"], revision: values["revision"])
+    end
+
+    # The normalized, bounded deletion value used by both the request parser and POST guard.
+    #
+    # @param params [ActionController::Parameters, Hash]
+    # @return [String, nil]
+    def self.delete_saved_param(params)
+      normalized_params(params)["delete_saved"].to_s.presence&.first(64)
+    end
+
+    def self.normalized_params(params)
+      values = params.respond_to?(:to_unsafe_h) ? params.to_unsafe_h : params.to_h
+      values.transform_keys(&:to_s)
     end
+    private_class_method :normalized_params
 
     # instead: "chip.alternative" (use another reading of an interpreted term);
-    # widen: a facet key (drop that facet's terms); relax: match fewer words.
+    # widen: a facet key (drop that facet's terms); relax: match fewer words;
+    # as_words: a chip index (search that filter's typed value as plain words).
     # compose: options-panel fields {"name" => "…", "policy" => "1 2", "is" => [...], "options" => [...]}
     # (applied only with compose_submit); options: open the options panel;
     # group: a GroupToken (all records of one group, see Search#related);
-    # saved: a saved search id to run; save_search with saved_name: save the query.
-    def initialize(definition:, query: nil, toggle: nil, remove: nil, clear: nil, instead: nil, widen: nil, relax: nil,
-      compose: nil, options: nil, fix: nil, group: nil, saved: nil, save_search: nil, saved_name: nil, sort: nil, page: nil, per: nil, revision: nil)
+    # saved: a saved search id to run; save_search with saved_name: save the query;
+    # delete_saved: an owned saved search id to delete without rewriting the query.
+    def initialize(definition:, query: nil, toggle: nil, remove: nil, as_words: nil, clear: nil, instead: nil, widen: nil, relax: nil,
+      compose: nil, options: nil, fix: nil, group: nil, saved: nil, delete_saved: nil, save_search: nil, saved_name: nil, sort: nil, page: nil, per: nil, revision: nil)
       @query = query.to_s
       @clear = clear.present?
       @instead = instead.to_s.match(/\A(\d+)\.(\d+)\z/)&.captures&.map(&:to_i)
@@ -36,12 +53,14 @@ module Querylane
       @options = options.present?
       @group = group.presence
       @fix = fix.present?
-      @saved = saved.to_s.presence&.first(64)
-      @save_search = save_search.present?
+      @delete_saved = delete_saved.to_s.presence&.first(64)
+      @saved = saved.to_s.presence&.first(64) unless @delete_saved
+      @save_search = save_search.present? && !@delete_saved
       @saved_name = saved_name.to_s.squish.first(80)
       @compose = compose.is_a?(Hash) ? compose.to_h.transform_keys(&:to_s) : nil
       @toggle = parse_toggle(definition, toggle)
       @remove = (Integer(remove.to_s, exception: false) if remove.present?)
+      @as_words = (Integer(as_words.to_s, exception: false) if as_words.present?)
       @sort = definition.sort(sort)
       @per = definition.per_options.include?(per.to_i) ? per.to_i : definition.per_options.first
       @page = rewriting? ? 1 : [page.to_i, 1].max
@@ -52,7 +71,7 @@ module Querylane
     def offset = (page - 1) * per
 
     # Whether this request asks the server to rewrite the query text.
-    def rewriting? = (@toggle || @remove || @clear || @instead || @widen || @compose || @saved) ? true : false
+    def rewriting? = (@toggle || @remove || @as_words || @clear || @instead || @widen || @compose || @saved) ? true : false
 
     private
 

data/lib/querylane/rewriter.rb

@@ -50,6 +50,40 @@ module Querylane
       text.strip
     end
 
+    # The query with one filter chip's term replaced by its typed value as
+    # plain words ("smith last:smiht" → "smith smiht"), for a chip that offers
+    # it (Chip#as_words); otherwise the query unchanged.
+    #
+    # @param query [Querylane::Query] valid
+    # @param chip [Querylane::Chips::Chip, nil]
+    # @return [String]
+    def as_words(query, chip)
+      return query.source unless chip&.as_words
+
+      words_in_place(query, chip.ranges.first, chip.as_words)
+    end
+
+    # The query text with `range` replaced by `typed` as plain words.
+    #
+    # @return [String]
+    def words_in_place(query, range, typed)
+      words = typed.split.map { |word| bare_word(query.definition, word) }.join(" ")
+      # Keep the words apart from a neighbour typed without a space (`last:"x"is:active`).
+      before = (range.begin.positive? && !query.source[range.begin - 1].match?(/\s/)) ? " " : ""
+      after = (range.end < query.source.length && !query.source[range.end].match?(/\s/)) ? " " : ""
+      replace(query.source, range, "#{before}#{words}#{after}")
+    end
+
+    # A word that reads back as a plain word: anything the parser would take
+    # as syntax (an operator key, a leading "-", OR, NOT, brackets, quotes) or
+    # the interpreter would read as an operator ("1234" as a last four) is
+    # quoted, since quoted words are never interpreted.
+    def bare_word(definition, word)
+      plain = word.match?(/\A[^\s()"-][^\s()"]*\z/) && !word.match?(/\A#{Parser::KEY}/o) && !%w[OR NOT].include?(word) &&
+        definition.interpret(word).nil?
+      plain ? word : quoted(word)
+    end
+
     # The options panel's view of a query: each field's value (keyed by the
     # compose field name), the parts no field can show (kept as typed), and,
     # per masked field, the masked terms it leaves in the box (masked values
@@ -139,7 +173,7 @@ module Querylane
         written = found.map { |token| token.quoted ? quoted(token.text) : quote(token.text) }
         operator.default ? written.join(" ") : written.map { |text| "#{operator.key}:#{text}" }.join(" ")
       else
-        found = found.map { |token| operator.normalize ? token.with(text: operator.normalize.call(token.text)) : token }
+        found = found.map { |token| (operator.normalize && !typed?(operator)) ? token.with(text: operator.normalize.call(token.text)) : token }
         join_or(found.uniq.map { |token| "#{operator.key}:#{token.quoted ? quoted(token.text) : quote(token.text)}" })
       end
     end
@@ -169,7 +203,15 @@ module Querylane
       end
     end
 
-    def display(term) = term.quoted ? quoted(term.value.to_s) : term.value.to_s
+    # A field's text for a term: quoted as typed; a `display_value: :typed` filter
+    # shows the value as typed, others (and interpreted terms, whose typed
+    # token would read differently once prefixed) the normalized value.
+    def display(term)
+      value = (typed?(term.operator) && !term.interpreted) ? term.raw.to_s : term.value.to_s
+      term.quoted ? quoted(value) : value
+    end
+
+    def typed?(operator) = operator.is_a?(Definition::FilterOperator) && operator.display_value == :typed
 
     # Always quoted, with " and \ escaped.
     def quoted(value) = %("#{value.to_s.gsub(/["\\]/) { |char| "\\#{char}" }}")

data/lib/querylane/search.rb

@@ -33,6 +33,7 @@ module Querylane
       query = Query.analyze(@definition, @request.query, config: @config)
       query, rewritten = rewrite(query)
       @notice = save(query) if @request.save_search && !@scope.denied?
+      @notice = delete_saved(@request.delete_saved) if @request.delete_saved && !@scope.denied?
       return result(:first_load, query, rewritten) if query.valid? && query.blank?
       return result(:invalid, query, rewritten, error: query.error) unless query.valid?
       return result(:short, query, rewritten, chips: Chips.for(query)) if query.too_short?(@definition.min_text_length)
@@ -211,6 +212,8 @@ module Querylane
           chip = Chips.for(query).find { |candidate| candidate.index == chip_index }
           alternative = chip&.alternatives&.find { |candidate| candidate.index == alternative_index }
           alternative ? Rewriter.replace(query.source, chip.ranges.first, alternative.text) : query.source
+        elsif @request.as_words
+          Rewriter.as_words(query, Chips.for(query).find { |candidate| candidate.index == @request.as_words })
         else
           chip = Chips.for(query).find { |candidate| candidate.index == @request.remove }
           chip ? Rewriter.remove(query.source, chip.ranges) : query.source
@@ -309,6 +312,15 @@ module Querylane
       nil
     end
 
+    def delete_saved(id)
+      store = @definition.saved_searches
+      return :not_available unless store&.respond_to?(:delete)
+
+      store.delete(context: @context, id: id) ? :deleted : :not_available
+    rescue => error
+      saved_store_failed(error)
+    end
+
     def saved_list
       store = @definition.saved_searches
       store && Array(store.all(context: @context))

data/lib/querylane/searchers/meilisearch.rb

@@ -67,10 +67,27 @@ module Querylane
 
       def client = @client.respond_to?(:call) ? @client.call : @client
 
+      # Turns a backend failure into SearchUnavailable and logs why. An API
+      # error is logged by code, type and status only: its message can echo
+      # the filter, and filters carry what the user searched for.
       def call
         yield
-      rescue ::Meilisearch::ApiError, ::Meilisearch::CommunicationError, ::Meilisearch::TimeoutError => error
-        raise SearchUnavailable, "Meilisearch #{error.class.name.demodulize}"
+      rescue ::Meilisearch::ApiError => error
+        unavailable(error, "code=#{error.code} type=#{error.type} http=#{error.http_code}", error.code)
+      rescue ::Meilisearch::CommunicationError, ::Meilisearch::TimeoutError => error
+        unavailable(error, without_url_secrets(error.message))
+      end
+
+      # A connection error can quote the client URL; keep its host and port,
+      # drop any user:password@ and query string.
+      def without_url_secrets(message)
+        message.gsub(%r{(\w+://)[^\s/@]+@}, '\1').gsub(/\?[^\s)]*/, "")
+      end
+
+      def unavailable(error, detail, code = nil)
+        name = "Meilisearch #{error.class.name.demodulize}"
+        Querylane.configuration.logger.warn("[querylane] search unavailable: #{name} #{detail}")
+        raise SearchUnavailable, [name, code].compact.join(" ")
       end
 
       # Indexes whose scope and query can match something; the others are

data/lib/querylane/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Querylane
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/querylane.rb

@@ -14,6 +14,7 @@ require "strscan"
 
 require "querylane/version"
 require "querylane/errors"
+require "querylane/copy"
 require "querylane/configuration"
 require "querylane/filter"
 require "querylane/scope"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: querylane
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Ajaya Agrawalla
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-20 00:00:00.000000000 Z
+date: 2026-11-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -79,6 +79,7 @@ files:
 - lib/querylane/configuration.rb
 - lib/querylane/context.rb
 - lib/querylane/controller.rb
+- lib/querylane/copy.rb
 - lib/querylane/definition.rb
 - lib/querylane/doctor.rb
 - lib/querylane/engine.rb