sbf-dm-core 1.3.0.beta

data/README.md

@@ -0,0 +1,269 @@
+Why DataMapper?
+===============
+
+Open Development
+----------------
+
+DataMapper sports a very accessible code-base and a welcoming community.
+Outside contributions and feedback are welcome and encouraged, especially
+constructive criticism. Make your voice heard! [Submit an issue](https://github.com/firespring/dm-core/issues),
+speak up on our [mailing-list](http://groups.google.com/group/datamapper/),
+chat with us on [irc](irc://irc.freenode.net/#datamapper), write a spec, get it
+reviewed, ask for commit rights. It's as easy as that to become a contributor.
+
+Identity Map
+------------
+
+One row in the data-store should equal one object reference. Pretty simple idea.
+Pretty profound impact. If you run the following code in ActiveRecord you'll
+see all `false` results. Do the same in DataMapper and it's
+`true` all the way down.
+
+``` ruby
+  repository do
+    @parent = Tree.first(:name => 'bob')
+
+    @parent.children.each do |child|
+      puts @parent.equal?(child.parent)  # => true
+    end
+  end
+```
+
+This makes DataMapper faster and allocate less resources to get things done.
+
+Dirty Tracking
+--------------
+
+When you save a model back to your data-store, DataMapper will only write
+the fields that actually changed. So it plays well with others. You can
+use it in an Integration data-store without worrying that your application will
+be a bad actor causing trouble for all of your other processes.
+
+Eager Loading
+-------------
+
+Ready for something amazing? The following example executes only two queries
+regardless of how many rows the inner and outer queries return.
+
+``` ruby
+  repository do
+    Zoo.all.each { |zoo| zoo.exhibits.to_a }
+  end
+```
+
+Pretty impressive huh? The idea is that you aren't going to load a set of
+objects and use only an association in just one of them. This should hold up
+pretty well against a 99% rule. When you don't want it to work like this, just
+load the item you want in it's own set. So the DataMapper thinks ahead. We
+like to call it "performant by default". This feature single-handedly wipes
+out the "N+1 Query Problem". No need to specify an `:include` option in
+your finders.
+
+Laziness Can Be A Virtue
+------------------------
+
+Text fields are expensive in data-stores. They're generally stored in a
+different place than the rest of your data. So instead of a fast sequential
+read from your hard-drive, your data-store server has to hop around all over the
+place to get what it needs. Since ActiveRecord returns everything by default,
+adding a text field to a table slows everything down drastically, across the
+board.
+
+Not so with the DataMapper. Text fields are lazily loaded, meaning they
+only load when you need them. If you want more control you can enable or
+disable this feature for any field (not just text-fields) by passing a
+`:lazy` option to your field mapping with a value of `true` or
+`false`.
+
+``` ruby
+  class Animal
+    include DataMapper::Resource
+
+    property :name,        String
+    property :description, Text, :lazy => false
+  end
+```
+
+Plus, lazy-loading of Text fields happens automatically and intelligently when
+working with associations.  The following only issues 2 queries to load up all
+of the notes fields on each animal:
+
+``` ruby
+  repository do
+    Animal.all.each { |animal| animal.description.to_a }
+  end
+```
+
+Did you notice the `#to_a` call in the above example?  That
+was necessary because even DataMapper collections are lazy.  If you don't
+iterate over them, or in this case ask them to become Arrays, they won't
+execute until you need them.  We needed to call `#to_a` to force
+the lazy load because without it, the above example would have only
+executed one query.  This extra bit of laziness can come in very handy,
+for example:
+
+``` ruby
+  animals     = Animal.all
+  description = 'foo'
+
+  animals.each do |animal|
+    animal.update(:description => description)
+  end
+```
+
+In the above example, the Animals won't be retrieved until you actually
+need them.  This comes in handy in cases where you initialize the
+collection before you know if you need it, like in a web app controller.
+
+Collection Chaining
+-------------------
+
+DataMapper's lazy collections are also handy because you can get the
+same effect as named scopes, without any special syntax, eg:
+
+``` ruby
+  class Animal
+    # ... setup ...
+
+    def self.mammals
+      all(:mammal => true)
+    end
+
+    def self.zoo(zoo)
+      all(:zoo => zoo)
+    end
+  end
+
+  zoo = Zoo.first(:name => 'Greater Vancouver Zoo')
+
+  Animal.mammals.zoo(zoo).to_a  # => executes one query
+```
+
+In the above example, we ask the Animal model for all the mammals,
+and then all the animals in a specific zoo, and DataMapper will chain
+the collection queries together and execute a single query to retrieve
+the matching records.  There's no special syntax, and no custom DSLs
+to learn, it's just plain ruby all the way down.
+
+You can even use this on association collections, eg:
+
+``` ruby
+  zoo.animals.mammals.to_a  # => executes one query
+```
+
+Custom Properties
+-----------------
+
+With DataMapper it is possible to create custom properties for your models.
+Consider this example:
+
+``` ruby
+  module DataMapper
+    class Property
+      class Email < String
+        required true
+        format   /^([\w\.%\+\-]+)@([\w\-]+\.)+([\w]{2,})$/i
+      end
+    end
+  end
+
+  class User
+    include DataMapper::Resource
+
+    property :id,    Serial
+    property :email, Email
+  end
+```
+
+This way there won't be a need to repeat same property options every time you
+add an email to a model. In the example above we create an Email property which
+is just a String with additional pre-configured options: `required` and
+`format`. Please note that it is possible to override these options when
+declaring a property, like this:
+
+``` ruby
+  class Member
+    include DataMapper::Resource
+
+    property :id,    Serial
+    property :email, Email, :required => false
+  end
+```
+
+Plays Well With Others
+----------------------
+
+In ActiveRecord, all your fields are mapped, whether you want them or not.
+This slows things down. In the DataMapper you define your mappings in your
+model. So instead of an _ALTER TABLE ADD field_ in your data-store, you simply
+add a `property :name, String` to your model. DRY. No schema.rb. No
+migration files to conflict or die without reverting changes. Your model
+drives the data-store, not the other way around.
+
+Unless of course you want to map to a legacy data-store. Raise your hand if you
+like seeing a method called `col2Name` on your model just because
+that's what it's called in an old data-store you can't afford to change right
+now? In DataMapper you control the mappings:
+
+``` ruby
+  class Fruit
+    include DataMapper::Resource
+
+    storage_names[:repo] = 'frt'
+
+    property :name, String, :field => 'col2Name'
+  end
+```
+
+All Ruby, All The Time
+----------------------
+
+It's great that ActiveRecord allows you to write SQL when you need to, but
+should we have to so often?
+
+DataMapper supports issuing your own query, but it also provides more helpers
+and a unique hash-based condition syntax to cover more of the use-cases where
+issuing your own SQL would have been the only way to go. For example, any
+finder option that's non-standard is considered a condition. So you can write
+`Zoo.all(:name => 'Dallas')` and DataMapper will look for zoos with the
+name of 'Dallas'.
+
+It's just a little thing, but it's so much nicer than writing
+`Zoo.find(:all, :conditions => ['name = ?', 'Dallas'])`. What if you
+need other comparisons though? Try these:
+
+``` ruby
+  # 'gt' means greater-than. We also do 'lt'.
+  Person.all(:age.gt => 30)
+
+  # 'gte' means greather-than-or-equal-to. We also do 'lte'.
+  Person.all(:age.gte => 30)
+
+  # 'not' allows you to match all people without the name "bob"
+  Person.all(:name.not => 'bob')
+
+  # If the value of a pair is an Array, we do an IN-clause for you.
+  Person.all(:name.like => 'S%', :id => [ 1, 2, 3, 4, 5 ])
+
+  # Does a NOT IN () clause for you.
+  Person.all(:name.not => [ 'bob', 'rick', 'steve' ])
+```
+
+See? Fewer SQL fragments dirtying your Ruby code. And that's just a few of the
+nice syntax tweaks DataMapper delivers out of the box...
+
+Note on Patches/Pull Requests
+-----------------------------
+
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+Copyright
+---------
+
+Copyright (c) 2012 Dan Kubb. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,4 @@
+require 'rubygems'
+require 'rake'
+
+FileList['tasks/**/*.rake'].each { |task| import task }

data/dm-core.gemspec

@@ -0,0 +1,21 @@
+require 'English'
+require File.expand_path('lib/dm-core/version', __dir__)
+
+Gem::Specification.new do |gem|
+  gem.name        = 'sbf-dm-core'
+  gem.version     = DataMapper::VERSION.dup
+  gem.required_ruby_version = '>= 2.7.8'
+  gem.authors     = ['Dan Kubb']
+  gem.email       = %w(dan.kubb@gmail.com)
+  gem.summary = 'DataMapper core library'
+  gem.description = 'DataMapper core library where one row in the data-store should equal one object reference. ' \
+                    'Pretty simple idea. Pretty profound impact.'
+  gem.license = 'Nonstandard'
+  gem.homepage = 'https://github.com/firespring/dm-core'
+
+  gem.require_paths    = %w(lib)
+  gem.files            = `git ls-files`.split($INPUT_RECORD_SEPARATOR)
+  gem.extra_rdoc_files = %w(LICENSE README.md)
+
+  gem.add_runtime_dependency('addressable', '~> 2.3', '>= 2.3.5')
+end

data/lib/dm-core/adapters/abstract_adapter.rb

@@ -0,0 +1,233 @@
+module DataMapper
+  module Adapters
+    # Specific adapters extend this class and implement
+    # methods for creating, reading, updating and deleting records.
+    #
+    # Adapters may only implement method for reading or (less common case)
+    # writing. Read only adapter may be useful when one needs to work
+    # with legacy data that should not be changed or web services that
+    # only provide read access to data (from Wordnet and Medline to
+    # Atom and RSS syndication feeds)
+    #
+    # Note that in case of adapters to relational databases it makes
+    # sense to inherit from DataObjectsAdapter class.
+    class AbstractAdapter
+      include DataMapper::Assertions
+      extend Equalizer, DataMapper::Assertions
+
+      equalize :name, :options, :resource_naming_convention, :field_naming_convention
+
+      # @api semipublic
+      def self.descendants
+        @descendants ||= DescendantSet.new
+      end
+
+      # @api private
+      def self.inherited(descendant)
+        descendants << descendant
+        super
+      end
+
+      # Adapter name
+      #
+      # @example
+      #   adapter.name  # => :default
+      #
+      # Note that when you use
+      #
+      # DataMapper.setup(:default, 'postgres://postgres@127.0.0.1/dm_core_test')
+      #
+      # the adapter name is currently set to :default
+      #
+      # @return [Symbol]
+      #   the adapter name
+      #
+      # @api semipublic
+      attr_reader :name
+
+      # Options with which adapter was set up
+      #
+      # @example
+      #   adapter.options  # => { :adapter => 'yaml', :path => '/tmp' }
+      #
+      # @return [Hash]
+      #   adapter configuration options
+      #
+      # @api semipublic
+      attr_reader :options
+
+      # A callable object returning a naming convention for model storage
+      #
+      # @example
+      #   adapter.resource_naming_convention  # => Proc for model storage name
+      #
+      # @return [#call]
+      #   object to return the naming convention for each model
+      #
+      # @api semipublic
+      attr_accessor :resource_naming_convention
+
+      # A callable object returning a naming convention for property fields
+      #
+      # @example
+      #   adapter.field_naming_convention  # => Proc for field name
+      #
+      # @return [#call]
+      #   object to return the naming convention for each field
+      #
+      # @api semipublic
+      attr_accessor :field_naming_convention
+
+      # Persists one or many new resources
+      #
+      # @example
+      #   adapter.create(collection)  # => 1
+      #
+      # Adapters provide specific implementation of this method
+      #
+      # @param [Enumerable<Resource>] resources
+      #   The list of resources (model instances) to create
+      #
+      # @return [Integer]
+      #   The number of records that were actually saved into the data-store
+      #
+      # @api semipublic
+      def create(resources)
+        raise NotImplementedError, "#{self.class}#create not implemented"
+      end
+
+      # Reads one or many resources from a datastore
+      #
+      # @example
+      #   adapter.read(query)  # => [ { 'name' => 'Dan Kubb' } ]
+      #
+      # Adapters provide specific implementation of this method
+      #
+      # @param [Query] query
+      #   the query to match resources in the datastore
+      #
+      # @return [Enumerable<Hash>]
+      #   an array of hashes to become resources
+      #
+      # @api semipublic
+      def read(query)
+        raise NotImplementedError, "#{self.class}#read not implemented"
+      end
+
+      # Updates one or many existing resources
+      #
+      # @example
+      #   adapter.update(attributes, collection)  # => 1
+      #
+      # Adapters provide specific implementation of this method
+      #
+      # @param [Hash(Property => Object)] attributes
+      #   hash of attribute values to set, keyed by Property
+      # @param [Collection] collection
+      #   collection of records to be updated
+      #
+      # @return [Integer]
+      #   the number of records updated
+      #
+      # @api semipublic
+      def update(attributes, collection)
+        raise NotImplementedError, "#{self.class}#update not implemented"
+      end
+
+      # Deletes one or many existing resources
+      #
+      # @example
+      #   adapter.delete(collection)  # => 1
+      #
+      # Adapters provide specific implementation of this method
+      #
+      # @param [Collection] collection
+      #   collection of records to be deleted
+      #
+      # @return [Integer]
+      #   the number of records deleted
+      #
+      # @api semipublic
+      def delete(collection)
+        raise NotImplementedError, "#{self.class}#delete not implemented"
+      end
+
+      # Create a Query object or subclass.
+      #
+      # Alter this method if you'd like to return an adapter specific Query subclass.
+      #
+      # @param [Repository] repository
+      #   the Repository to retrieve results from
+      # @param [Model] model
+      #   the Model to retrieve results from
+      # @param [Hash] options
+      #   the conditions and scope
+      #
+      # @return [Query]
+      #
+      # @api semipublic
+      #--
+      # TODO: DataObjects::Connection.create_command style magic (Adapter)::Query?
+      def new_query(repository, model, options = {})
+        Query.new(repository, model, options)
+      end
+
+      # Set the serial value of the Resource
+      #
+      # @param [Resource] resource
+      #   the resource to set the serial property in
+      # @param [Integer] next_id
+      #   the identifier to set in the resource
+      #
+      # @return [undefined]
+      #
+      # @api semipublic
+      protected def initialize_serial(resource, next_id)
+        return unless (serial = resource.model.serial(name))
+        return unless serial.get!(resource).nil?
+
+        serial.set!(resource, next_id)
+
+        # TODO: replace above with this, once
+        # specs can handle random, non-sequential ids
+        # serial.set!(resource, rand(2**32))
+      end
+
+      # Translate the attributes into a Hash with the field as the key
+      #
+      # @example
+      #   attributes = { User.properties[:name] => 'Dan Kubb' }
+      #   adapter.attributes_as_fields(attributes)  # => { 'name' => 'Dan Kubb' }
+      #
+      # @param [Hash] attributes
+      #   the attributes with the Property as the key
+      #
+      # @return [Hash]
+      #   the attributes with the Property#field as the key
+      #
+      # @api semipublic
+      protected def attributes_as_fields(attributes)
+        attributes.to_h { |property, value| [property.field, property.dump(value)] }
+      end
+
+      # Initialize an AbstractAdapter instance
+      #
+      # @param [Symbol] name
+      #   the adapter repository name
+      # @param [Hash] options
+      #   the adapter configuration options
+      #
+      # @return [undefined]
+      #
+      # @api semipublic
+      private def initialize(name, options)
+        @name                       = name
+        @options                    = options.dup.freeze
+        @resource_naming_convention = NamingConventions::Resource::UnderscoredAndPluralized
+        @field_naming_convention    = NamingConventions::Field::Underscored
+      end
+    end
+
+    const_added(:AbstractAdapter)
+  end
+end

data/lib/dm-core/adapters/in_memory_adapter.rb

@@ -0,0 +1,110 @@
+module DataMapper
+  module Adapters
+    # This is probably the simplest functional adapter possible. It simply
+    # stores and queries from a hash containing the model classes as keys,
+    # and an array of hashes. It is not persistent whatsoever; when the Ruby
+    # process finishes, everything that was stored it lost. However, it doesn't
+    # require any other external libraries, such as data_objects, so it is ideal
+    # for writing specs against. It also serves as an excellent example for
+    # budding adapter developers, so it is critical that it remains well documented
+    # and up to date.
+    class InMemoryAdapter < AbstractAdapter
+      # Used by DataMapper to put records into a data-store: "INSERT" in SQL-speak.
+      # It takes an array of the resources (model instances) to be saved. Resources
+      # each have a key that can be used to quickly look them up later without
+      # searching, if the adapter supports it.
+      #
+      # @param [Enumerable(Resource)] resources
+      #   The set of resources (model instances)
+      #
+      # @api semipublic
+      def create(resources)
+        records = records_for(resources.first&.model)
+
+        resources.each do |resource|
+          initialize_serial(resource, records.size.succ)
+          records << attributes_as_fields(resource.attributes(nil))
+        end
+      end
+
+      # Looks up one record or a collection of records from the data-store:
+      # "SELECT" in SQL.
+      #
+      # @param [Query] query
+      #   The query to be used to search for the resources
+      #
+      # @return [Array]
+      #   An Array of Hashes containing the key-value pairs for
+      #   each record
+      #
+      # @api semipublic
+      def read(query)
+        query.filter_records(records_for(query.model).dup)
+      end
+
+      # Used by DataMapper to update the attributes on existing records in a
+      # data-store: "UPDATE" in SQL-speak. It takes a hash of the attributes
+      # to update with, as well as a collection object that specifies which resources
+      # should be updated.
+      #
+      # @param [Hash] attributes
+      #   A set of key-value pairs of the attributes to update the resources with.
+      # @param [DataMapper::Collection] collection
+      #   The collection of resources to update.
+      #
+      # @api semipublic
+      def update(attributes, collection)
+        attributes = attributes_as_fields(attributes)
+        read(collection.query)&.each { |record| record.update(attributes) }&.size
+      end
+
+      # Destroys all the records matching the given query. "DELETE" in SQL.
+      #
+      # @param [DataMapper::Collection] collection
+      #   The collection of resources to delete.
+      #
+      # @return [Integer]
+      #   The number of records that were deleted.
+      #
+      # @api semipublic
+      def delete(collection)
+        records = records_for(collection.model)
+        records_to_delete = collection.query.filter_records(records.dup)
+        records.replace(records - records_to_delete)
+        records_to_delete&.size
+      end
+
+      # TODO: consider proper automigrate functionality
+      def reset
+        @records = {}
+      end
+
+      # Make a new instance of the adapter. The @records ivar is the 'data-store'
+      # for this adapter. It is not shared amongst multiple incarnations of this
+      # adapter, eg DataMapper.setup(:default, :adapter => :in_memory);
+      # DataMapper.setup(:alternate, :adapter => :in_memory) do not share the
+      # data-store between them.
+      #
+      # @param [String, Symbol] name
+      #   The name of the Repository using this adapter.
+      # @param [String, Hash] options
+      #   The connection uri string, or a hash of options to set up
+      #   the adapter
+      #
+      # @api semipublic
+      private def initialize(name, options = {})
+        super
+        @records = {}
+      end
+
+      # All the records we're storing. This method will look them up by model name
+      #
+      # @api private
+      private def records_for(model)
+        @records[model.storage_name(name)] ||= []
+      end
+    end
+
+    const_added(:InMemoryAdapter)
+  end
+end