spree_core 5.6.1 → 6.0.0.beta2

data/lib/spree/events/adapters/base.rb

@@ -147,25 +147,52 @@ module Spree
         def invoke_subscriber(subscriber, event, options)
           async = options.fetch(:async, true)
 
-          if subscriber.is_a?(Proc)
-            # Block subscribers run synchronously
-            subscriber.call(event)
-          elsif subscriber.respond_to?(:call)
-            # Callable objects (including subscriber instances)
-            if async && defined?(Spree::Events::SubscriberJob)
-              Spree::Events::SubscriberJob.perform_later(subscriber.name, event.to_h)
-            else
+          ActiveSupport::Notifications.instrument(
+            'dispatch.spree_events',
+            event_name: event.name,
+            subscriber: subscriber_label(subscriber),
+            async: async_dispatch?(subscriber, async)
+          ) do
+            if subscriber.is_a?(Proc)
+              # Block subscribers run synchronously
               subscriber.call(event)
-            end
-          elsif subscriber.is_a?(Class) && subscriber < Spree::Subscriber
-            # Subscriber classes
-            if async && defined?(Spree::Events::SubscriberJob)
-              Spree::Events::SubscriberJob.perform_later(subscriber.name, event.to_h)
+            elsif subscriber.respond_to?(:call)
+              # Callable objects (including subscriber instances)
+              if async && defined?(Spree::Events::SubscriberJob)
+                Spree::Events::SubscriberJob.perform_later(subscriber.name, event.to_h)
+              else
+                subscriber.call(event)
+              end
+            elsif subscriber.is_a?(Class) && subscriber < Spree::Subscriber
+              # Subscriber classes
+              if async && defined?(Spree::Events::SubscriberJob)
+                Spree::Events::SubscriberJob.perform_later(subscriber.name, event.to_h)
+              else
+                subscriber.new.call(event)
+              end
             else
-              subscriber.new.call(event)
+              raise ArgumentError, "Invalid subscriber: #{subscriber.inspect}. Must be a Proc, callable, or Spree::Subscriber subclass."
             end
+          end
+        end
+
+        # Whether this dispatch hops to ActiveJob rather than running inline —
+        # mirrors the branching in {#invoke_subscriber}.
+        def async_dispatch?(subscriber, async)
+          return false if subscriber.is_a?(Proc)
+
+          async && defined?(Spree::Events::SubscriberJob) ? true : false
+        end
+
+        # Stable, low-cardinality label for instrumentation payloads (a
+        # Proc's #to_s embeds a memory address).
+        def subscriber_label(subscriber)
+          if subscriber.is_a?(Proc)
+            'Proc'
+          elsif subscriber.respond_to?(:name) && subscriber.name
+            subscriber.name
           else
-            raise ArgumentError, "Invalid subscriber: #{subscriber.inspect}. Must be a Proc, callable, or Spree::Subscriber subclass."
+            subscriber.class.name
           end
         end
 

data/lib/spree/hooks.rb

