reorm 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c4d147f8ec8ab156ae124379903853b37a6aec29
+  data.tar.gz: c53da10347253a776ecfea2cee5d56d9f49e1622
+SHA512:
+  metadata.gz: 356d4b82f8285da450df48392baa417df7760f81c7ebf866eb74257ab0e2352bcfd0c7b2f0e5682f925217e528b2a2e29c3b97c89f1a2376b2247e571cd7ddbd
+  data.tar.gz: 0e412ac34981e3f3551538e38263e6b88a5be80333d06e5dfa5f5f6d323d0cc9980fb5b22137a6abce7cd8e15f35e9869c9998ac593451b487c867a0e4fdcf4b

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in reorm.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Peter Wood
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,219 @@
+# Reorm
+
+A (possibly naive) ORM for use with the RethinkDB driver for Ruby. The library
+is heavily influenced by the implementations of the active record pattern from
+the Sequel and ActiveRecord libraries. I'm not 100% sure that this is a good
+match for a document oriented store such as RethinkDB but here it is anyway.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'reorm'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install reorm
+
+## Usage
+
+First things first, the library needs to be configured to connect to your
+RethinkDB instance. The simplest way to do this is create a file called
+database.yml in the current working directory. Place content like the following
+into this file...
+
+    defaults: &defaults
+      host: localhost
+      port: 28015
+
+    development:
+      <<: *defaults
+      db: reorm_dev
+
+    test:
+      <<: *defaults
+      db: reorm_test
+
+This will be picked up by the library and used to create a connection based on
+it current environment (this defaults to development but if you set either the
+RAILS_ENV or RACK_ENV environment variables that will be used instead). The
+example above connects to the same RethinkDB instance, on localhost at port
+28015, and then defaults the database it will use based on the enviornment
+setting. Note the configuration options are more complicated and flexible than
+using this approach but more on that later.
+
+Next, declare a model class like so...
+
+    class MyModel < Reorm::Model
+    end
+
+This small amount of code declares a class that will expect to save its data
+elements into a table called my_models (it will create this table if it does not
+already exist) and with an assumption that it uses a primary key called id. You
+can change the table name used like so...
+
+    class MyModel < Reorm::Model
+      table_name "other_records"
+    end
+
+You could now create an instance of your model and save it to the database like
+so...
+
+    model = MyModel.create(one: 1, two: 2, three: {four: 4})
+
+Once a model has been created like this it will have all of the top level fields
+specified as parameters available as properties from the model object generated.
+So, for example, you could access some of the value from the object created
+above in code as follows...
+
+    model.one   # = 1
+    model.two   # = 2
+    model.three # = {four: 4}
+
+When an object is created it will automatically have its primary key filled out
+by RethinkDB. By default models use a primary key called id but you can change
+this by adding code like the following to you class declaration...
+
+    primary_key :my_key
+
+This will change the primary key used by the class to the field specified to
+the call to ```primary_key```. When a primary key value has been generated by
+RethinkDB its also available as a property from the object. Given the create
+example above the models primary key can be accessed like any other property of
+the object...
+
+    model.id # RethinkDB generated primary key value.
+
+To retrieve models back from the database you call either call the ```#all()```
+method or use the ```#filter()``` method that is available on all model classes.
+For example, if you had a model called User, you could use this code to iterate
+across all user records...
+
+    User.all.each do |user|
+      # Do some stuff here.
+      ...
+    end
+
+Or you could search for a user with a particular email address using code like
+the following...
+
+    user = User.filter({email: "user@email.com"}).first
+
+If I wanted all users whose email address had a particular domain then I would
+use code like the following...
+
+    users = User.filter {|record| record["email"].match("@gmail.com$")}
+    users.each do |user|
+      # Do some stuff here.
+      ...
+    end
+
+Note that in the predicate passed to the filter method the value passed to the
+block is the raw record and not an instance of the model class. This means that
+you have to dereference field values as you would from a Hash. When using the
+output of the filter however you will receive model class instances and can
+use those as normal.
+
+The filter code is based on the RethinkDB filter functionality so consult the
+documentation for more information.
+
+### Validations
+
+Model classes can provide functionality that allows them to be validated to
+ensure that their data settings are consistent. To do this implement a method on
+your class called ```#validate()```. The first thing to do in this method is to
+make a call to the parent class implementation of this method via a call to
+```super``` - this is important so don't forget to do it! After that you can
+perform tests on the objects settings and add errors to the model where you
+discover discrepancies. For example...
+
+    def validate
+      super
+      if [nil, ""].include?(email)
+        errors.add(:email, "cannot be blank.")
+      end
+    end
+
+The library provides a number of helper method to shortcut some common
+validations such as the following...
+
+    def validate
+      super
+      validate_presence_of :email
+    end
+
+Would do the same thing as the first version of the ```validate()``` method
+shown above. Some other examples include...
+
+    def validate
+      super
+      validate_length_of :field1, minimum: 5, maximum: 20
+      validate_inclusion_of :field2, "One", "Of", "These", "Values"
+      validate_exclusion_of :field3 "Not", "One", "Of", "These"
+    end
+
+If you call te ```valid?()``` method on a model then the model object will be
+validated and this method will return true if no errors were set and false if at
+least one error was set. You can view the errors for a model by accessing its
+```errors``` property which returns an instance of the
+```Reorm::Reorm::PropertyErrors``` class.
+
+Note that a object is automatically validated any time it is saved and that the
+save request will fail if the object fails validation and an exception will be
+raised. You can turn validation off for a save by passing false as a parameter
+to the save call.
+
+### Event Callbacks
+
+The library supports a number of event related callbacks that will be invoked
+when a specific event occurs. You can add an event related callback to a model
+by declaring it within the model class like so...
+
+    before_save :method_name
+
+In this case the library will attempt to invoked a method called ```method_name```
+on the model object after validation but before the object is actually written
+to RethinkDB. Note the method has to actually exist on the model for this to
+work. The following callbacks, in the order in which they occur, are available -
+before_validate, after_validate, before_create, before_update, before_save,
+after_save, after_update and after_create.
+
+### Unit Tests
+
+To run the unit tests you'll need a locally running instance of RethinkDB (none
+of that nonsense mocking out DB writes rubbish here!) and then you can run the
+available unit tests using the ```rspec``` command.
+
+### Configuration
+
+The library, on load up, looks for a file containing the RethinkDB configuration
+details. It will settle upon the first file that it finds called database.yml,
+rethinkdb.yml or application.yml (note a .json extension is also acceptable).
+This file will be expected to contain a Hash in the appropriate format. Within
+this Hash it will first look for a an environment base entry (i.e. a key of
+'development', 'production' or 'test'). If it finds no such key it will assume
+that the entire Hash is the configuration, otherwise it will extract the entry
+under the given key and use that as configuration.
+
+Next it takes the output from the previous section and looks for an entry keyed
+under 'rethinkdb'. Again, if it does not find it, it will assume the entire
+entry is its configuration, otherwise it will focus down on the keyed entry
+once more. The reasoning here is to allow you to have a separate standalone
+database configuration file or to allow your database configuration values to
+be part of a larger configuration file. The output from this process is expected
+to be the parmaeters that will allow the library to connect to a RethinkDB
+server.
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/reorm/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/config/database.yml

