cuprum-collections 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53ab28a09a25a4de8a7ca405a3f59b45b5b9cec3fc0acd243a8815bfdfee80ae
-  data.tar.gz: aef7d1257fd0997c284a1cad91118086ae2672789fe40d9648fc6a553fb70abd
+  metadata.gz: 78622fdeb8107cc8df27120e104a7b4ab1239569f8677b648b3462b36b4c008c
+  data.tar.gz: 0ca7eeb33a33d477888851d1a515b9e0c7cae3dc80a7a85f5455747ea1275ddc
 SHA512:
-  metadata.gz: 2f9544cd606500cca431300aa4432ab58a475fbb2ee6c813bbdef36d8a10a5cec3eea7b219eb16dfcf4a810fa022154e554e61373ad47e080818933f97f76d74
-  data.tar.gz: 46f80cf9f3d575e564a46230fc65c984d4886f7f23ca62cdd2454f528a9d2f96fc70e31d23f222c7acd944ab5f5a9a468f94ed3a928a191d5bdaf0057219288a
+  metadata.gz: 40a8281d4232bf7e8e78450d99dde47089dbbc039c7f7c689c579d98bf22d3069e3e9c0f3066ebca1d4ce292fb170738f5ed71afb8b49a875648333d81523f08
+  data.tar.gz: fc9c9d23db953377b34397a89fdd4098e170b1b2db3f84261562c473d932e881dbcc92237d5fb53a8b819a722bef5d89f545418fca9e527e8dfc0271c4aacd3c

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.2.0
+
+Implemented `Cuprum::Collections::Repository`.
+
+### Collections
+
+Implemented `Cuprum::Collections::Basic::Repository`.
+
+### Queries
+
+Fixed passing an attributes array as a query ordering.
+
 ## 0.1.0
 
 Initial version.

data/README.md

@@ -77,7 +77,7 @@ steps do
   # Build the book from attributes.
   book = step do
     collection.build_one.call(
-      attributes: { id: 10, title: 'Gideon the Ninth', author: 'Tammsyn Muir' }
+      attributes: { id: 10, title: 'Gideon the Ninth', author: 'Tamsyn Muir' }
     )
   end
 
@@ -116,7 +116,7 @@ Structurally, a collection is a set of commands, which are instances of `Cuprum:
 The `AssignOne` command takes an attributes hash and an entity, and returns an instance of the entity class whose attributes are equal to the attributes hash merged into original entities attributes. Depending on the collection, `#assign_one` may or may not modify or return the original entity.
 
 ```ruby
-book       = { 'id' => 10, 'title' => 'Gideon the Ninth', 'author' => 'Tammsyn Muir' }
+book       = { 'id' => 10, 'title' => 'Gideon the Ninth', 'author' => 'Tamsyn Muir' }
 attributes = { 'title' => 'Harrow the Ninth', 'published_at' => '2020-08-04' }
 result     = collection.assign_one.call(attributes: attributes, entity: entity)
 
@@ -124,7 +124,7 @@ result.value
 #=> {
 #     'id'           => 10,
 #     'title'        => 'Harrow the Ninth',
-#     'author'       => 'Tammsyn Muir',
+#     'author'       => 'Tamsyn Muir',
 #     'published_at' => '2020-08-04'
 #   }
 ```
