lib/fixtury/locator.rb in fixtury-0.4.1 vs lib/fixtury/locator.rb in fixtury-1.0.0.beta1

@@ -1,49 +1,60 @@
 # frozen_string_literal: true
 
+require "fixtury/locator_backend/memory"
+
 module Fixtury
+  # Locator is responsible for recognizing, loading, and dumping references.
+  # It is a simple wrapper around a backend that is responsible for the actual work.
+  # The backend is expected to implement the following methods: recognizable_key?, recognized_value?, load_recognized_reference, dump_recognized_value.
   class Locator
 
-    class << self
-
-      attr_accessor :instance
-
-      def instance
-        @instance ||= begin
-          require "fixtury/locator_backend/memory"
-          ::Fixtury::Locator.new(
-            backend: ::Fixtury::LocatorBackend::Memory.new
-          )
-        end
-      end
-
-    end
-
     attr_reader :backend
 
-    def initialize(backend:)
+    def initialize(backend: ::Fixtury::LocatorBackend::Memory.new)
       @backend = backend
     end
 
-    def recognize?(ref)
-      raise ArgumentError, "Unable to recognize a nil ref" if ref.nil?
+    def inspect
+      "#{self.class}(backend: #{backend.class})"
+    end
 
-      backend.recognized_reference?(ref)
+    # Determine if the provided locator_key is a valid form recognized by the backend.
+    #
+    # @param locator_key [Object] the locator key to check
+    # @return [Boolean] true if the locator key is recognizable by the backend
+    # @raise [ArgumentError] if the locator key is nil
+    def recognizable_key?(locator_key)
+      raise ArgumentError, "Unable to recognize a nil locator value" if locator_key.nil?
+
+      backend.recognizable_key?(locator_key)
     end
 
-    def load(ref)
-      raise ArgumentError, "Unable to load a nil ref" if ref.nil?
+    # Load the value associated with the provided locator key.
+    #
+    # @param locator_key [Object] the locator key to load
+    # @return [Object] the loaded value
+    # @raise [ArgumentError] if the locator key is nil
+    def load(locator_key)
+      raise ArgumentError, "Unable to load a nil locator value" if locator_key.nil?
 
-      backend.load(ref)
+      backend.load(locator_key)
     end
 
-    def dump(value)
-      raise ArgumentError, "Unable to dump a nil value" if value.nil?
+    # Provide the value to the backend to generate a locator key.
+    #
+    # @param stored_value [Object] the value to dump
+    # @param context [String] a string to include in the error message if the value is nil
+    # @return [Object] the locator key
+    # @raise [ArgumentError] if the value is nil
+    # @raise [ArgumentError] if the backend is unable to dump the value
+    def dump(stored_value, context: nil)
+      raise ArgumentError, "Unable to dump a nil value. #{context}" if stored_value.nil?
 
-      ref = backend.dump(value)
-      raise ArgumentError, "The value resulted in a nil ref" if ref.nil?
+      locator_key = backend.dump(stored_value)
+      raise ArgumentError, "Dump resulted in a nil locator value. #{context}" if locator_key.nil?
 
-      ref
+      locator_key
     end
 
   end
 end