@@ -0,0 +1,11 @@
+defaults: &defaults
+  host: localhost
+  port: 28015
+
+development:
+  <<: *defaults
+  db: reorm_dev
+
+test:
+  <<: *defaults
+  db: reorm_test

data/lib/reorm/configuration.rb

@@ -0,0 +1,12 @@
+#! /usr/bin/env ruby
+# Copyright (c), 2015 Peter Wood
+# See the license.txt for details of the licensing of the code in this file.
+
+module Reorm
+	class Configuration < Configurative::Settings
+		files *(Dir.glob(File.join(Dir.getwd, "**", "database.{yml,yaml,json}")) +
+		        Dir.glob(File.join(Dir.getwd, "**", "rethinkdb.{yml,yaml,json}")) +
+				 	  Dir.glob(File.join(Dir.getwd, "**", "application.{yml,yaml,json}")))
+		#section "rethinkdb"
+	end
+end

data/lib/reorm/cursor.rb

@@ -0,0 +1,162 @@
+#! /usr/bin/env ruby
+# Copyright (c), 2015 Peter Wood
+# See the license.txt for details of the licensing of the code in this file.
+
+module Reorm
+  class Cursor
+    def initialize(model_class, query, order_by=nil)
+      @model_class = model_class
+      @query       = query
+      @cursor      = nil
+      @offset      = 0
+      @total       = 0
+      @order_by    = order_by
+    end
+    attr_reader :model_class
+
+    def close
+      @cursor.close if @cursor && !@cursor.kind_of?(Array)
+      @cursor = nil
+      @offset = @total = 0
+      self
+    end
+    alias :reset :close
+
+    def filter(predicate)
+      Cursor.new(model_class, @query.filter(predicate), @order_by)
+    end
+
+    def count
+      Reorm.connection do |connection|
+        @query.count.run(connection)
+      end
+    end
+
+    def exhausted?
+      open? && @offset == @total
+    end
+
+    def find
+      model = nil
+      each do |record|
+        found = yield(record)
+        if found
+          model = record
+          break
+        end
+      end
+      model
+    end
+    alias :detect :find
+
+    def next
+      open if !open?
+      if exhausted?
+        raise Error, "There are no more matching records."
+      end
+      data    = @order_by.nil? ? @cursor.next : @cursor[@offset]
+      @offset += 1
+      model_class.new(data)
+    end
+
+    def each(&block)
+      @order_by.nil? ? each_without_order_by(&block) : each_with_order_by(&block)
+    end
+
+    def inject(token=nil)
+      each do |record|
+        yield token, record
+      end
+      token
+    end
+
+    def nth(offset)
+      model = nil
+      if offset >= 0 && offset < count
+        Reorm.connection do |connection|
+          model = model_class.new(@query.nth(offset).run(connection))
+        end
+      end
+      model
+    end
+
+    def first
+      nth(0)
+    end
+
+    def last
+      nth(count - 1)
+    end
+
+    def to_a
+      inject([]) {|list, record| list << record}
+    end
+
+    def limit(size)
+      Cursor.new(model_class, @query.limit(size), @order_by)
+    end
+
+    def offset(index)
+      Cursor.new(model_class, @query.skip(quantity), @order_by)
+    end
+    alias :skip :offset
+
+    def slice(start_at, end_at=nil, left_bound='closed', right_bound="open")
+      if end_at
+        Cursor.new(model_class, @query.slice(start_at, end_at, left_bound, right_bound), @order_by)
+      else
+        Cursor.new(model_class, @query.slice(start_at), @order_by)
+      end
+    end
+
+    def order_by(*arguments)
+      Cursor.new(model_class, @query, arguments)
+    end
+
+  private
+
+    def open
+      Reorm.connection do |connection|
+        array_based = false
+        if @order_by && @order_by.size > 0
+          clause = @order_by.find {|entry| entry.kind_of?(Hash)}
+          array_based = clause.nil? || clause.keys != [:index]
+        end
+
+        @offset = 0
+        if !array_based
+          @total  = @query.count.run(connection)
+          @cursor = @query.run(connection)
+        else
+          @cursor = @query.order_by(*@order_by).run(connection)
+          @total  = @cursor.size
+        end
+      end
+    end
+
+    def open?
+      !@cursor.nil?
+    end
+
+    def each_with_order_by
+      Reorm.connection do |connection|
+        @query.order_by(*@order_by).run(connection).each do |record|
+          yield model_class.new(record)
+        end
+      end
+    end
+
+    def each_without_order_by
+      Reorm.connection do |connection|
+        cursor = @query.run(connection)
+        begin
+          cursor.each do |record|
+            yield model_class.new(record)
+          end
+        ensure
+          cursor.close
+        end
+      end
+    end
+  end
+end

