valkyrie 0.1.0 → 1.0.0.rc1

data/lib/valkyrie/persistence/memory.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
+#
 module Valkyrie::Persistence
+  # Implements the DataMapper Pattern to store metadata in memory
+  #
+  # @note this adapter is used primarily for testing, and is not recommended
+  #   in cases where you want to preserve real data
   module Memory
     require 'valkyrie/persistence/memory/metadata_adapter'
     require 'valkyrie/persistence/memory/persister'

data/lib/valkyrie/persistence/memory/metadata_adapter.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 module Valkyrie::Persistence::Memory
+  # MetadataAdapter for the memory adapter.
+  # @see Valkyrie::Persistence::Memory
+  # @note Documentation for instance methods on other MetadataAdapters are
+  #   copied from the Memory implementation via `(see
+  #   Valkyrie::Persistence::Memory#method)` to reduce duplication.
   class MetadataAdapter
     attr_writer :cache
 
@@ -12,7 +17,7 @@ module Valkyrie::Persistence::Memory
     # @return [Valkyrie::Persistence::Memory::QueryService] A query service for
     #   this adapter.
     def query_service
-      Valkyrie::Persistence::Memory::QueryService.new(adapter: self)
+      @query_service ||= Valkyrie::Persistence::Memory::QueryService.new(adapter: self)
     end
 
     def cache

data/lib/valkyrie/persistence/memory/persister.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 module Valkyrie::Persistence::Memory
+  # Persister for the memory metadata adapter.
+  # @see Valkyrie::Persistence::Memory
+  # @note Documentation for persisters in general is maintained here.
   class Persister
     attr_reader :adapter
     delegate :cache, to: :adapter
@@ -14,8 +17,11 @@ module Valkyrie::Persistence::Memory
     #   persistence backend.
     def save(resource:)
       resource = generate_id(resource) if resource.id.blank?
+      resource.created_at ||= Time.current
       resource.updated_at = Time.current
+      resource.new_record = false
       normalize_dates!(resource)
+      ensure_multiple_values!(resource)
       cache[resource.id] = resource
     end
 
@@ -34,10 +40,22 @@ module Valkyrie::Persistence::Memory
       cache.delete(resource.id)
     end
 
+    # Wipes all data in the persistence backend.
+    def wipe!
+      cache.clear
+    end
+
     private
 
       def generate_id(resource)
-        resource.new(id: SecureRandom.uuid, created_at: Time.current)
+        resource.new(id: SecureRandom.uuid)
+      end
+
+      def ensure_multiple_values!(resource)
+        bad_keys = resource.attributes.except(:internal_resource, :created_at, :updated_at, :new_record, :id).select do |_k, v|
+          !v.nil? && !v.is_a?(Array)
+        end
+        raise ::Valkyrie::Persistence::UnsupportedDatatype, "#{resource}: #{bad_keys.keys} have non-array values, which can not be persisted by Valkyrie. Cast to arrays." unless bad_keys.keys.empty?
       end
 
       def normalize_dates!(resource)

data/lib/valkyrie/persistence/memory/query_service.rb

@@ -1,28 +1,48 @@
 # frozen_string_literal: true
 module Valkyrie::Persistence::Memory
   class QueryService
-    attr_reader :adapter
+    # Query Service for the memory metadata adapter.
+    # @see Valkyrie::Persistence::Memory
+    # @note Documentation for Query Services in general is maintained here.
+    attr_reader :adapter, :query_handlers
     delegate :cache, to: :adapter
     # @param adapter [Valkyrie::Persistence::Memory::MetadataAdapter] The adapter which
     #   has the cache to query.
     def initialize(adapter:)
       @adapter = adapter
+      @query_handlers = []
     end
 
     # @param id [Valkyrie::ID] The ID to query for.
     # @raise [Valkyrie::Persistence::ObjectNotFoundError] Raised when the ID
     #   isn't in the persistence backend.
+    # @raise [ArgumentError] Raised when ID is not a String or a Valkyrie::ID
     # @return [Valkyrie::Resource] The object being searched for.
     def find_by(id:)
+      id = Valkyrie::ID.new(id.to_s) if id.is_a?(String)
+      validate_id(id)
       cache[id] || raise(::Valkyrie::Persistence::ObjectNotFoundError)
     end
 
