Roadmap Finalize API

Over time the DM API has been subtly changing so that Resource, Collection and Model share similar properties across common methods. The consistency in the DM API is one of it’s strongest attributes, and we would like to finish polishing this before a DataMapper 1.0 launch.

It’s become clear that aside from Collection having some behaviour of Array and Enumerable objects, it can otherwise be thought of as identical to a Model. Therefore the Model and Collection API should be unified as closely as possible. The same finders, and CRUD operations should be possible through both objects. Specs should be shared between all methods in Model and Collection. Some of the methods should be moved to shared modules, and then included into Model and Collection.

For example, there is Collection#update and Resource#update, both of which accept a Hash corresponding to the property names and values, and then persist this state in the datastore. If validations are used, then each Resource will only be persisted if the change is valid. There is currently no Model#update method, but there should be for consistency even though I don’t expect it to be used very often. The specs for the behaviour of #update that is consistent between the objects should be pushed into shared specs.

Each of the #update methods also has a corresponding #update! method that performs the same operation, except that instead of testing the validity of each Resource (and initializing the Resource beforehand), it performs the change directly in the datastore. If the datastore provides a bulk update operation it will be used to efficiently modify one or more resources.

At some point (probably after DM 1.0 is released) Model and Collection may even become a single type of object, possibly a Relation (in the Relational Algebra sense) or something that has-a Relation. Since 1:m and m:m associations are also based on Collection, they would also be included in this refactoring.

This gist shows an overview of the final Model, Collection and Resource APIs. We will need to ensure there are specs for each of these methods, and that any shared behaviour is in shared specs. Each method can probably be dealt with in isolation, so someone interested in working on this could probably tackle #fetch, then a few days later #copy, and so on. I imagine several people could be working on this task at the same time provided it was clear which methods you are working on.