data/lib/reorm/exceptions.rb

@@ -0,0 +1,13 @@
+#! /usr/bin/env ruby
+# Copyright (c), 2015 Peter Wood
+# See the license.txt for details of the licensing of the code in this file.
+
+module Reorm
+	class Error < StandardError
+		def initialize(message, cause=nil)
+			super(message)
+			@cause = cause
+		end
+		attr_reader :cause
+	end
+end

data/lib/reorm/field_path.rb

@@ -0,0 +1,53 @@
+#! /usr/bin/env ruby
+# Copyright (c), 2015 Peter Wood
+# See the license.txt for details of the licensing of the code in this file.
+
+module Reorm
+  class FieldPath
+    def initialize(*path)
+      @path = [].concat(path)
+    end
+
+    def name
+      @path.last
+    end
+
+    def value(document)
+      locate(document).first
+    end
+
+    def value!(document)
+      result = locate(document)
+      raise Error, "Unable to locate the #{name} (full path: #{self}) field for an instance of the #{document.class.name} class." if !result[1]
+      result[0]
+    end
+
+    def exists?(document)
+      locate(document)[1]
+    end
+
+    def to_s
+      @path.join(" -> ")
+    end
+
+  private
+
+    def locate(document)
+      result = [nil, false]
+      value = document
+      @path.each_with_index do |field, index|
+        if !value || !value.respond_to?(:include?) || !value.include?(field)
+          value = nil
+          break
+        else
+          if index == @path.length - 1
+            result = [value[field], true]
+          else
+            value = value[field]
+          end
+        end
+      end
+      result
+    end
+  end
+end