+    # @param ids [Array<Valkyrie::ID, String>] The IDs to query for.
+    # @raise [ArgumentError] Raised when any ID is not a String or a Valkyrie::ID
+    # @return [Array<Valkyrie::Resource>] All requested objects that were found
+    def find_many_by_ids(ids:)
+      ids.map do |id|
+        begin
+          find_by(id: id)
+        rescue ::Valkyrie::Persistence::ObjectNotFoundError
+          nil
+        end
+      end.reject(&:nil?)
+    end
+
     # @return [Array<Valkyrie::Resource>] All objects in the persistence backend.
     def find_all
       cache.values
     end
 
-    # @param resource [Class] Class to query for.
+    # @param model [Class] Class to query for.
     # @return [Array<Valkyrie::Resource>] All objects in the persistence backend
     #   with the given class.
     def find_all_of_model(model:)
@@ -32,12 +52,15 @@ module Valkyrie::Persistence::Memory
     end
 
     # @param resource [Valkyrie::Resource] Model whose members are being searched for.
-    # @return [Array<Valkyrie::Resource>] All child objects referenced by `resource`'s
-    #   `member_ids` method. Returned in order.
-    def find_members(resource:)
-      member_ids(resource: resource).map do |id|
+    # @param model [Class] Class to query for. (optional)
+    # @return [Array<Valkyrie::Resource>] child objects of type `model` referenced by
+    #   `resource`'s `member_ids` method. Returned in order.
+    def find_members(resource:, model: nil)
+      result = member_ids(resource: resource).map do |id|
         find_by(id: id)
       end
+      return result unless model
+      result.select { |obj| obj.is_a?(model) }
     end
 
     # @param resource [Valkyrie::Resource] Model whose property is being searched.
@@ -55,10 +78,12 @@ module Valkyrie::Persistence::Memory
     #   other resources.
     # @param property [Symbol] The property which, on other resources, is
     #   referencing the given `resource`
+    # @raise [ArgumentError] Raised when the ID is not in the persistence backend.
     # @return [Array<Valkyrie::Resource>] All resources in the persistence backend
     #   which have the ID of the given `resource` in their `property` property. Not
     #   in order.
     def find_inverse_references_by(resource:, property:)
+      ensure_persisted(resource)
       find_all.select do |obj|
         begin
           Array.wrap(obj[property]).include?(resource.id)
@@ -79,8 +104,24 @@ module Valkyrie::Persistence::Memory
       end
     end
 
-    def member_ids(resource:)
-      resource.member_ids || []
+    def custom_queries
+      @custom_queries ||= ::Valkyrie::Persistence::CustomQueryContainer.new(query_service: self)
     end
+
+    private
+
+      # @return [Array<Valkyrie::ID>] a list of the identifiers of the member objects
+      def member_ids(resource:)
+        return [] unless resource.respond_to? :member_ids
+        resource.member_ids || []
+      end
+
+      def validate_id(id)
+        raise ArgumentError, 'id must be a Valkyrie::ID' unless id.is_a? Valkyrie::ID
+      end
+
+      def ensure_persisted(resource)
+        raise ArgumentError, 'resource is not saved' unless resource.persisted?
+      end
   end
 end

data/lib/valkyrie/persistence/postgres.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
+#
 module Valkyrie::Persistence
+  # Implements the DataMapper Pattern to store metadata into Postgres
   module Postgres
     require 'valkyrie/persistence/postgres/metadata_adapter'
   end

data/lib/valkyrie/persistence/postgres/metadata_adapter.rb

@@ -2,6 +2,12 @@
 require 'valkyrie/persistence/postgres/persister'
 require 'valkyrie/persistence/postgres/query_service'
 module Valkyrie::Persistence::Postgres
+  # Metadata Adapter for Postgres Adapter.
+  #
+  # This adapter uses ActiveRecord to persist resources in a JSON-B column named
+  # `metadata`. This requires setting up a database.
+  #
+  # @see https://github.com/samvera-labs/valkyrie/wiki/Set-up-Valkyrie-database-in-a-Rails-Application
   class MetadataAdapter
     # @return [Class] {Valkyrie::Persistence::Postgres::Persister}
     def persister