@@ -0,0 +1,146 @@
+module Spree
+  # Extension hook registry for Spree::Workflow flows (see
+  # docs/plans/6.0-service-workflows.md). Keys are dotted strings —
+  # '<workflow key>.<hook name>', e.g. 'carts.add_item.after_item_added'.
+  # Handlers are stored as class names (constantized at dispatch) so
+  # registration is initializer-safe, dev-reload-safe and idempotent;
+  # blocks are accepted for one-line glue.
+  class Hooks
+    class UnknownHookError < StandardError; end
+
+    # Reported (never raised) when two context-hook handlers set the same key.
+    class ContextCollision < StandardError; end
+
+    def initialize
+      @handlers = Hash.new { |hash, key| hash[key] = [] }
+      # workflow key => workflow class name; populated by Spree::Workflow
+      # when a class declares hooks. Class NAMES, never classes — reload
+      # safety.
+      @workflows = {}
+    end
+
+    attr_reader :workflows
+
+    # @param key [String] '<workflow key>.<hook name>'
+    # @param handler [Class, String, nil] class responding to call(context)
+    def register(key, handler = nil, &block)
+      key = key.to_s
+      callable = block || handler
+      raise ArgumentError, 'Pass a handler class or a block' if callable.nil?
+
+      entry = callable.is_a?(Proc) ? callable : callable.to_s
+      @handlers[key] << entry unless @handlers[key].include?(entry)
+      entry
+    end
+
+    def unregister(key, handler = nil)
+      return @handlers.delete(key.to_s) if handler.nil?
+
+      @handlers[key.to_s].delete(handler.is_a?(Proc) ? handler : handler.to_s)
+    end
+
+    # @return [Array<#call>] resolved handlers for the key
+    def for(key)
+      @handlers[key.to_s].map { |entry| entry.is_a?(Proc) ? entry : entry.constantize.new }
+    end
+
+    # Calls every handler registered for the key and deep-merges the hashes
+    # they return, so context hooks (set_pricing_context, get_provider_data)
+    # can feed data into a calculation without sharing mutable state.
+    # Handlers returning anything other than a Hash contribute nothing —
+    # lifecycle handlers routinely return whatever their last expression was.
+    #
+    # @return [Hash] merged contributions; empty when no handler contributed
+    def dispatch(key, context)
+      self.for(key).each_with_object({}) do |handler, merged|
+        contribution = handler.call(context)
+        next unless contribution.is_a?(Hash)
+
+        report_collisions(key, merged, contribution)
+        merged.deep_merge!(contribution)
+      end
+    end
+
+    # Registered by Spree::Workflow at class-definition time.
+    def register_workflow(workflow_key, class_name)
+      @workflows[workflow_key.to_s] = class_name.to_s
+    end
+
+    # Validates every registered key against hooks declared by workflow
+    # classes. Call after eager load — a typo fails the boot instead of
+    # never firing.
+    def validate!
+      @handlers.keys.each do |key|
+        workflow_key, hook_name = split_key(key)
+        workflow = @workflows[workflow_key]&.safe_constantize
+        raise UnknownHookError, "Hook '#{key}' does not match any registered workflow" if workflow.nil?
+
+        unless workflow.declared_hooks.include?(hook_name.to_sym)
+          raise UnknownHookError,
+                "Workflow '#{workflow_key}' declares no hook '#{hook_name}' (declared: #{workflow.declared_hooks.join(', ')})"
+        end
+      end
+      true
+    end
+
+    # @param key [String, Symbol] '<workflow key>.<hook name>'
+    # @return [Integer] registered handler count for the key, without
+    #   constantizing anything (cheap enough for instrumentation payloads)
+    def handler_count(key)
+      @handlers.fetch(key.to_s) { [] }.size
+    end
+
+    def keys
+      @handlers.keys
+    end
+
+    def clear!
+      @handlers.clear
+    end
+
+    # Introspection facade: Spree.hooks.carts => { 'carts.add_item' => [...] }
+    def method_missing(name, *args, &block)
+      prefix = "#{name}."
+      matching = @workflows.keys.select { |workflow_key| workflow_key.start_with?(prefix) || workflow_key == name.to_s }
+      return super if matching.empty? && !@workflows.keys.any? { |k| k.start_with?(prefix) }
+
+      matching.index_with do |workflow_key|
+        workflow = @workflows[workflow_key]&.safe_constantize
+        workflow ? workflow.declared_hooks : []
+      end
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      prefix = "#{name}."
+      @workflows.keys.any? { |workflow_key| workflow_key.start_with?(prefix) } || super
+    end
+
+    private
+
+    # Last writer wins on a collision, which is only defensible if it's
+    # visible — two extensions silently fighting over one key is the failure
+    # mode this whole contract exists to avoid.
+    def report_collisions(key, merged, contribution)
+      collisions = merged.keys & contribution.keys
+      return if collisions.empty?
+
+      Rails.error.report(
+        Spree::Hooks::ContextCollision.new(
+          "Hook '#{key}' handlers both set: #{collisions.join(', ')} — last registered handler wins"
+        ),
+        context: { hook: key, keys: collisions },
+        source: 'spree.hooks',
+        handled: true
+      )
+    end
+
+    def split_key(key)
+      parts = key.to_s.split('.')
+      [parts[0..-2].join('.'), parts[-1]]
+    end
+  end
+
+  def self.hooks
+    @hooks ||= Hooks.new
+  end
+end

data/lib/spree/iso_data.rb