@@ -136,14 +136,14 @@ If the entity class specifies a set of attributes (such as the defined columns i
 The `BuildOne` command takes an attributes hash and returns a new instance of the entity class whose attributes are equal to the given attributes. This does not validate or persist the entity; it is equivalent to calling `entity_class.new` with the attributes.
 
 ```ruby
-attributes = { 'id' => 10, 'title' => 'Gideon the Ninth', 'author' => 'Tammsyn Muir' }
+attributes = { 'id' => 10, 'title' => 'Gideon the Ninth', 'author' => 'Tamsyn Muir' }
 result     = collection.build_one.call(attributes: attributes, entity: entity)
 
 result.value
 #=> {
 #     'id'           => 10,
 #     'title'        => 'Gideon the Ninth',
-#     'author'       => 'Tammsyn Muir'
+#     'author'       => 'Tamsyn Muir'
 #   }
 ```
 
@@ -298,14 +298,14 @@ If the collection does not include an entity with the specified primary key, the
 The `InsertOne` command takes an entity and inserts that entity into the collection.
 
 ```ruby
-book       = { 'id' => 10, 'title' => 'Gideon the Ninth', 'author' => 'Tammsyn Muir' }
+book       = { 'id' => 10, 'title' => 'Gideon the Ninth', 'author' => 'Tamsyn Muir' }
 result     = collection.insert_one.call(entity: entity)
 
 result.value
 #=> {
 #     'id'           => 10,
 #     'title'        => 'Gideon the Ninth',
-#     'author'       => 'Tammsyn Muir'
+#     'author'       => 'Tamsyn Muir'
 #   }
 
 collection.query.where(id: 10).exists?
@@ -351,7 +351,7 @@ contract = Stannum::Contract.new do
   property :title, Stannum::Constraints::Presence.new
 end
 
-book   = { 'id' => 10, 'title' => 'Gideon the Ninth', 'author' => 'Tammsyn Muir' }
+book   = { 'id' => 10, 'title' => 'Gideon the Ninth', 'author' => 'Tamsyn Muir' }
 result = collection.validate_one.call(contract: contract, entity: book)
 result.success?
 #=> true
@@ -361,9 +361,34 @@ If the contract does not match the entity, the `#validate_one` command will retu
 
 If the collection does not specify a default contract and no `:contract` keyword is provided, the `#validate_one` command will return a failing result with a `MissingDefaultContract` error.
 
-#### Basic Collection
+<a id="repositories"></a>
+
+#### Repositories
+
+```ruby
+require 'cuprum/collections/repository'
+```
+
+A repository is a group of collections. While a collection might be be a single data set, such as the records in a table, the repository represents all of the data sets in a data source, such as the tables in a database.
+
+```ruby
+repository = Cuprum::Collections::Repository.new
+repository.key?('book')
+#=> false
 
+repository.add(books_collection)
+
+repository.key?('book')
+#=> true
+repository.keys
+#=> ['books']
+repository['books']
+#=> the books collection
 ```
+
+#### Basic Collection
+
+```ruby
 require 'cuprum/collections/basic'
 ```
 
@@ -388,6 +413,40 @@ You can also specify some optional keywords:
 - The `:primary_key_name` parameter specifies the attribute that serves as the primary key for the collection entities. The default value is `:id`.
 - The `:primary_key_type` parameter specifies the type of the primary key attribute. The default value is `Integer`.
 
+##### Basic Repositories
+
+```ruby
+require 'cuprum/collections/basic/repository'
+```
+
+A `Basic::Repository` is a collection of `Basic::Collection`s. In addition to implementing the Repository methods (see [Repositories](#repositories), above), a basic repository can be initialized with a data set and used to build new collections directly.
+
+```ruby
+data = {
+  'books' => [
+    {
+      'name'   => 'Gideon the Ninth',
+      'author' => 'Tamsyn Muir'
+    }
+  ]
+}
+repository = Cuprum::Collections::Basic::Repository.new(data: data)
+repository.keys
+#=> []
+
+repository.build(collection_name: 'books')
+#=> an instance of Cuprum::Collections::Basic::Collection
+repository.keys
+#=> ['books']
+repository['books'].query.to_a
+#=> [
+#     {
+#       'name'   => 'Gideon the Ninth',
+#       'author' => 'Tamsyn Muir'
+#     }
+#   ]
+```
+
 <a id="constraints"></a>
 
 ### Constraints
@@ -686,7 +745,7 @@ The `#reset` method takes no parameters and returns the query. By default, a `Qu
 query.count
 #=> 10
 
-book = { id: 10, title: 'Gideon the Ninth', author: 'Tammsyn Muir' }
+book = { id: 10, title: 'Gideon the Ninth', author: 'Tamsyn Muir' }
 collection.insert_one.call(entity: book)
 
 query.count

data/lib/cuprum/collections/basic/repository.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/basic'
+require 'cuprum/collections/basic/collection'
+require 'cuprum/collections/repository'
+
+module Cuprum::Collections::Basic
+  # A repository represents a group of Basic collections.
+  class Repository < Cuprum::Collections::Repository
+    # @param data [Hash<String, Object>] Seed data to use when building
+    #   collections.
+    def initialize(data: {})
+      super()
+
+      @data = data
+    end
+
+    # Adds a new collection with the given name to the repository.
+    #
+    # @param collection_name [String] The name of the new collection.
+    # @param data [Hash<String, Object>] The inital data for the collection. If
+    #   not specified, defaults to the data used to initialize the repository.
+    # @param options [Hash] Additional options to pass to Collection.new
+    #
+    # @return [Cuprum::Collections::Basic::Collection] the created collection.
+    #
+    # @see Cuprum::Collections::Basic::Collection#initialize.
+    def build(collection_name:, data: nil, **options)
+      validate_collection_name!(collection_name)
+      validate_data!(data)
+
+      collection = Cuprum::Collections::Basic.new(
+        collection_name: collection_name,
+        data:            data || @data.fetch(collection_name.to_s, []),
+        **options
+      )
+
+      add(collection)
+
+      collection
+    end
+
+    private
+
+    def valid_collection?(collection)
+      collection.is_a?(Cuprum::Collections::Basic::Collection)
+    end
+
+    def validate_collection_name!(name)
+      raise ArgumentError, "collection name can't be blank" if name.nil?
+
+      unless name.is_a?(String) || name.is_a?(Symbol)
+        raise ArgumentError, 'collection name must be a String or Symbol'
+      end
+
+      return unless name.empty?
+
+      raise ArgumentError, "collection name can't be blank"
+    end
+
+    def validate_data!(data)
+      return if data.nil? || data.is_a?(Array)
+
+      raise ArgumentError, 'data must be an Array of Hashes'
+    end
+  end
+end

data/lib/cuprum/collections/queries/ordering.rb

@@ -33,6 +33,8 @@ module Cuprum::Collections::Queries
       #   @raise InvalidOrderError if any of the hash keys are invalid attribute
       #     names, or any of the hash values are invalid sort directions.
       def normalize(*attributes)
+        attributes = attributes.flatten if attributes.first.is_a?(Array)
+
         validate_ordering!(attributes)
 
         qualified = attributes.last.is_a?(Hash) ? attributes.pop : {}

data/lib/cuprum/collections/repository.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+require 'cuprum/collections'
+
+module Cuprum::Collections
+  # A repository represents a group of collections.
+  #
+  # Conceptually, a repository represents one or more underlying data stores. An
+  # application might have one repository for each data store, e.g. one
+  # repository for relational data, a second repository for document-based data,
+  # and so on. The application may instead aggregate all of its collections into
+  # a single repository, relying on the shared interface of all Collection
+  # implementations.
+  class Repository
+    extend Forwardable
+
+    # Error raised when trying to add an invalid collection to the repository.
+    class InvalidCollectionError < StandardError; end
+
+    # Error raised when trying to access a collection that is not defined.
+    class UndefinedCollectionError < StandardError; end
+
+    def initialize
+      @collections = {}
+    end
+
+    # @!method keys
+    #   Returns the names of the collections in the repository.
+    #
+    #   @return [Array<String>] the collection names.
+
+    def_delegators :@collections, :keys
+
+    # Finds and returns the collection with the given name.
+    #
+    # @param collection_name [String, Symbol] The name of the collection to
+    #   return.
+    #
+    # @return [Object] the requested collection.
+    #
+    # @raise [Cuprum::Collection::Repository::UndefinedCOllectionError] if the
+    #   requested collection is not in the repository.
+    def [](collection_name)
+      @collections.fetch(collection_name.to_s) do
+        raise UndefinedCollectionError,
+          "repository does not define collection #{collection_name.inspect}"
+      end
+    end
+
+    # Adds the collection to the repository.
+    #
+    # The collection must implement the #collection_name property. Repository
+    # subclasses may enforce additional requirements.
+    #
+    # @param collection [#collection_name] The collection to add to the
+    #   repository.
+    #
+    # @return [Cuprum::Rails::Repository] the repository.
+    def add(collection)
+      validate_collection!(collection)
+
+      @collections[collection.collection_name.to_s] = collection
+
+      self
+    end
+    alias << add
+
+    # Checks if a collection with the given name exists in the repository.
+    #
+    # @param collection_name [String, Symbol] The name to check for.
+    #
+    # @return [true, false] true if the key exists, otherwise false.
+    def key?(collection_name)
+      @collections.key?(collection_name.to_s)
+    end
+
+    private
+
+    def valid_collection?(collection)
+      collection.respond_to?(:collection_name)
+    end
+
+    def validate_collection!(collection)
+      return if valid_collection?(collection)
+
+      raise InvalidCollectionError,
+        "#{collection.inspect} is not a valid collection"
+    end
+  end
+end

data/lib/cuprum/collections/rspec/assign_one_command_contract.rb

@@ -58,7 +58,7 @@ module Cuprum::Collections::RSpec
         let(:attributes) do
           {
             title:    'Gideon the Ninth',
-            author:   'Tammsyn Muir',
+            author:   'Tamsyn Muir',
             series:   'The Locked Tomb',
             category: 'Horror'
           }
@@ -124,7 +124,7 @@ module Cuprum::Collections::RSpec
           let(:attributes) do
             {
               title:    'Gideon the Ninth',
-              author:   'Tammsyn Muir',
+              author:   'Tamsyn Muir',
               series:   'The Locked Tomb',
               category: 'Horror'
             }

data/lib/cuprum/collections/rspec/build_one_command_contract.rb

@@ -50,7 +50,7 @@ module Cuprum::Collections::RSpec
         let(:attributes) do
           {
             title:    'Gideon the Ninth',
-            author:   'Tammsyn Muir',
+            author:   'Tamsyn Muir',
             series:   'The Locked Tomb',
             category: 'Horror'
           }

data/lib/cuprum/collections/rspec/repository_contract.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/rspec'
+
+module Cuprum::Collections::RSpec
+  # Contract validating the behavior of a Repository.
+  REPOSITORY_CONTRACT = lambda do
+    describe '#[]' do
+      let(:error_class) do
+        described_class::UndefinedCollectionError
+      end
+      let(:error_message) do
+        "repository does not define collection #{collection_name.inspect}"
+      end
+
+      it { expect(repository).to respond_to(:[]).with(1).argument }
+
+      describe 'with nil' do
+        let(:collection_name) { nil }
+
+        it 'should raise an exception' do
+          expect { repository[collection_name] }
+            .to raise_error(error_class, error_message)
+        end
+      end
+
+      describe 'with an object' do
+        let(:collection_name) { Object.new.freeze }
+
+        it 'should raise an exception' do
+          expect { repository[collection_name] }
+            .to raise_error(error_class, error_message)
+        end
+      end
+
+      describe 'with an invalid string' do
+        let(:collection_name) { 'invalid_name' }
+
+        it 'should raise an exception' do
+          expect { repository[collection_name] }
+            .to raise_error(error_class, error_message)
+        end
+      end
+
+      describe 'with an invalid symbol' do
+        let(:collection_name) { :invalid_name }
+
+        it 'should raise an exception' do
+          expect { repository[collection_name] }
+            .to raise_error(error_class, error_message)
+        end
+      end
+
+      wrap_context 'when the repository has many collections' do
+        describe 'with an invalid string' do
+          let(:collection_name) { 'invalid_name' }
+
+          it 'should raise an exception' do
+            expect { repository[collection_name] }
+              .to raise_error(error_class, error_message)
+          end
+        end
+
+        describe 'with an invalid symbol' do
+          let(:collection_name) { :invalid_name }
+
+          it 'should raise an exception' do
+            expect { repository[collection_name] }
+              .to raise_error(error_class, error_message)
+          end
+        end
+
+        describe 'with a valid string' do
+          let(:collection_name) { collection_names.first }
+
+          it { expect(repository[collection_name]).to be books_collection }
+        end
+
+        describe 'with a valid symbol' do
+          let(:collection_name) { collection_names.first.intern }
+
+          it { expect(repository[collection_name]).to be books_collection }
+        end
+      end
+    end
+
+    describe '#add' do
+      let(:error_class) do
+        described_class::InvalidCollectionError
+      end
+      let(:error_message) do
+        "#{collection.inspect} is not a valid collection"
+      end
+
+      it { expect(repository).to respond_to(:add).with(1).argument }
+
+      it 'should alias #add as #<<' do
+        expect(repository.method(:<<)).to be == repository.method(:add)
+      end
+
+      describe 'with nil' do
+        let(:collection) { nil }
+
+        it 'should raise an exception' do
+          expect { repository.add(collection) }
+            .to raise_error(error_class, error_message)
+        end
+      end
+
+      describe 'with an object' do
+        let(:collection) { Object.new.freeze }
+
+        it 'should raise an exception' do
+          expect { repository.add(collection) }
+            .to raise_error(error_class, error_message)
+        end
+      end
+
+      describe 'with a collection' do
+        it { expect(repository.add(example_collection)).to be repository }
+
+        it 'should add the collection to the repository' do
+          repository.add(example_collection)
+
+          expect(repository[example_collection.collection_name])
+            .to be example_collection
+        end
+      end
+    end
+
+    describe '#key?' do
+      it { expect(repository).to respond_to(:key?).with(1).argument }
+
+      it { expect(repository.key? nil).to be false }
+
+      it { expect(repository.key? Object.new.freeze).to be false }
+
+      it { expect(repository.key? 'invalid_name').to be false }
+
+      it { expect(repository.key? :invalid_name).to be false }
+
+      wrap_context 'when the repository has many collections' do
+        it { expect(repository.key? 'invalid_name').to be false }
+
+        it { expect(repository.key? :invalid_name).to be false }
+
+        it { expect(repository.key? collection_names.first).to be true }
+
+        it { expect(repository.key? collection_names.first.intern).to be true }
+      end
+    end
+
+    describe '#keys' do
+      include_examples 'should define reader', :keys, []
+
+      wrap_context 'when the repository has many collections' do
+        it { expect(repository.keys).to be == collection_names }
+      end
+    end
+  end
+end

data/lib/cuprum/collections/version.rb

@@ -11,7 +11,7 @@ module Cuprum
       # Major version.
       MAJOR = 0
       # Minor version.
-      MINOR = 1
+      MINOR = 2
       # Patch version.
       PATCH = 0
       # Prerelease version.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cuprum-collections
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Rob "Merlin" Smith
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-10-19 00:00:00.000000000 Z
+date: 2021-10-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cuprum
@@ -143,6 +143,7 @@ files:
 - lib/cuprum/collections/basic/commands/validate_one.rb
 - lib/cuprum/collections/basic/query.rb
 - lib/cuprum/collections/basic/query_builder.rb
+- lib/cuprum/collections/basic/repository.rb
 - lib/cuprum/collections/basic/rspec.rb
 - lib/cuprum/collections/basic/rspec/command_contract.rb
 - lib/cuprum/collections/command.rb
@@ -175,6 +176,7 @@ files:
 - lib/cuprum/collections/queries/parse_strategy.rb
 - lib/cuprum/collections/query.rb
 - lib/cuprum/collections/query_builder.rb
+- lib/cuprum/collections/repository.rb
 - lib/cuprum/collections/rspec.rb
 - lib/cuprum/collections/rspec/assign_one_command_contract.rb
 - lib/cuprum/collections/rspec/build_one_command_contract.rb
@@ -188,6 +190,7 @@ files:
 - lib/cuprum/collections/rspec/query_builder_contract.rb
 - lib/cuprum/collections/rspec/query_contract.rb
 - lib/cuprum/collections/rspec/querying_contract.rb
+- lib/cuprum/collections/rspec/repository_contract.rb
 - lib/cuprum/collections/rspec/update_one_command_contract.rb
 - lib/cuprum/collections/rspec/validate_one_command_contract.rb
 - lib/cuprum/collections/version.rb