@@ -10,9 +16,10 @@ module Valkyrie::Persistence::Postgres
 
     # @return [Class] {Valkyrie::Persistence::Postgres::QueryService}
     def query_service
-      Valkyrie::Persistence::Postgres::QueryService.new(adapter: self)
+      @query_service ||= Valkyrie::Persistence::Postgres::QueryService.new(adapter: self)
     end
 
+    # @return [Class] {Valkyrie::Persistence::Postgres::ResourceFactory}
     def resource_factory
       Valkyrie::Persistence::Postgres::ResourceFactory
     end

data/lib/valkyrie/persistence/postgres/orm.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 require 'valkyrie/persistence/postgres/orm/resource'
 module Valkyrie::Persistence::Postgres
+  # Namespace for ActiveRecord access in Postgres adapter.
   module ORM
     def self.table_name_prefix
       'orm_'

data/lib/valkyrie/persistence/postgres/orm/resource.rb

@@ -1,6 +1,18 @@
 # frozen_string_literal: true
 module Valkyrie::Persistence::Postgres
   module ORM
+    # ActiveRecord class which the Postgres adapter uses for persisting data.
+    # @!attribute id
+    #   @return [UUID] ID of the record
+    # @!attribute metadata
+    #   @return [Hash] Hash of all metadata.
+    # @!attribute created_at
+    #   @return [DateTime] Date created
+    # @!attribute updated_at
+    #   @return [DateTime] Date updated
+    # @!attribute internal_resource
+    #   @return [String] Name of {Valkyrie::Resource} model - used for casting.
+    #
     class Resource < ActiveRecord::Base
     end
   end

data/lib/valkyrie/persistence/postgres/orm_converter.rb

@@ -1,118 +1,143 @@
 # frozen_string_literal: true
 module Valkyrie::Persistence::Postgres
+  # Responsible for converting a
+  # {Valkyrie::Persistence::Postgres::ORM::Resource} to a {Valkyrie::Resource}
   class ORMConverter
     attr_reader :orm_object
     def initialize(orm_object)
       @orm_object = orm_object
     end
 
+    # Create a new instance of the class described in attributes[:internal_resource]
+    # and send it all the attributes that @orm_object has
     def convert!
-      @resource ||= attributes[:internal_resource].constantize.new(attributes)
+      @resource ||= resource
     end
 
-    # @return [Hash] Valkyrie-style hash of attributes.
-    def attributes
-      @attributes ||= orm_object.attributes.merge(rdf_metadata).symbolize_keys
-    end
+    private
 
-    def rdf_metadata
-      @rdf_metadata ||= RDFMetadata.new(orm_object.metadata).result
-    end
+      def resource
+        resource_klass.new(attributes.merge(new_record: false))
+      end
 
-    class RDFMetadata
-      attr_reader :metadata
-      def initialize(metadata)
-        @metadata = metadata
+      def resource_klass
+        internal_resource.constantize
       end
 
-      def result
-        Hash[
-          metadata.map do |key, value|
-            [key, PostgresValue.for(value).result]
-          end
-        ]
+      def internal_resource
+        attributes[:internal_resource]
       end
 
-      class PostgresValue < ::Valkyrie::ValueMapper
+      # @return [Hash] Valkyrie-style hash of attributes.
+      def attributes
+        @attributes ||= orm_object.attributes.merge(rdf_metadata).symbolize_keys
       end
-      # Converts {RDF::Literal} typed-literals from JSON-LD stored into an
-      #   {RDF::Literal}
-      class HashValue < ::Valkyrie::ValueMapper
-        PostgresValue.register(self)
-        def self.handles?(value)
-          value.is_a?(Hash) && value["@value"]
-        end
 
-        def result
-          RDF::Literal.new(value["@value"], language: value["@language"])
-        end
+      def rdf_metadata
+        @rdf_metadata ||= RDFMetadata.new(orm_object.metadata).result
       end
 
-      # Converts stored IDs into {Valkyrie::ID}s
-      class IDValue < ::Valkyrie::ValueMapper
-        PostgresValue.register(self)
-        def self.handles?(value)
-          value.is_a?(Hash) && value["id"] && !value["internal_resource"]
+      # Responsible for converting `metadata` JSON-B field in
+      # {Valkyrie::Persistence::Postgres::ORM::Resource} into an acceptable hash
+      # for {Valkyrie::Resource}
+      class RDFMetadata
+        attr_reader :metadata
+        def initialize(metadata)
+          @metadata = metadata
         end
 
         def result