@@ -0,0 +1,188 @@
+module Spree
+  # Reference data for countries and their subdivisions, sourced from the
+  # +countries+ gem (ISO 3166). Backs {Spree::Country} and {Spree::State},
+  # which are value objects rather than database records.
+  #
+  # The gem's raw subdivision list is not usable as-is at checkout, so this
+  # module curates it in three ways:
+  #
+  # * {SUBDIVISION_TYPES} keeps only the subdivision kinds a customer would
+  #   recognise as a "state" for that country.
+  # * {SUBDIVISION_ADDITIONS} restores entries the gem omits but real addresses
+  #   still use — US military codes, and Italian provinces abolished in 2016.
+  # * {SUBDIVISION_ALIASES} maps codes that ISO has since renamed onto their
+  #   successors, so an address stored years ago still resolves.
+  #
+  # Without the last two, upgrading would invalidate addresses that were
+  # perfectly valid when they were entered.
+  module IsoData
+    # Territories, uninhabited islands and Antarctica — never orderable.
+    EXCLUDED_COUNTRIES = %w[AQ AX GS UM HM IO EH BV TF].freeze
+
+    # Subdivision types to keep, per country. A country absent from this hash
+    # keeps every type the gem lists for it.
+    #
+    # The US would otherwise carry six outlying areas (Guam, Puerto Rico and
+    # friends) alongside the 50 states and DC; China would carry Hong Kong and
+    # Macao, which Spree treats as countries in their own right.
+    SUBDIVISION_TYPES = {
+      'US' => %w[state district],
+      'CN' => %w[province municipality autonomous_region]
+    }.freeze
+
+    # Codes dropped after the type filter. Taiwan is an autonomous region in the
+    # gem's Chinese subdivision list and a country everywhere else.
+    SUBDIVISION_EXCLUSIONS = { 'CN' => %w[TW] }.freeze
+
+    # Subdivisions the gem does not list but addresses legitimately use.
+    #
+    # The US military codes are how APO/FPO mail is addressed and every US
+    # checkout accepts them. The Sardinian provinces were abolished in 2016
+    # with no successor, so an address from before then has nowhere else to go.
+    SUBDIVISION_ADDITIONS = {
+      'US' => {
+        'AA' => 'Armed Forces Americas',
+        'AE' => 'Armed Forces Europe',
+        'AP' => 'Armed Forces Pacific'
+      },
+      'IT' => {
+        'CI' => 'Carbonia-Iglesias',
+        'OG' => 'Ogliastra',
+        'OT' => 'Olbia-Tempio',
+        'VS' => 'Medio Campidano'
+      }
+    }.freeze
+
+    # Retired ISO codes mapped to their current equivalent. Reading an address
+    # written under the old code still finds the right subdivision; writing
+    # always stores the successor.
+    SUBDIVISION_ALIASES = {
+      'IN' => {
+        'CT' => 'CG',  # Chhattisgarh
+        'OR' => 'OD',  # Odisha
+        'TG' => 'TS',  # Telangana
+        'UT' => 'UK',  # Uttarakhand
+        'DD' => 'DH',  # Daman and Diu, merged in 2020
+        'DN' => 'DH'   # Dadra and Nagar Haveli, merged in 2020
+      },
+      'IT' => { 'AO' => '23' }, # Valle d'Aosta, now coded as a region
+      'ZA' => {
+        'GT' => 'GP',  # Gauteng
+        'NL' => 'ZN'   # KwaZulu-Natal
+      }
+    }.freeze
+
+    class << self
+      # Every orderable country, memoized for the life of the process.
+      # @return [Array<ISO3166::Country>]
+      def countries
+        @countries ||= ISO3166::Country.all.
+                       reject { |country| EXCLUDED_COUNTRIES.include?(country.alpha2) }.
+                       freeze
+      end
+
+      # @param code [String] alpha-2 or alpha-3 code, any case
+      # @return [ISO3166::Country, nil]
+      def country(code)
+        return nil if code.blank?
+
+        code = code.to_s.strip.upcase
+        found = ISO3166::Country[code] || ISO3166::Country.find_country_by_alpha3(code)
+        return nil if found.nil? || EXCLUDED_COUNTRIES.include?(found.alpha2)
+
+        found
+      end
+
+      # The curated subdivisions for a country, as +{ code => name }+, ordered
+      # by name.
+      #
+      # @param iso [String] alpha-2 country code
+      # @return [Hash{String => String}]
+      # Keyed by locale as well as country: the names are localized, and this
+      # cache outlives a request, so keying on the country alone would serve
+      # whichever locale happened to warm it to everyone else.
+      def subdivisions(iso)
+        iso = iso.to_s.upcase
+        @subdivisions ||= {}
+        @subdivisions[[I18n.locale, iso]] ||= build_subdivisions(iso).freeze
+      end
+
+      # Resolves whatever handle a caller has — a current code, a retired one,
+      # or a subdivision name — to a current code.
+      #
+      # @param iso [String] alpha-2 country code
+      # @param value [String] code or name
+      # @return [String, nil] the current subdivision code
+      def subdivision_code(iso, value)
+        return nil if value.blank?
+
+        iso = iso.to_s.upcase
+        candidate = value.to_s.strip
+        available = subdivisions(iso)
+
+        upcased = candidate.upcase
+        return upcased if available.key?(upcased)
+
+        aliased = SUBDIVISION_ALIASES.dig(iso, upcased)
+        return aliased if aliased && available.key?(aliased)
+
+        by_name = available.find { |_code, name| name.casecmp?(candidate) }
+        return by_name.first if by_name
+
+        # Falls back to the gem, which also matches translated names.
+        country(iso)&.find_subdivision_by_name(candidate)&.code.presence
+      end
+
+      # @param iso [String] alpha-2 country code
+      # @param code [String] subdivision code
+      # @return [String, nil] the subdivision's name
+      def subdivision_name(iso, code)
+        subdivisions(iso)[code.to_s.upcase]
+      end
+
+      # Drops memoized data. Only needed when locale configuration changes
+      # after boot, which in practice means specs.
+      # @return [void]
+      def reset!
+        @countries = nil
+        @subdivisions = nil
+      end
+
+      private
+
+      def build_subdivisions(iso)
+        source = country(iso)
+        return {} if source.nil?
+
+        types = SUBDIVISION_TYPES[iso]
+        selected = types ? source.subdivisions_of_types(types) : source.subdivisions
+        excluded = SUBDIVISION_EXCLUSIONS.fetch(iso, [])
+
+        entries = selected.
+                  reject { |code, _| excluded.include?(code) }.
+                  map { |code, subdivision| [code, subdivision_display_name(subdivision)] }
+
+        entries.concat(SUBDIVISION_ADDITIONS.fetch(iso, {}).to_a)
+        entries.sort_by { |_code, name| name.to_s }.to_h
+      end
+
+      # Under a non-English locale a subdivision is named by its translation,
+      # when the gem has one for the locales it was configured with.
+      #
+      # English deliberately reads the canonical +name+ rather than the +en+
+      # translation: the two disagree in places (the gem translates DC as
+      # "Washington DC", where the canonical name is "District of Columbia"),
+      # and the canonical spelling is the one Spree has always stored.
+      #
+      # Note the translation keys are symbols here, unlike +Country#translation+,
+      # which takes a string.
+      def subdivision_display_name(subdivision)
+        locale = I18n.locale.to_s.downcase
+        return subdivision.name if locale.start_with?('en')
+
+        translations = subdivision.translations || {}
+        translations[locale.to_sym].presence || subdivision.name
+      end
+    end
+  end
+end

