cuprum-collections 0.1.0 → 0.3.0.rc.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53ab28a09a25a4de8a7ca405a3f59b45b5b9cec3fc0acd243a8815bfdfee80ae
-  data.tar.gz: aef7d1257fd0997c284a1cad91118086ae2672789fe40d9648fc6a553fb70abd
+  metadata.gz: 077ded1de1d41e29689ed46422c0ba4b367d333a495f568f461c9a5a0d8c5278
+  data.tar.gz: 82e9ec27fcdf2975f37f24f680cd2a0d653ec529c6884a6e9c8ad8cd33a5f4ed
 SHA512:
-  metadata.gz: 2f9544cd606500cca431300aa4432ab58a475fbb2ee6c813bbdef36d8a10a5cec3eea7b219eb16dfcf4a810fa022154e554e61373ad47e080818933f97f76d74
-  data.tar.gz: 46f80cf9f3d575e564a46230fc65c984d4886f7f23ca62cdd2454f528a9d2f96fc70e31d23f222c7acd944ab5f5a9a468f94ed3a928a191d5bdaf0057219288a
+  metadata.gz: 623403206ee2a4ed953069e67e04f6c06038157fa3ac2701e65cd3e2739b49e4579a1379f2f04b7324df646de1b2c667749c8a9ae5c576bdbc587f88bcd7be7c
+  data.tar.gz: 5cc578f36e263ed5b83c46e902222286f47a1d2588aad8b43817686cd814242205c81d02591921895510ab551a8afdd96384c1a7fe7e0a4557dd991b5a641d0e

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.2.0
+
+Implemented `Cuprum::Collections::Repository`.
+
+### Collections
+
+Updated `Cuprum::Collections::Basic::Collection`.
+
+- Implemented `#count` method.
+- Implemented `#qualified_name` method.
+
+Implemented `Cuprum::Collections::Basic::Repository`.
+
+### Commands
+
+Implemented built-in Commands, which take a `:collection` parameter:
+
+- `Commands::Create`
+- `Commands::FindOneMatching`
+- `Commands::Update`
+- `Commands::Upsert`
+
+### Queries
+
+Fixed passing an attributes array as a query ordering.
+
 ## 0.1.0
 
 Initial version.

data/README.md

@@ -26,7 +26,7 @@ The Ruby ecosystem has a wide variety of tools and libraries for managing data a
 
 ### Compatibility
 
-Cuprum::Collections is tested against Ruby (MRI) 2.6 through 2.7.
+Cuprum::Collections is tested against Ruby (MRI) 2.7 through 3.2.
 
 ### Documentation
 