-          Valkyrie::ID.new(value["id"])
+          Hash[
+            metadata.map do |key, value|
+              [key, PostgresValue.for(value).result]
+            end
+          ]
         end
-      end
 
-      # Converts stored URIs into {RDF::URI}s
-      class URIValue < ::Valkyrie::ValueMapper
-        PostgresValue.register(self)
-        def self.handles?(value)
-          value.is_a?(Hash) && value["@id"]
+        class PostgresValue < ::Valkyrie::ValueMapper
         end
+        # Converts {RDF::Literal} typed-literals from JSON-LD stored into an
+        #   {RDF::Literal}
+        class HashValue < ::Valkyrie::ValueMapper
+          PostgresValue.register(self)
+          def self.handles?(value)
+            value.is_a?(Hash) && value["@value"]
+          end
 
-        def result
-          ::RDF::URI.new(value["@id"])
+          def result
+            RDF::Literal.new(value["@value"],
+                             language: value["@language"],
+                             datatype: value["@type"])
+          end
         end
-      end
 
-      # Converts nested records into {Valkyrie::Resource}s
-      class NestedRecord < ::Valkyrie::ValueMapper
-        PostgresValue.register(self)
-        def self.handles?(value)
-          value.is_a?(Hash) && value.keys.length > 1
-        end
+        # Converts stored IDs into {Valkyrie::ID}s
+        class IDValue < ::Valkyrie::ValueMapper
+          PostgresValue.register(self)
+          def self.handles?(value)
+            value.is_a?(Hash) && value["id"] && !value["internal_resource"]
+          end
 
-        def result
-          RDFMetadata.new(value).result.symbolize_keys
+          def result
+            Valkyrie::ID.new(value["id"])
+          end
         end
-      end
 
-      class DateValue < ::Valkyrie::ValueMapper
-        PostgresValue.register(self)
-        def self.handles?(value)
-          return false unless value.is_a?(String)
-          return false unless value[4] == "-"
-          year = value.to_s[0..3]
-          return false unless year.length == 4 && year.to_i.to_s == year
-          DateTime.iso8601(value)
-        rescue
-          false
+        # Converts stored URIs into {RDF::URI}s
+        class URIValue < ::Valkyrie::ValueMapper
+          PostgresValue.register(self)
+          def self.handles?(value)
+            value.is_a?(Hash) && value["@id"]
+          end
+
+          def result
+            ::RDF::URI.new(value["@id"])
+          end
         end
 
-        def result
-          DateTime.iso8601(value).utc
+        # Converts nested records into {Valkyrie::Resource}s
+        class NestedRecord < ::Valkyrie::ValueMapper
+          PostgresValue.register(self)
+          def self.handles?(value)
+            value.is_a?(Hash) && value.keys.length > 1
+          end
+
+          def result
+            RDFMetadata.new(value).result.symbolize_keys
+          end
         end
-      end
 
-      class EnumeratorValue < ::Valkyrie::ValueMapper
-        PostgresValue.register(self)
-        def self.handles?(value)
-          value.respond_to?(:each)
+        # Converts Date strings to `DateTime`
+        class DateValue < ::Valkyrie::ValueMapper
+          PostgresValue.register(self)
+          def self.handles?(value)
+            return false unless value.is_a?(String)
+            return false unless value[4] == "-"
+            year = value.to_s[0..3]
+            return false unless year.length == 4 && year.to_i.to_s == year
+            DateTime.iso8601(value)
+          rescue
+            false
+          end
+
+          def result
+            DateTime.iso8601(value).utc
+          end
         end
 
-        def result
-          value.map do |value|
-            calling_mapper.for(value).result
+        # Handles iterating over arrays of values and converting each value.
+        class EnumeratorValue < ::Valkyrie::ValueMapper
+          PostgresValue.register(self)
+          def self.handles?(value)
+            value.respond_to?(:each)
+          end
+
+          def result
+            value.map do |value|
+              calling_mapper.for(value).result
+            end
           end
         end
       end
-    end
   end
 end