data/lib/spree/measurement.rb

@@ -0,0 +1,113 @@
+module Spree
+  # Unit conversion for the physical measurements Spree stores: dimensions in
+  # millimeters, centimeters, inches or feet, and weights in grams, kilograms,
+  # pounds or ounces.
+  #
+  # Spree keeps measurements in whatever unit the merchant typed, next to the
+  # unit itself, so any calculation combining two records has to normalize
+  # first. Volume is where this stops being cosmetic — a carton measured in
+  # inches has roughly sixteen times the cubic value of the same numbers read
+  # as centimeters, so cubic meters derived from raw dimension columns are
+  # wrong for most of the world.
+  #
+  # Stateless module functions over two unit tables, deliberately not a value
+  # object: callers already hold a number and a unit string.
+  module Measurement
+    # Centimeters per unit of length.
+    LENGTH_IN_CENTIMETERS = {
+      'mm' => BigDecimal('0.1'),
+      'cm' => BigDecimal('1'),
+      'in' => BigDecimal('2.54'),
+      'ft' => BigDecimal('30.48')
+    }.freeze
+
+    # Kilograms per unit of weight.
+    WEIGHT_IN_KILOGRAMS = {
+      'g' => BigDecimal('0.001'),
+      'kg' => BigDecimal('1'),
+      'lb' => BigDecimal('0.45359237'),
+      'oz' => BigDecimal('0.028349523125')
+    }.freeze
+
+    CENTIMETERS_PER_METER = BigDecimal('100')
+
+    DEFAULT_LENGTH_UNIT = 'cm'.freeze
+    DEFAULT_WEIGHT_UNIT = 'kg'.freeze
+
+    class << self
+      # Converts a length to centimeters.
+      #
+      # @param value [Numeric, String, nil]
+      # @param unit [String, nil] one of {LENGTH_IN_CENTIMETERS}'s keys; an
+      #   unknown or blank unit is read as centimeters
+      # @return [BigDecimal, nil] nil when the value is missing
+      def to_centimeters(value, unit: DEFAULT_LENGTH_UNIT)
+        convert(value, LENGTH_IN_CENTIMETERS, unit, DEFAULT_LENGTH_UNIT)
+      end
+
+      # Converts a weight to kilograms.
+      #
+      # @param value [Numeric, String, nil]
+      # @param unit [String, nil] one of {WEIGHT_IN_KILOGRAMS}'s keys; an
+      #   unknown or blank unit is read as kilograms
+      # @return [BigDecimal, nil] nil when the value is missing
+      def to_kilograms(value, unit: DEFAULT_WEIGHT_UNIT)
+        convert(value, WEIGHT_IN_KILOGRAMS, unit, DEFAULT_WEIGHT_UNIT)
+      end
+
+      # Converts a length between any two supported units.
+      #
+      # @param value [Numeric, String, nil]
+      # @param from [String, nil]
+      # @param to [String, nil]
+      # @return [BigDecimal, nil] nil when the value is missing
+      def convert_length(value, from:, to:)
+        rescale(to_centimeters(value, unit: from), LENGTH_IN_CENTIMETERS, to, DEFAULT_LENGTH_UNIT)
+      end
+
+      # Converts a weight between any two supported units.
+      #
+      # @param value [Numeric, String, nil]
+      # @param from [String, nil]
+      # @param to [String, nil]
+      # @return [BigDecimal, nil] nil when the value is missing
+      def convert_weight(value, from:, to:)
+        rescale(to_kilograms(value, unit: from), WEIGHT_IN_KILOGRAMS, to, DEFAULT_WEIGHT_UNIT)
+      end
+
+      # The cubic meters a box of these dimensions occupies — the CBM figure
+      # freight is quoted and tiered on.
+      #
+      # @param length [Numeric, nil]
+      # @param width [Numeric, nil]
+      # @param height [Numeric, nil]
+      # @param unit [String, nil] the unit all three are expressed in
+      # @return [BigDecimal, nil] nil unless all three dimensions are present
+      #   and positive — a box with a missing or zero side has no volume worth
+      #   reporting, and returning zero would read as "measured, and empty"
+      def cubic_meters(length, width, height, unit: DEFAULT_LENGTH_UNIT)
+        sides = [length, width, height].map { |side| to_centimeters(side, unit: unit) }
+        return if sides.any? { |side| side.nil? || side <= 0 }
+
+        sides.inject(:*) / (CENTIMETERS_PER_METER**3)
+      end
+
+      private
+
+      # Turns a normalized figure (centimeters, kilograms) back into the
+      # target unit.
+      def rescale(normalized, table, unit, default_unit)
+        return if normalized.nil?
+
+        normalized / (table[unit.to_s.downcase.presence || default_unit] || table[default_unit])
+      end
+
+      def convert(value, table, unit, default_unit)
+        return if value.nil? || (value.is_a?(String) && value.blank?)
+
+        factor = table[unit.to_s.downcase.presence || default_unit] || table[default_unit]
+        value.to_d * factor
+      end
+    end
+  end
+end

