yadm 0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 100c78414b9dd599615ad79f69f2deabb996aecc
+  data.tar.gz: fa7071ad5525b2666c38f1b592ea8462ca1cd7aa
+SHA512:
+  metadata.gz: 467fd5032131f79119bc4f68a66834079696f910ad517d5eeeaf7fcc7247268508ecd053ad6f79de712dbe0f8afd757b6f03aadaa7078d8da41b6e9894ee2c1a
+  data.tar.gz: c754c914bd0fcf31c4459879cef43a4c21676e3e827ad9f3945a4fb7f586aaf9f3b88733423989467ea7ee45fcf0ad662c101a3ef1f89cee17a4fd2801ba6bf6

data/.gitignore

@@ -0,0 +1,8 @@
+/.bundle
+/.yardoc
+/_yardoc
+/Gemfile.lock
+/doc
+/pkg
+/tmp
+/*.sqlite

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format documentation
+--require spec_helper

data/Gemfile

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

data/Guardfile

@@ -0,0 +1,8 @@
+guard :rspec, all_on_start: true, cmd: 'bundle exec rspec' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})        { |m| "spec/#{m[1]}_spec.rb" }
+  watch(%r{^spec/support/.+\.rb$}) { 'spec' }
+  watch('spec/spec_helper.rb')     { 'spec' }
+  
+  watch('lib/yadm/adapters/common_sql.rb') { 'spec/yadm/adapters' }
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Vsevolod Romashov
+
+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,273 @@
+# YADM - Yet Another Data Mapper
+
+Another attempt to implement Data Mapper in ruby.
+
+Built with 2 goals in mind:
+
+* to get familiar with common pitfalls in implementing Data Mapper
+* to make a tool that can be useful now and has the potential to be able
+to serve as a replacement for ActiveRecord eventually
+
+## Installation
+
+```ruby
+# Gemfile
+gem 'yadm'
+```
+
+``` sh
+$ bundle
+```
+
+## Usage
+
+YADM consists of several components:
+
+* entities
+* repositories
+* identity map
+* data sources
+* mapper
+
+### Entities
+
+Entity is a basic object with some attributes.
+
+You can create an entity by defining a class that includes `YADM::Entity`:
+
+``` ruby
+class Person
+  include YADM::Entity
+  
+  attributes :first_name, :last_name, :email, :password, :age
+end
+```
+
+_You don't need to specify the `id` attribute, it comes by default._
+
+### Repositories
+
+A repository is a module representing a collection of entities. It can fetch
+the objects from the data store and persist the changes back. Here you can
+define complex criteria for querying the data source.
+
+A repository is created as a module that includes `YADM::Repository`
+and specifies it's entity:
+
+``` ruby
+module People
+  include YADM::Repository
+  entity Person
+  
+  criteria :kids do
+    with { age < 12 }
+  end
+  
+  criteria :older_than do |min_age|
+    with { age > min_age }
+  end
+  
+  criteria :in_alphabetical_order do
+    ascending_by { last_name }.ascending_by { first_name }
+  end
+  
+  criteria :oldest do |count|
+    descending_by { age }.first(count)
+  end
+end
+```
+
+### Identity map
+
+The identity map is a cache for data.
+
+Most data requests first look it up in the identity map. If it's there
+it is returned without accessing the data source; otherwise it is pulled from
+the data source, put into the map for subsequent queries and then returned.
+
+_Currently the identity map doesn't handle any complex queries - only `.find`
+calls are cached._
+
+### Data sources
+
+Data sources encapsulate the ability to read the data and write it back.
+They are defined by adapters for different data storage solutions;
+YADM ships with the following adapters:
+
+* `memory` (useful for testing)
+* `sqlite` (requires `sequel` and `sqlite3` gems)
+* `mysql` (requires `sequel` and `mysql2` gems)
+* `postgresql` (requires `sequel` and `pg` gems)
+
+Adapters are not required by default (because of their dependencies)
+so you should manually require each adapter you need manually.
+
+You can register a data source with some unique identifier to use it later on:
+
+``` ruby
+require 'yadm/adapters/memory'
+require 'yadm/adapters/postgresql'
+
+YADM.setup do
+  data_source :memory_store, adapter: :memory
+  data_source :pg_store, adapter: :postgresql, database: 'yadm', user: 'yadm', password: 'yadm'
+end
+```
+
+### Mapper
+
+Mapper is the central part glueing everything together - it connects
+repositories to data sources.
+
+Assuming the `memory_store` data source created earlier
+we can link the repository to it and define some attributes:
+
+``` ruby
+YADM.setup do
+  map do
+    repository People do
+      data_source :memory_store
+      collection  :people
+      
+      attribute :id,         Integer
+      attribute :first_name, String
+      attribute :last_name,  String
+      attribute :email,      String
+      attribute :password,   String
+      attribute :age,        Integer
+    end
+  end
+end
+```
+
+_The data source is divided into separate collections represented by tables
+in a database (and by plain ruby hashes in the memory adapter)._
+
+### Creating a new record
+
+A new record can be created by building a new entity object and passing it
+to it's repository `.persist` method. Entity gets an `id` after being saved.
+
+``` ruby
+john = Person.new(
+  first_name: 'John',
+  last_name:  'Smith',
+  email:      'john@smiths.com',
+  password:   'secret',
+  age:        28
+)
+john.id # => nil
+
+People.persist(john)
+jonh.id # => 1
+```
+
+### Getting a record by id
+
+Dead simple:
+
+``` ruby
+People.find(1) # => #<Person:0x007ffdeab7f8c8 ...>
+```
+
+### Updating a record
+
+The `.persist` method is able to distinguish between a new entity and
+an already saved one; in the latter case it updates the respective record
+in the data source.
+
+``` ruby
+john.password = 'f1E2m0CdP'
+People.persist(john)
+```
+
+### Deleting a record
+
+Deleting a record is as simple as passing the respective entity to
+`.delete` method.
+
+``` ruby
+People.delete(john)
+```
+
+### Using complex queries
+
+The `criteria` method in the repository DSL (mentioned earlier)
+allows to create query criteria such as query conditions, order and limit.
+Criteria's name serves as a name for the repository method
+that applies the criteria.
+
+``` ruby
+People.kids # => #<People::Query:0x007f940b104db0 ...>
+```
+
+The query object is enumerable - you can call any `Enumerable` methods such as
+`each` or `map` on it. Data is fetched lazily: the data source will be asked
+for data only when it is needed:
+
+``` ruby
+People.kids.map(&:first_name) # => ['John']
+```
+
+This laziness allows to chain criteria methods together effectively merging
+them in one big criteria:
+
+``` ruby
+People.older_than(30).in_alphabetical_order # => #<People::Query:0x007f940a9abed8 ...>
+```
+
+When you just want to get all the records without filtering/ordering them
+you can call `.to_a` on the repository:
+
+``` ruby
+People.to_a # => [#<Person:0x007f940ae39360 ...>, #<Person:0x007f940acfa580 ...>]
+```
+
+_You can call enumerable methods on the repository as well - this allows
+to traverse all records in the collection._
+
+### Migrations
+
+Working with a relational database requires changing it's schema often;
+this is what migrations are for. YADM provides a very simple interface for
+defining [sequel migrations](http://sequel.jeremyevans.net/rdoc/files/doc/schema_modification_rdoc.html):
+
+``` ruby
+YADM.migrate :store do |db|
+  db.create_table :posts do
+    primary_key :id
+    
+    String  :title
+    String  :author
+    Integer :comments
+    Time    :created_at
+  end
+end
+```
+
+_You must define the respective data source before trying to migrate it._
+
+## Roadmap
+
+* SQL joins
+* associations
+* more adapters
+
+## Acknowledgements
+
+This project is heavily inspired by [lotus/model](https://github.com/lotus/model)
+and [ROM](http://rom-rb.org) projects, the [famous Uncle Bob's
+"Architecture the Lost Years"](http://www.youtube.com/watch?v=WpkDN78P884)
+and [POODR](http://www.poodr.com/) of course.
+
+## Examples
+
+There are a couple examples in the `examples/` directory.
+
+## Contributing
+
+1. Fork it (https://github.com/7even/yadm/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,10 @@
+require 'bundler/gem_tasks'
+
+desc 'Loads YADM and launches a console'
+task :console do
+  require 'yadm'
+  require 'pry'
+  Pry.start
+end
+
+task default: :console

data/examples/basic.rb

@@ -0,0 +1,43 @@
+# use with `pry -r ./examples/basic.rb`
+$LOAD_PATH << File.expand_path('../../lib')
+require 'yadm'
+require 'yadm/adapters/memory'
+
+class Person
+  include YADM::Entity
+  attributes :first_name, :last_name, :age
+end
+
+module People
+  include YADM::Repository
+  entity Person
+  
+  criteria :older_than do |min_age|
+    with { age > min_age }
+  end
+  
+  criteria :in_alphabetical_order do
+    ascending_by { last_name }.ascending_by { first_name }
+  end
+end
+
+YADM.setup do
+  data_source :store, adapter: :memory
+  
+  map do
+    repository People do
+      data_source :store
+      collection  :people
+      
+      attribute :id, Integer
+      attribute :first_name, String
+      attribute :last_name, String
+      attribute :age, Integer
+    end
+  end
+end
+
+[
+  Person.new(first_name: 'Vsevolod', last_name: 'Romashov', age: 30),
+  Person.new(first_name: 'Alexey', last_name: 'Kurepin', age: 29)
+].each { |person| People.persist(person) }

data/examples/migration.rb

@@ -0,0 +1,65 @@
+# use with `pry -r ./examples/migration.rb`
+$LOAD_PATH << File.expand_path('../../lib')
+require 'yadm'
+require 'yadm/adapters/sqlite'
+
+class Post
+  include YADM::Entity
+  attributes :title, :author, :comments, :created_at
+end
+
+module Posts
+  include YADM::Repository
+  entity Post
+  
+  criteria :recent do
+    descending_by { created_at }.first(20)
+  end
+  
+  criteria :created_by do |given_author|
+    with { author == given_author }
+  end
+end
+
+YADM.setup do
+  data_source :store, adapter: :sqlite
+  
+  map do
+    repository Posts do
+      data_source :store
+      collection  :posts
+      
+      attribute :id,         Integer
+      attribute :title,      String
+      attribute :author,     String
+      attribute :comments,   Integer
+      attribute :created_at, Time
+    end
+  end
+end
+
+YADM.migrate :store do |db|
+  db.create_table :posts do
+    primary_key :id
+    
+    String  :title
+    String  :author
+    Integer :comments
+    Time    :created_at
+  end
+end
+
+[
+  Post.new(
+    title:      'Hello World!',
+    author:     '7even',
+    comments:   7,
+    created_at: Time.now - 3600
+  ),
+  Post.new(
+    title:      'Goodbye cruel world.',
+    author:     'foxweb',
+    comments:   5,
+    created_at: Time.now - 1800
+  )
+].each { |post| Posts.persist(post) }