data/lib/reorm/model.rb

@@ -0,0 +1,132 @@
+#! /usr/bin/env ruby
+# Copyright (c), 2015 Peter Wood
+# See the license.txt for details of the licensing of the code in this file.
+
+module Reorm
+  class Model
+    extend EventHandler
+    extend EventSource
+    extend TableBacked
+    include EventSource
+    include TableBacked
+    include Validations
+
+    @@class_tables = {}
+
+    def initialize(properties={})
+      @properties = {}
+      properties.each do |key, value|
+        @properties[key.to_sym] = value
+      end
+      @errors     = PropertyErrors.new
+    end
+    attr_reader :errors
+
+    def valid?
+      validate
+      @errors.clear?
+    end
+
+    def validate
+      fire_events(events: [:before_validate])
+      @errors.reset
+      fire_events(events: [:after_validate])
+      self
+    end
+
+    def save(validated=true)
+      if validated && !valid?
+        raise Error, "Validation error encountered saving an instance of the #{self.class.name} class."
+      end
+
+      action_type = (@properties[primary_key] ? :update : :create)
+      if action_type == :create
+        fire_events(events: [:before_create, :before_save])
+      else
+        fire_events(events: [:before_update, :before_save])
+      end
+
+      Reorm.connection do |connection|
+        ensure_table_exists(connection)
+        if !@properties.include?(primary_key)
+          result = r.table(table_name).insert(self.to_h, return_changes: true).run(connection)
+          if !result["inserted"] || result["inserted"] != 1
+            raise Error, "Creation of database record for an instance of the #{self.class.name} class failed."
+          end
+          @properties[primary_key] = result["generated_keys"].first
+        else
+          result = r.table(table_name).update(self.to_h).run(connection)
+          if !result["replaced"] || !result["replaced"] == 1
+            raise Error, "Update of database record for an instance of the #{self.class.name} class failed."
+          end
+        end
+      end
+
+      if action_type == :create
+        fire_events(events: [:after_save, :after_create])
+      else
+        fire_events(events: [:after_save, :after_update])
+      end
+    end
+
+    def [](property_name)
+      @properties[property_name.to_sym]
+    end
+
+    def []=(property_name, value)
+      @properties[property_name.to_sym] = value
+      value
+    end
+
+    def respond_to?(method_name, include_private=false)
+      @properties.include?(property_name(method_name)) || super
+    end
+
+    def method_missing(method_name, *arguments, &block)
+      if method_name.to_s[-1,1] != "="
+        if @properties.include?(property_name(method_name))
+          @properties[method_name]
+        else
+          super
+        end
+      else
+        @properties[property_name(method_name)] = arguments.first
+      end
+    end
+
+    def to_h
+      {}.merge(@properties)
+    end
+
+    def self.create(properties={})
+      object = self.new(properties)
+      object.save
+      object
+    end
+
+    def self.all
+      Cursor.new(self, r.table(table_name))
+    end
+
+    def self.filter(predicate=nil, &block)
+      if predicate.nil?
+        Cursor.new(self, r.table(table_name).filter(&block))
+      else
+        Cursor.new(self, r.table(table_name).filter(predicate))
+      end
+    end
+
+  private
+
+    def property_name(name)
+      name.to_s[-1,1] == "=" ? name.to_s[0...-1].to_sym : name
+    end
+
+    def ensure_table_exists(connection)
+      tables = r.table_list.run(connection)
+      if !tables.include?(table_name)
+        r.table_create(table_name, primary_key: primary_key).run(connection)
+      end
+    end
+  end
+end