preserves 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f8431d69f3de10e3ee28a0e6e2c96b86afadfeee
+  data.tar.gz: 6c87236337e01dbb1c5e95a95920fc82ef8f7f18
+SHA512:
+  metadata.gz: 3e693759454aea1c88303fd6ed6b5e916991ad1491b3217ee9f1558b1c99b094c1be2eed26db95e26ab25cf82d7734829fa3292b4f531626071b1a5c5930aac7
+  data.tar.gz: 25d5b244aebae726bc06607b192c094672e5b96199501a9bb6f915d0bb21c2de5aa27d226f1efb9dbace3445f4fe78ad8ba86060ea2babecc384f80d2f87ef43

data/.gitignore

@@ -0,0 +1,23 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+vendor/bundle

data/.irbrc

@@ -0,0 +1,9 @@
+# NOTE: For this file to work, your ~/.irbrc file must contain snippet from http://www.samuelmullen.com/2010/04/irb-global-local-irbrc/.
+
+
+# Allow reloading our gem.
+def reload!
+  @gem_name = Dir["#{Dir.pwd}/*.gemspec"].first.split('/').last.sub('.gemspec', '')
+  files = $LOADED_FEATURES.select { |feat| feat =~ %r[/#{@gem_name}/] }
+  files.each { |file| load file }
+end

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--warnings
+--require spec_helper

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Gem dependencies are specified in `preserves.gemspec`.
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 BoochTek, LLC
+
+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,178 @@
+Preserves
+=========
+
+Preserves is a minimalist ORM (object-relational mapper) for Ruby, using the
+Repository and Data Mapper patterns.
+
+We're trying to answer these questions:
+
+* How simple can we make an ORM that is still useful?
+* Developers have to know SQL anyway, so why try to hide the SQL from them?
+    * Is the complexity of a typical ORM really better than the complexity of SQL?
+* ORMs are a leaky abstraction. What if we made it so leaky that it doesn't matter?
+
+This ORM is based on a few strong opinions:
+
+* The Data Mapper pattern is generally better than the Active Record pattern.
+    * Unless you're just writing a CRUD front-end, with little interesting behavior.
+* Declaring attributes in the domain model is better than hiding them elsewhere.
+    * Declaring relationships in one place and attributes in another is true madness.
+* NoSQL as a main data store is usually misguided.
+    * PostgreSQL can do just about anything you need, using SQL.
+* Projects are unlikely to need to abstract SQL to allow them to use different RDBMSes.
+    * Developer workstations are fast enough to run "full" RDBMSes.
+    * If you're not using "interesting" features, then you're probably using "standard" SQL.
+
+The Data Mapper pattern provides several advantages:
+
+* Domain objects don't have to know anything about the database or its schema.
+    * Instead, the mapper knows about the domain objects and the database.
+        * DB schema can change without having to change to domain objects; only the mapper changes.
+* The domain objects are self-contained.
+    * Don't have to look elsewhere to understand everything a class contains.
+* Better meets the Single Responsibility Principle (SRP).
+    * Domain model classes handle business logic.
+    * Repository classes handle persistence.
+    * Mapper classes handle mapping database fields to object attributes.
+
+It's been pointed out that Preserves might not in fact even be an ORM, because it doesn't have a complete model of the relations between objects.
+
+
+Installation
+------------
+
+Add this line to your application's Gemfile:
+
+    gem 'preserves'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install preserves
+
+
+Example Usage
+-------------
+
+First, create your domain model class. You can use a [Struct], an
+[OpenStruct], a [Virtus] model, or a plain old Ruby object (PORO) class.
+We'll use a Struct in the examples, so we can initialize the fields easily.
+
+~~~ ruby
+User = Struct.new(:id, :name, :age) do
+end
+~~~
+
+Next, configure the Preserves data store.
+
+~~~ ruby
+Preserves.data_store = Preserves::PostgreSQL("my_database")
+~~~
+
+Then create a repository linked to the domain model class.
+By default, all attributes will be assumed to be Strings.
+For other attribute types, you'll need to supply the mapping.
+(We'll have some default mappings determined from the DB or model later.)
+Your repository should then define methods to access model objects
+in the database. (These will mostly be like ActiveRecord scopes.)
+
+~~~ ruby
+UserRepository = Preserves.repository(model: User) do
+  mapping do
+    map id: 'username'  # The database field named 'username' corresponds to the 'id' attribute in the model.
+    map :age, Integer   # The 'age' field should be mapped to an Integer in the model.
+  end
+
+  # We'll likely provide `insert`, but this gives an idea of how minimal we'll be to start off.
+  def insert(user)
+    result = query("INSERT INTO 'users' (username, name, age) VALUES ($1, $2, $3)",
+                   user.id, user.name, user.age)
+    raise "Could not insert User #{user.id} into database" unless result.size == 1
+  end
+
+  def older_than(age)
+    select("SELECT *, username AS id FROM 'users' WHERE age > $1 ORDER BY $2", age, :name)
+  end
+
+  def with_id(id)
+    select("SELECT *, username AS id FROM 'users' WHERE username = $1", id)
+  end
+end
+~~~
+
+Now we can create model objects and use the repository to save them to and
+retrieve them from the database:
+
+~~~ ruby
+craig = User.new("booch", "Craig", 42)
+UserRepository.insert(craig)
+users_over_40 = UserRepository.older_than(40)   # Returns an Enumerable set of User objects.
+beth = UserRepository.with_id("beth").one       # Returns a single User object or nil.
+~~~
+
+
+API Summary
+-----------
+
+NOTE: This project is in very early exploratory stages. The API **will** change.
+
+
+### Repository ###
+
+Most of the API you'll use will be in the your repository object.
+The mixin provides the following methods:
+
+~~~ ruby
+fetch(id)             # Fetch a single domain model object by its primary key.
+[id]                  # Fetch a single domain model object by its primary key.
+query(sql_string)     # Runs SQL and returns a Preserves::SQL::ResultSet.
+select(sql_string)    # Runs SQL and returns a Preserves::Selection.
+select(sql_string, param1, param2)  # Include bind params for the SQL query.
+select(sql_string, association_name: sql_result)  # Include associations.
+~~~
+
+
+### Preserves::SQL::ResultSet ###
+
+~~~ ruby
+result.size     # Number of rows that were affected by the SQL query.
+~~~
+
+
+### Preserves::Selection ###
+
+A Selection is an Enumerable, representing the results of a SELECT query,
+mapped to domain model objects.
+Most of your interactions with Selections will be through the Enumerable interface.
+
+~~~ ruby
+selection.each      # Iterates through the resulting domain objects.
+selection.first     # Returns the first result. Returns nil if there are no results.
+selection.first!    # Returns the first result. Raises an exception if there are no results.
+selection.last      # Returns the last result. Returns nil if there are no results.
+selection.last!     # Returns the last result. Raises an exception if there are no results.
+selection.only      # Returns the only result. Returns nil if there are no results. Raises an exception if there's more than 1 result. (Aliased as `one`.)
+selection.only!     # Returns the only result. Raises an exception if there's not exactly 1 result. (Aliased as `one!`.)
+~~~
+
+
+Contributing
+------------
+
+1. Fork the [project repo].
+2. Create your feature branch (`git checkout -b my-new-feature`).
+3. Make sure tests pass (`rspec` or `rake spec`).
+4. Commit your changes (`git commit -am 'Add some feature'`).
+5. Push to the branch (`git push origin my-new-feature`).
+6. Create a new [pull request].
+
+
+[Struct]: http://ruby-doc.org/core-2.2.0/Struct.html
+[OpenStruct]: http://ruby-doc.org/stdlib-2.2.0/libdoc/ostruct/rdoc/OpenStruct.html
+[Virtus]: https://github.com/solnic/virtus#readme
+
+[project repo]: https://github.com/boochtek/ruby_preserves/fork
+[pull request]: https://github.com/boochtek/ruby_preserves/pulls

data/Rakefile

@@ -0,0 +1,2 @@
+require 'rubygems/tasks'
+Gem::Tasks.new

data/SETUP.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+
+case "$(uname)" in
+Darwin)
+	brew install postgresql
+	ln -sfv /usr/local/opt/postgresql/*.plist ~/Library/LaunchAgents
+	launchctl load ~/Library/LaunchAgents/homebrew.mxcl.postgresql.plist
+	bundle --path vendor/bundle
+	createdb 'preserves_test'
+	;;
+*)
+	echo "Don't know how to install on this system. Please submit a pull request."
+	exit
+	;;
+esac

data/TODO.md

@@ -0,0 +1,122 @@
+TODO
+====
+
+
+Presentation
+------------
+
+* Create the short URL. (NO UNDERSCORES on TinyURL)
+    * http://craigbuchek.com/ruby-preserves-rubyconf
+    * http://tinyurl.com/ruby-preserves-rubyconf
+    * https://rawgit.com/booch/presentations/Ruby_Preserves-RubyConf-2015-11-15/Ruby_Preserves/slides.html
+
+
+ASAP
+----
+
+* README: Document has_many and belongs_to.
+    * Advise to avoid belongs_to mappings, if possible.
+        * Especially don't want circular dependencies.
+* README: Show an example of pagination.
+* README: Show how to use a different repository for tests, if necessary.
+    * Since we require SQL, we can't really do in-memory.
+        * So the repository would not be a Preserves repository.
+* Saving.
+    * Not sure if we should just have subclasses use query().
+        * I'm starting to lean that way.
+        * We probably have all the info we need to build the INSERT programmatically.
+            * But that would violate our "just use SQL everywhere" mantra.
+    * insert / update / save / delete
+* Preserves.repository() should return a module to mix in, and not take a block.
+    * And should not be singletons.
+        * Might use method_missing on class to allow usage as if it's a singleton.
+    * Use the Module Factory pattern.
+
+
+Soonish
+-------
+
+* Convenience methods.
+    * create_table
+    * scope
+* More coercions.
+    * Boolean
+    * Date
+    * Rename to serialize/deserialize.
+    * Move serializers to their own class(es).
+        * Or should we use solnic/coercible gem?
+    * Allow a way to specify more type mappings/serializers.
+    	 * Registration?
+* Get default mappings from DB schema.
+    * INTEGER
+    * DATE
+    * TIME
+* Prepared statements.
+    * Can we just prepare every SQL query we run?
+        * Have a cache mapping the SQL query string to the prepared statement.
+            * Would obviously want to make this a LRU cache eventually.
+* Ensure we can use PostgreSQL arrays.
+* Be consistent between strings and symbols.
+* Can we initialize the domain model objects, instead of using setters?
+    * Would initialize with a Hash of attributes and values.
+    * Might allow both variants, to work with different kinds of classes.
+    * Would need a way to know if the model class supports the initializer we'd be using.
+* Allow strings in place of class names for specifying repositories.
+    * Because we'll have circular references for belongs_to/has_many pairs.
+    * Or should we not allow that, because it's bad for OOP to have circular dependencies?
+* Better exceptions -- add some Exception classes.
+* Have Selection class lazily do mapping, instead of eagerly in the repository?
+* Unit tests.
+    * We currently only have integration/acceptance tests.
+    * Pluralize.
+        * Will have to move it to its own file and make it public.
+* Add has_many :through relations.
+    * Might already work with the existing code, and just need testing.
+    * Allow, but don't require, join table to have an associated Repository object.
+    * Use ActiveRecord syntax, but store them separately in Mapper.
+* Should we catch exceptions from the DB?
+    * Should we reraise them with our own exception class?
+    * Should we swallow them?
+* Cleanup.
+    * Clean up Mapper a bit more.
+    * Setting up the DB in spec_helper is terrible.
+        * At least move it to a separate file.
+* Better documentation.
+    * README isn't great at explaining how to use it.
+    * Should make recommendations on how to use this.
+        * In Rails, recommend putting repositories in app/repositories/.
+            * Add that to LOAD_PATH, but don't auto-load.
+        * Repository file should require domain model file, but never vice-versa.
+        * Recommend they consider using 'Users' instead of 'UserRepository'.
+* Handle Virtus models.
+    * Get list of default mappings from model attributes list.
+    * New up the object with all attributes, instead of setting them individually.
+    * Will probably make this a separate gem.
+        * Can layer on top, or inject extra strategies for object creation and default mappings.
+* Identity map.
+    * For cases where we're creating a bunch of objects, but some already exist.
+    * Allow a way to specify that a model is a value type (which doesn't have an identity).
+        * Does it make sense to have these in the database?
+* Test for mapping both type and name.
+    * Probably already works.
+* Fit into ActiveModel.
+    * Would require picking one base class for models.
+        * Would lose the ability to use POROs (at least when using ActiveModel).
+    * Would require mutual dependencies.
+        * The model will have to call to the repo to persist itself.
+        * The repo will need to know about the model.
+            * Maybe there's a way to actually break this, since our mapping doesn't need it immediately.
+    * Would require also including a validation layer (I think).
+* Connection pooling.
+* Is there a way we could do dirty tracking/updating?
+    * This would require some help from the model.
+        * So we'd probably make it optional, depending on whether the model supports it.
+* Is there a way we could do optimistic locking?
+* Is there a way we could do lazy loading of associations?
+* Transactions / Unit of Work.
+* Composite keys.
+* Use Mutant for testing.
+* Use a CI service.
+* Use Ruby 2.1 keyword arguments.
+* Use cursors.
+* Performance testing.

data/lib/preserves.rb

@@ -0,0 +1,24 @@
+require "preserves/version"
+require "preserves/repository"
+require "preserves/sql"
+
+
+module Preserves
+  def self.repository(options={}, &block)
+    repository = Repository.new(options)
+    repository.instance_eval(&block)
+    repository
+  end
+
+  def self.data_store=(connection)
+    @data_store = connection
+  end
+
+  def self.data_store
+    @data_store or raise "You must define a default data store"
+  end
+
+  def self.PostgreSQL(db_name)
+    SQL.connection(dbname: db_name)
+  end
+end

data/lib/preserves/mapper.rb

@@ -0,0 +1,108 @@
+# Terminology note: A field is associated with a single row/record. A column pertains to all rows/records.
+
+require "preserves/mapping"
+require "preserves/mapper/has_many"
+require "preserves/mapper/belongs_to"
+
+
+module Preserves
+  class Mapper
+
+    attr_accessor :mapping
+
+    def initialize(mapping)
+      self.mapping = mapping
+    end
+
+    def map(result, relations={})
+      result.map do |record|
+        map_one(record, relations)
+      end
+    end
+
+    def map_one(record, relations={})
+      mapping.model_class.new.tap do |object|
+        map_attributes(object, record)
+        map_relations(object, record, relations)
+      end
+    end
+
+  protected
+
+    def primary_key_attribute
+      column_name_to_attribute_name(mapping.primary_key)
+    end
+
+  private
+
+    def map_attributes(object, record)
+      record.each_pair do |column_name, field_value|
+        attribute_name = column_name_to_attribute_name(column_name)
+        if object.respond_to?("#{attribute_name}=")
+          object.send("#{attribute_name}=", field_value_to_attribute_value(attribute_name, field_value))
+        end
+      end
+    end
+
+    def column_name_to_attribute_name(column_name)
+      mapping.name_mappings.fetch(column_name) { column_name }
+    end
+
+    def field_value_to_attribute_value(attribute_name, field_value)
+      attribute_type = attribute_name_to_attribute_type(attribute_name)
+      coerce(field_value, to: attribute_type)
+    end
+
+    def attribute_value_to_field_value(attribute_name, attribute_value)
+      attribute_type = attribute_name_to_attribute_type(attribute_name)
+      uncoerce(attribute_value, to: attribute_type)
+    end
+
+    def attribute_name_to_attribute_type(attribute_name)
+      mapping.type_mappings.fetch(attribute_name.to_sym) { String }
+    end
+
+    def map_relations(object, record, relations)
+      has_many_relations = relations.select{ |k, _v| mapping.has_many_mappings.keys.include?(k) }
+      map_has_many_relations(object, record, has_many_relations)
+      belongs_to_relations = relations.select{ |k, _v| mapping.belongs_to_mappings.keys.include?(k) }
+      map_belongs_to_relations(object, record, belongs_to_relations)
+      # TODO: Raise an exception if any of the relations weren't found in any of the relation mappings.
+    end
+
+    def map_has_many_relations(object, record, relations)
+      # TODO: Ensure that there's a setter for every relation_name before we iterate through the relations.
+      relations.each do |relation_name, relation_result_set|
+        Mapper::HasMany.new(object, record, relation_name, relation_result_set, mapping).map!
+      end
+    end
+
+    def map_belongs_to_relations(object, record, relations)
+      # TODO: Ensure that there's a setter for every relation_name before we iterate through the relations.
+      relations.each do |relation_name, relation_result_set|
+        Mapper::BelongsTo.new(object, record, relation_name, relation_result_set, mapping).map!
+      end
+    end
+
+    def coerce(field_value, options={})
+      return nil if field_value.nil?
+
+      if options[:to] == Integer
+        Integer(field_value)
+      else
+        field_value
+      end
+    end
+
+    def uncoerce(attribute_value, options={})
+      return "NULL" if attribute_value.nil?
+
+      if options[:to] == String
+        "'#{attribute_value}'"
+      else
+        attribute_value.to_s
+      end
+    end
+
+  end
+end