@@ -34,9 +34,9 @@ Documentation is generated using [YARD](https://yardoc.org/), and can be generat
 
 ### License
 
-Copyright (c) 2020-2021 Rob Smith
+Copyright (c) 2020-2023 Rob Smith
 
-Stannum is released under the [MIT License](https://opensource.org/licenses/MIT).
+Cuprum::Collections is released under the [MIT License](https://opensource.org/licenses/MIT).
 
 ### Contribute
 
@@ -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
 
@@ -105,6 +105,13 @@ end
 
 Because a collection can represent any sort of data, from a raw Ruby Hash to an ORM record, the term used to indicate "one item in the collection" is an *entity*. Likewise, the class of the items in the collection is the *entity_class*. In our example above, our entities are books, and the entity class is Hash.
 
+Each collection also defines the following methods:
+
+- `#collection_name`: The collection name is a short description of what the collection contains. For example, a collection of `Book` objects might have a collection name of `'books'`, while a collection of `Authorization::Credentials::ApiKey` objects might have a collection name of `'api_keys'`.
+- `#qualified_name`: The qualified name is a full description of the collection, and should be unique. For example, a collection of `Book` objects might have a qualified name of `'books'`, while a collection of `Authorization::Credentials::ApiKey` objects might have a qualified name of `'authorization/credentials/api_keys'`.
+
+As a general rule, the `#collection_name` is used when displaying information to the user, while the `#qualified_name` is used to uniquely identify the collection (such as when adding to or retrieving from a [Repository](#repositories)).
+
 <a id="commands"></a>
 
 #### Commands
@@ -116,7 +123,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 +131,7 @@ result.value
 #=> {
 #     'id'           => 10,
 #     'title'        => 'Harrow the Ninth',
-#     'author'       => 'Tammsyn Muir',
+#     'author'       => 'Tamsyn Muir',
 #     'published_at' => '2020-08-04'
 #   }
 ```
@@ -136,14 +143,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'
 #   }
 ```
 
@@ -214,7 +221,7 @@ If the collection does not include an entity with each of the specified primary
 
 ##### Find Matching
 
-The `FindMatching` command takes a set of query parameters and queries data from the collection. You can specify filters using the `:where` keyword or by passing a block, sort the results using the `:order` keyword, or return a subset of the results using the `:limit` and `:offset` keywords. For full details on performing queries, see [Queries](#queries), below.
+The `FindMatching` command takes a set of query parameters and queries data from the collection. You can specify filters using the `:where` keyword or by passing a block, sort the results using the `:order` keyword, or return a subset of the results using the `:limit` and `:offset` keywords.
 
 ```ruby
 result =
@@ -260,7 +267,11 @@ The `FindMatching` command has several options:
     #=>  { books: [{ ... }, { ... }, { ... }] }
     ```
 
+- The `:limit` keyword caps the number of results returned.
+- The `:offset` keyword skips the specified number of results.
+- The `:order` keyword specifies the order of results.
 - The `:scope` keyword allows you to pass a query to the command. Only entities that match the given scope will be found and returned by `#find_matching`.
+- The `:where` keyword defines filters for which results are to be returned.
 
 ##### Find One
 
@@ -298,14 +309,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' }
-result     = collection.insert_one.call(entity: entity)
+book       = { 'id' => 10, 'title' => 'Gideon the Ninth', 'author' => 'Tamsyn Muir' }
+result     = collection.insert_one.call(entity: book)
 
 result.value
 #=> {
 #     'id'           => 10,
 #     'title'        => 'Gideon the Ninth',
-#     'author'       => 'Tammsyn Muir'
+#     'author'       => 'Tamsyn Muir'
 #   }
 
 collection.query.where(id: 10).exists?
@@ -351,7 +362,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 +372,59 @@ 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. Each repository uses the `#qualified_name` of its collections as a unique key.
+
+```ruby
+repository = Cuprum::Collections::Repository.new
+repository.key?('books')
+#=> false
+
+repository.add(books_collection)
+
+repository.key?('books')
+#=> true
+repository.keys
+#=> ['books']
+repository['books']
+#=> the books collection
+```
+
+When accessing a collection with a qualified name, you must pass the qualified name to `#[]` or `#key?`, rather than the collection name.
+
+```ruby
+repository = Cuprum::Collections::Repository.new
+repository.key?('api_keys')
+#=> false
+repository.key?('authorization/credentials/api_keys')
+#=> false
 
+api_keys_collection.collection_name
+#=> 'api_keys'
+api_keys_collection.qualified_name
+#=> 'authorization/credentials/api_keys'
+repository.add(api_keys_collection)
+
+repository.key?('api_keys')
+#=> false
+repository.key?('authorization/credentials/api_keys')
+#=> true
+repository.keys
+#=> ['authorization/credentials/api_keys']
+repository['authorization/credentials/api_keys']
+#=> the api keys collection
 ```
+
+#### Basic Collection
+
+```ruby
 require 'cuprum/collections/basic'
 ```
 
@@ -387,6 +448,41 @@ You can also specify some optional keywords:
 - The `:member_name` parameter is used to create an envelope for singular query commands such as the `FindOne` command. If not given, the member name will be generated automatically as a singular form of the collection name.
 - 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`.
+- The `:qualified_name` parameter sets the qualified name for the collection. It is used to uniquely identify the collection in a repository.
+
+##### 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>
 
@@ -686,7 +782,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
@@ -948,3 +1044,213 @@ query.each.map(&:title)
 #     'The Farthest Shore'
 #   ]
 ```
+
+<a id="builtin-commands"></a>
+
+### Built In Commands
+
+`Cuprum::Collections` defines some basic commands. Each command takes a `:collection` parameter, which is used for performing the data operations.
+
+#### Create
+
+```ruby
+require 'cuprum/collections/commands/create'
+```
+
+The `Create` command takes an attributes Hash and adds an entity with those attributes to the collection. Internally, it calls the `#build_one`, `#validate_one`, and `#insert_one` commands on the collection.
+
+```ruby
+command = Cuprum::Collections::Commands::Create.new(collection: books_collection)
+
+books_collection.count
+#=> 0
+result = command.call(attributes: { 'title' => 'Gideon the Ninth' })
+result.value
+#=> a Book with title "Gideon the Ninth"
+books_collection.count
+#=> 1
+
+books_collection.find_matching.call { { 'title' => 'Gideon the Ninth' } }.value.first
+#=> a Book with title "Gideon the Ninth"
+```
+
+If the contract does not match the entity, the `Create` command will return a failing result with a `ValidationFailed` error.
+
+If the collection does not specify a default contract and no :contract keyword is provided, the `Create` command will return a failing result with a `MissingDefaultContract` error.
+
+If the collection already includes an entity with the specified primary key, the `Create` command will return a failing result with an `AlreadyExists` error.
+
+#### FindOneMatching
+
+```ruby
+require 'cuprum/collections/commands/find_one_matching'
+```
+
+The `FindOneMatching` command takes either an attributes hash or a [Query](#queries) block, and returns the unique entity from the collection with those entities or matching that query.
+
+```ruby
+command = Cuprum::Collections::Commands::FindOneMatching.new(collection: books_collection)
+
+result = command.call(attributes: { 'title' => 'Gideon the Ninth'})
+result.success?
+#=> true
+result.value
+#=> the unique Book with title "Gideon the Ninth"
+
+result = command.call do
+  {
+    'series'       => 'The Locked Tomb',
+    'published_at' => less_than('2020-01-01')
+  }
+end
+result.success?
+#=> true
+result.value
+#=> the unique Book with the given series and published before the given date
+```
+
+If there are no entities in the collection matching the attributes or query, the `FindOneMatching` command returns a failing result with a `Cuprum::Collections::Errors::NotFound` error.
+
+```ruby
+result = command.call(attributes: { 'title' => 'Gideon the Eleventh'})
+result.success?
+#=> false
+result.error
+#=> an instance of Cuprum::Collections::Errors::NotFound
+```
+
+If there are two or more entities in the collection matching the attributes or query, the `FindOneMatching` command returns a failing result with a `Cuprum::Collections::Errors::NotUnique` error.
+
+```ruby
+result = command.call(attributes: { 'author' => 'Tamsyn Muir'})
+result.success?
+#=> false
+result.error
+#=> an instance of Cuprum::Collections::Errors::NotUnique
+```
+
+#### Update
+
+```ruby
+require 'cuprum/collections/commands/update'
+```
+
+The `Update` command takes an attributes Hash and an entity and updates the corresponding entity in the collection with those attributes. Internally, it calls the `#assign_one`, `#validate_one`, and `#update_one` commands on the collection.
+
+```ruby
+command = Cuprum::Collections::Commands::Update.new(collection: books_collection)
+
+entity = books_collection.find_matching.call { { 'title' => 'Gideon the Ninth' } }.value.first
+#=> a Book with title "Gideon the Ninth" and series "The Locked Tomb"
+
+result = command.call(
+  attributes: { 'series' => 'Space Necromancers' },
+  entity:     entity
+)
+result.value
+#=> a Book with title "Gideon the Ninth" and series "Space Necromancers"
+
+books_collection.find_matching.call { { 'title' => 'Gideon the Ninth' } }.value.first
+#=> a Book with title "Gideon the Ninth" and series "Space Necromancers"
+```
+
+If the contract does not match the entity, the `Update` command will return a failing result with a `ValidationFailed` error.
+
+If the collection does not specify a default contract and no :contract keyword is provided, the `Update` command will return a failing result with a `MissingDefaultContract` error.
+
+If the collection does not include an entity with the specified entity's primary key, the `Update` command will return a failing result with a `NotFound` error.
+
+#### Upsert
+
+```ruby
+require 'cuprum/collections/commands/upsert'
+```
+
+The `Upsert` command takes an attributes Hash and checks the collection for an entity with a matching primary key. If an entity is found, it updates the entity with the given attributes, as per the `Update` command (see above); if an entity is not found, it creates a new entity with the given attributes, as per the `Create` command.
+
+```ruby
+command = Cuprum::Collections::Commands::Upsert.new(collection: books_collection)
+
+# Creating An Entity
+books_collection.count
+#=> 0
+result = command.call(attributes: { 'id' => 0, 'title' => 'Gideon the Ninth' })
+result.value
+#=> a Book with id 0 and title "Gideon the Ninth"
+books_collection.count
+#=> 1
+
+books_collection.find_matching.call { { 'title' => 'Gideon the Ninth' } }.value.first
+#=> a Book with id 0 and title "Gideon the Ninth"
+
+# Updating An Entity
+result = command.call(attributes: { 'id' => 0, 'author' => 'Tamsyn Muir' })
+result.value
+#=> a Book with id 0, title "Gideon the Ninth", and author "Tamsyn Muir"
+
+books_collection.find_matching.call { { 'title' => 'Gideon the Ninth' } }.value.first
+#=> a Book with id 0, title "Gideon the Ninth", and author "Tamsyn Muir"
+```
+
+The `Upsert` command can also be configured with an attribute name or list of attribute names; the command will then search for an entity in the collection matching those attributes, rather than by primary key.
+
+```ruby
+command      =
+  Cuprum::Collections::Commands::Upsert
+  .new(attribute_names: %w[title author], collection: books_collection)
+other_entity = books_collection.build_one.call(
+  attributes: {
+    'id'     => 0,
+    'title'  => 'Gideon the Ninth',
+    'author' => 'T. M.'
+  }
+)
+books_collection.insert_one.call(entity: entity)
+
+# Creating An Entity
+books_collection.count
+#=> 1
+result = command.call(
+  attributes: {
+    'id'     => 1,
+    'title'  => 'Gideon the Ninth',
+    'author' => 'Tamsyn Muir'
+  }
+)
+result.value
+#=> a Book with id 1, title "Gideon the Ninth", and author "Tamsyn Muir"
+books_collection.count
+#=> 1
+
+books_collection.find_matching.call { { 'title' => 'Gideon the Ninth' } }.value.count
+#=> 2
+books_collection.find_matching.call { { 'title' => 'Gideon the Ninth' } }.value.map(&:author)
+#=> ['T. M.', 'Tamsyn Muir']
+
+# Updating An Entity
+result = command.call(
+  attributes: {
+    'title'  => 'Gideon the Ninth',
+    'author' => 'Tamsyn Muir',
+    'series' => 'The Locked Tomb'
+  }
+)
+result.value
+#=> a Book with id 1, title "Gideon the Ninth", author "Tamsyn Muir", and series
+#   "The Locked Tomb"
+
+books_collection.find_matching.call do
+  {
+    'title'  => 'Gideon the Ninth',
+    'author' => 'Tamsyn Muir'
+  }
+end.value.first
+#=> a Book with id 1, title "Gideon the Ninth", author "Tamsyn Muir", and series
+#   "The Locked Tomb"
+```
+
+If there are two or more entities in the collection matching the attributes or query, the `Upsert` command returns a failing result with a `Cuprum::Collections::Errors::NotUnique` error.
+
+If the contract does not match the entity, the `Upsert` command will return a failing result with a `ValidationFailed` error.
+
+If the collection does not specify a default contract and no :contract keyword is provided, the `Upsert` command will return a failing result with a `MissingDefaultContract` error.

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

@@ -17,6 +17,8 @@ module Cuprum::Collections::Basic
     #   Defaults to :id.
     # @param primary_key_type [Class, Stannum::Constraint] The type of the
     #   primary key attribute. Defaults to Integer.
+    # @param qualified_name [String] The qualified name of the collection, which
+    #   should be unique. Defaults to the collection name.
     # @param options [Hash<Symbol>] Additional options for the command.
     def initialize( # rubocop:disable Metrics/ParameterLists
       collection_name:,
@@ -25,6 +27,7 @@ module Cuprum::Collections::Basic
       member_name:      nil,
       primary_key_name: :id,
       primary_key_type: Integer,
+      qualified_name:   nil,
       **options
     )
       super()
@@ -37,6 +40,7 @@ module Cuprum::Collections::Basic
       @options          = options
       @primary_key_name = primary_key_name
       @primary_key_type = primary_key_type
+      @qualified_name   = qualified_name || @collection_name
     end
 
     # @return [String] the name of the collection.
@@ -62,6 +66,9 @@ module Cuprum::Collections::Basic
     #   attribute.
     attr_reader :primary_key_type
 
+    # @return [String] the qualified name of the collection.
+    attr_reader :qualified_name
+
     command_class :assign_one do
       Cuprum::Collections::Basic::Commands::AssignOne
         .subclass(**command_options)
@@ -107,6 +114,12 @@ module Cuprum::Collections::Basic
         .subclass(**command_options)
     end
 
+    # @return [Integer] the count of items in the collection.
+    def count
+      query.count
+    end
+    alias size count
+
     # A new Query instance, used for querying against the collection data.
     #
     # @return [Cuprum::Collections::Basic::Query] the query.

data/lib/cuprum/collections/basic/commands/destroy_one.rb

@@ -28,9 +28,10 @@ module Cuprum::Collections::Basic::Commands
       return if index
 
       error = Cuprum::Collections::Errors::NotFound.new(
-        collection_name:    collection_name,
-        primary_key_name:   primary_key_name,
-        primary_key_values: [primary_key]
+        attribute_name:  primary_key_name,
+        attribute_value: primary_key,
+        collection_name: collection_name,
+        primary_key:     true
       )
       Cuprum::Result.new(error: error)
     end

data/lib/cuprum/collections/basic/commands/find_many.rb

@@ -47,7 +47,7 @@ module Cuprum::Collections::Basic::Commands
 
     def items_with_primary_keys(items:)
       # :nocov:
-      items.map { |item| [item[primary_key_name.to_s], item] }.to_h
+      items.to_h { |item| [item[primary_key_name.to_s], item] }
       # :nocov:
     end
 

data/lib/cuprum/collections/basic/commands/insert_one.rb

@@ -32,9 +32,10 @@ module Cuprum::Collections::Basic::Commands
       return if index.nil?
 
       error = Cuprum::Collections::Errors::AlreadyExists.new(
-        collection_name:    collection_name,
-        primary_key_name:   primary_key_name,
-        primary_key_values: value
+        attribute_name:  primary_key_name,
+        attribute_value: value,
+        collection_name: collection_name,
+        primary_key:     true
       )
       failure(error)
     end

data/lib/cuprum/collections/basic/commands/update_one.rb

@@ -32,9 +32,10 @@ module Cuprum::Collections::Basic::Commands
       return index unless index.nil?
 
       error = Cuprum::Collections::Errors::NotFound.new(
-        collection_name:    collection_name,
-        primary_key_name:   primary_key_name,
-        primary_key_values: entity[primary_key_name.to_s]
+        attribute_name:  primary_key_name,
+        attribute_value: entity[primary_key_name.to_s],
+        collection_name: collection_name,
+        primary_key:     true
       )
       failure(error)
     end

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

@@ -151,9 +151,9 @@ module Cuprum::Collections::Basic
     def filtered_data
       @filtered_data ||=
         data
-          .yield_self { |ary| apply_filters(ary) }
-          .yield_self { |ary| apply_order(ary) }
-          .yield_self { |ary| apply_limit_offset(ary) }
+          .then { |ary| apply_filters(ary) }
+          .then { |ary| apply_order(ary) }
+          .then { |ary| apply_limit_offset(ary) }
           .map(&:dup)
     end
   end

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