data/lib/spree/money.rb

@@ -5,6 +5,76 @@ Money.rounding_mode = BigDecimal::ROUND_HALF_UP
 
 module Spree
   class Money
+    # How Spree rounds an amount to a currency.
+    #
+    # Lives here beside the rounding mode above because "how much is this worth
+    # in this currency" is one answer a store should give consistently — the
+    # same two lines had otherwise been written out wherever a service needed
+    # them, each copy free to drift.
+    module Rounding
+      module_function
+
+      # The number of decimal places a currency is written in: 2 for most, 0
+      # for yen, 3 for dinar. An unknown currency falls back to two places
+      # rather than raising — a sale is not the moment to discover a typo in a
+      # currency code.
+      #
+      # Note that Spree's money columns are `decimal(_, 2)` throughout, so a
+      # three-decimal currency still loses its last place on the way into the
+      # database. Rounding here to the currency's own precision keeps the
+      # arithmetic honest and means widening those columns would be the only
+      # change needed; it does not by itself make Spree dinar-exact.
+      #
+      # @param currency [String, ::Money::Currency, nil]
+      # @return [Integer]
+      def precision(currency)
+        (::Money::Currency.find(currency) || ::Money::Currency.find('USD')).exponent
+      end
+
+      # Rounds to the currency's own minor unit, half-up, so amounts reconcile
+      # to the cent when they are summed.
+      #
+      # @param amount [Numeric, String, nil]
+      # @param currency [String, ::Money::Currency, nil]
+      # @return [BigDecimal]
+      def to_currency(amount, currency)
+        quantize(amount, precision(currency))
+      end
+
+      # The same rounding against a precision already in hand.
+      #
+      # @param amount [Numeric, String, nil]
+      # @param precision [Integer]
+      # @return [BigDecimal]
+      def quantize(amount, precision)
+        BigDecimal(amount.to_s).round(precision, BigDecimal::ROUND_HALF_UP)
+      end
+
+      # An amount as a whole number of the currency's smallest unit — cents for
+      # most currencies, whole yen for one written without decimals.
+      #
+      # Apportionment works in these units because integers divide exactly:
+      # shares computed from them can be made to sum to the original, which is
+      # what keeps a divided charge equal to the one the customer agreed to.
+      # Hardcoding a hundredth here instead would give a yen sale a hundred
+      # times its weight and hand back a figure with decimals the currency does
+      # not have.
+      #
+      # @param amount [Numeric, String, nil]
+      # @param currency [String, ::Money::Currency, nil]
+      # @return [Integer]
+      def to_minor_units(amount, currency)
+        (BigDecimal(amount.to_s) * (10**precision(currency))).round.to_i
+      end
+
+      # @param units [Integer] whole minor units, as {#to_minor_units} returns
+      # @param currency [String, ::Money::Currency, nil]
+      # @return [BigDecimal]
+      def from_minor_units(units, currency)
+        BigDecimal(units) / (10**precision(currency))
+      end
+    end
+
     include Comparable
 
     class << self

data/lib/spree/number_generators/registry.rb

@@ -0,0 +1,80 @@
+module Spree
+  module NumberGenerators
+    # Maps a resource key (`:order`, `:return`, …) to the generator that
+    # numbers it. Empty by default: with no explicit entry, the store's
+    # `document_number_format` preference decides between the sequential and
+    # random strategies, which is what makes the dashboard switch work
+    # without any registration at all.
+    #
+    #   Spree.number_generators[:order] = 'MyApp::BranchOrderNumbers'
+    #   Spree.number_generators[:order]        # => the class
+    #   Spree.number_generators.delete(:order) # back to store settings
+    #
+    # Values are stored as strings and constantized on read so a host app can
+    # register in an initializer without eager-loading the class, and so
+    # Zeitwerk reloads resolve the current definition in development.
+    class Registry
+      FORMATS = {
+        'sequential' => 'Spree::NumberGenerators::Sequential',
+        'random' => 'Spree::NumberGenerators::Random'
+      }.freeze
+
+      DEFAULT_FORMAT = 'sequential'.freeze
+
+      def initialize
+        @overrides = {}
+      end
+
+      # @param key [Symbol, String] resource key
+      # @param class_name [String, Class, nil] nil clears the override
+      def []=(key, class_name)
+        if class_name.nil?
+          delete(key)
+        else
+          @overrides[key.to_sym] = class_name.to_s
+        end
+      end
+
+      # @return [Class, nil] the registered class, without falling back
+      def [](key)
+        @overrides[key.to_sym]&.constantize
+      end
+
+      def delete(key)
+        @overrides.delete(key.to_sym)
+      end
+
+      def keys
+        @overrides.keys
+      end
+
+      def clear
+        @overrides.clear
+      end
+
+      # The generator for a resource: an explicit registration if there is
+      # one, otherwise the strategy named by the format preference of the
+      # store the record belongs to.
+      #
+      # @param key [Symbol, String] resource key
+      # @param store [Spree::Store, nil] the record's store; the format
+      #   preference is read from it rather than from `Spree::Current` so a
+      #   background job numbering another store's document still honours
+      #   that store's choice
+      # @return [Spree::NumberGenerators::Base]
+      def for(key, store: nil)
+        registered = self[key]
+        return registered.new if registered
+
+        format_class(store).new
+      end
+
+      private
+
+      def format_class(store)
+        format = (store || Spree::Current.store)&.preferred_document_number_format
+        FORMATS.fetch(format.to_s, FORMATS.fetch(DEFAULT_FORMAT)).constantize
+      end
+    end
+  end
+end