couchbase-model 0.0.1 → 0.1.0

data/.travis.yml

@@ -1,6 +1,6 @@
 before_install:
   - wget -O- http://packages.couchbase.com/ubuntu/couchbase.key | sudo apt-key add -
-  - echo deb http://packages.couchbase.com/ubuntu lucid lucid/main | sudo tee /etc/apt/sources.list.d/couchbase.list
+  - echo deb http://packages.couchbase.com/preview/ubuntu lucid lucid/main | sudo tee /etc/apt/sources.list.d/couchbase.list
   - sudo apt-get update
   - sudo apt-get -y install libevent-dev libvbucket-dev libcouchbase-dev
 

data/README.markdown

@@ -1,6 +1,41 @@
-# Couchbase Model [![Build Status](https://secure.travis-ci.org/avsej/ruby-couchbase-model.png?branch=master)](http://travis-ci.org/avsej/ruby-couchbase-model)
+# Couchbase Model
 
-This library allows to declare models for [couchbase gem][1]. Here are example:
+This library allows to declare models for [couchbase gem][1].
+
+## Rails integration
+
+To generate config you can use `rails generate couchbase:config`:
+
+    $ rails generate couchbase:config
+    create  config/couchbase.yml
+
+It will generate this `config/couchbase.yml` for you:
+
+    common: &common
+      hostname: localhost
+      port: 8091
+      username:
+      password:
+      pool: default
+
+    development:
+      <<: *common
+      bucket: couchbase_tinyurl_development
+
+    test:
+      <<: *common
+      bucket: couchbase_tinyurl_test
+
+    # set these environment variables on your production server
+    production:
+      hostname: <%= ENV['COUCHBASE_HOST'] %>
+      port: <%= ENV['COUCHBASE_PORT'] %>
+      username: <%= ENV['COUCHBASE_USERNAME'] %>
+      password: <%= ENV['COUCHBASE_PASSWORD'] %>
+      pool: <%= ENV['COUCHBASE_POOL'] %>
+      bucket: <%= ENV['COUCHBASE_BUCKET'] %>
+
+## Examples
 
     require 'couchbase/model'
 
@@ -48,4 +83,58 @@ You can define connection options on per model basis:
       connect :port => 80, :bucket => 'blog'
     end
 
+## Views (aka Map/Reduce queries to Couchbase)
+
+Views are stored in models directory in subdirectory named after the
+model (to be precious `design_document` attribute of the model class).
+Here is an example of directory layout for `Link` model with three
+views.
+
+    .
+    └── app
+        └── models
+            ├── link
+            │   ├── total_count
+            │   │   ├── map.js
+            │   │   └── reduce.js
+            │   ├── by_created_at
+            │   │   └── map.js
+            │   └── by_view_count
+            │       └── map.js
+            └── link.rb
+
+To generate view you can use yet another generator `rails generate
+couchbase:view DESIGNDOCNAME VIEWNAME`. For example how `total_count`
+view could be generated:
+
+    $ rails generate link total_count
+
+The generated files contains useful info and links about how to write
+map and reduce functions, you can take a look at them in the [templates
+directory][2].
+
+In the model class you should declare accessible views:
+
+    class Post < Couchbase::Model
+      attribute :title
+      attribute :body
+      attribute :draft
+      attribute :view_count
+      attribute :created_at, :default => lambda { Time.now }
+
+      view :total_count, :by_created_at, :by_view_count
+    end
+
+And request them later:
+
+    Post.by_created_at(:include_docs => true).each do |post|
+      puts post.title
+    end
+
+    Post.by_view_count(:include_docs => true).group_by(&:view_count) do |count, posts|
+      p "#{count} -> #{posts.map{|pp| pp.inspect}.join(', ')}"
+    end
+
+
 [1]: https://github.com/couchbase/couchbase-ruby-client/
+[2]: https://github.com/couchbaselabs/ruby-couchbase-model/tree/master/lib/rails/generators/couchbase/view/templates/

data/couchbase-model.gemspec

@@ -5,9 +5,9 @@ require "couchbase/model/version"
 Gem::Specification.new do |s|
   s.name        = "couchbase-model"
   s.version     = Couchbase::Model::VERSION
-  s.authors     = ["Sergey Avseyev"]
-  s.email       = ["sergey.avseyev@gmail.com"]
-  s.homepage    = ""
+  s.author      = "Couchbase"
+  s.email       = "support@couchbase.com"
+  s.homepage    = "https://github.com/couchbaselabs/ruby-couchbase-model"
   s.summary     = %q{Declarative interface to Couchbase}
   s.description = %q{ORM-like interface allows you to persist your models to Couchbase}
 
@@ -16,7 +16,7 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
 
-  s.add_runtime_dependency 'couchbase', '~> 1.1.0'
+  s.add_runtime_dependency 'couchbase', '~> 1.2.0.dp'
 
   s.add_development_dependency 'rake', '~> 0.8.7'
   s.add_development_dependency 'minitest'

data/lib/couchbase-model.rb

@@ -16,3 +16,8 @@
 #
 
 require 'couchbase/model'
+
+# If we are using Rails then we will include the Couchbase railtie.
+if defined?(Rails)
+  require "couchbase/railtie"
+end

data/lib/couchbase/model.rb

@@ -15,16 +15,22 @@
 # limitations under the License.
 #
 
+require 'digest/md5'
+
 require 'couchbase'
 require 'couchbase/model/version'
 require 'couchbase/model/uuid'
+require 'couchbase/model/configuration'
 
 module Couchbase
 
+  # @since 0.0.1
   class Error::MissingId < Error::Base; end
 
   # Declarative layer for Couchbase gem
   #
+  # @since 0.0.1
+  #
   #  require 'couchbase/model'
   #
   #  class Post < Couchbase::Model
@@ -72,14 +78,35 @@ module Couchbase
   #  end
   class Model
     # Each model must have identifier
+    #
+    # @since 0.0.1
     attr_accessor :id
 
-    # @private Container for all attributes of all subclasses
-    @@attributes = ::Hash.new {|hash, key| hash[key] = []}
+    # @since 0.1.0
+    attr_reader :_key
+
+    # @since 0.1.0
+    attr_reader :_value
+
+    # @since 0.1.0
+    attr_reader :_doc
+
+    # @since 0.1.0
+    attr_reader :_meta
+
+    # @private Container for all attributes with defaults of all subclasses
+    @@attributes = ::Hash.new {|hash, key| hash[key] = {}}
+
+    # @private Container for all view names of all subclasses
+    @@views = ::Hash.new {|hash, key| hash[key] = []}
 
     # Use custom connection options
     #
-    # @param [String, Hash, Array] options for establishing connection.
+    # @since 0.0.1
+    #
+    # @param [String, Hash, Array] options options for establishing
+    #   connection.
+    # @return [Couchbase::Bucket]
     #
     # @see Couchbase::Bucket#initialize
     #
@@ -92,8 +119,108 @@ module Couchbase
       self.bucket = Couchbase.connect(*options)
     end
 
+    # Associate custom design document with the model
+    #
+    # Design document is the special document which contains views, the
+    # chunks of code for building map/reduce indexes. When this method
+    # called without argument, it just returns the effective design document
+    # name.
+    #
+    # @since 0.1.0
+    #
+    # @see http://www.couchbase.com/docs/couchbase-manual-2.0/couchbase-views.html
+    #
+    # @param [String, Symbol] name the name for the design document. By
+    #   default underscored model name is used.
+    # @return [String] the effective design document
+    #
+    # @example Choose specific design document name
+    #   class Post < Couchbase::Model
+    #     design_document :my_posts
+    #     ...
+    #   end
+    def self.design_document(name = nil)
+      if name
+        @_design_doc = name.to_s
+      else
+        @_design_doc ||= begin
+                           name = self.name.dup
+                           name.gsub!(/::/, '_')
+                           name.gsub!(/([A-Z\d]+)([A-Z][a-z])/,'\1_\2')
+                           name.gsub!(/([a-z\d])([A-Z])/,'\1_\2')
+                           name.downcase!
+                         end
+      end
+    end
+
+    # Ensure that design document is up to date.
+    #
+    # @since 0.1.0
+    #
+    # This method also cares about organizing view in separate javascript
+    # files. The general structure is the following (+[root]+ is the
+    # directory, one of the {Model::Configuration.design_documents_paths}):
+    #
+    #   [root]
+    #   |
+    #   `- link
+    #   |  |
+    #   |  `- by_created_at
+    #   |  |  |
+    #   |  |  `- map.js
+    #   |  |
+    #   |  `- by_session_id
+    #   |  |  |
+    #   |  |  `- map.js
+    #   |  |
+    #   |  `- total_views
+    #   |  |  |
+    #   |  |  `- map.js
+    #   |  |  |
+    #   |  |  `- reduce.js
+    #
+    # The directory structure above demonstrate layout for design document
+    # with id +_design/link+ and three views: +by_create_at+,
+    # +by_session_id` and `total_views`.
+    def self.ensure_design_document!
+      unless Configuration.design_documents_paths
+        raise "Configuration.design_documents_path must be directory"
+      end
+
+      doc = {'_id' => "_design/#{design_document}", 'views' => {}}
+      digest = Digest::MD5.new
+      mtime = 0
+      views.each do |name|
+        doc['views'][name] = view = {}
+        ['map', 'reduce'].each do |type|
+          Configuration.design_documents_paths.each do |path|
+            ff = File.join(path, design_document.to_s, name.to_s, "#{type}.js")
+            if File.file?(ff)
+              view[type] = File.read(ff)
+              mtime = [mtime, File.mtime(ff).to_i].max
+              digest << view[type]
+              break # pick first matching file
+            end
+          end
+        end
+      end
+      doc['signature'] = digest.to_s
+      doc['timestamp'] = mtime
+      if doc['signature'] != thread_storage[:signature] && doc['timestamp'] > thread_storage[:timestamp].to_i
+        current_doc = bucket.design_docs[design_document.to_s]
+        if current_doc.nil? || (current_doc['signature'] != doc['signature'] && doc['timestamp'] > current_doc[:timestamp].to_i)
+          bucket.save_design_doc(doc)
+          current_doc = doc
+        end
+        thread_storage[:signature] = current_doc['signature']
+        thread_storage[:timestamp] = current_doc['timestamp'].to_i
+      end
+    end
+
     # Choose the UUID generation algorithms
     #
+    # @since 0.0.1
+    #
     # @param [Symbol] algorithm (:sequential) one of the available
     #   algorithms.
     #
@@ -104,12 +231,16 @@ module Couchbase
     #     uuid_algorithm :random
     #     ...
     #   end
+    #
+    # @return [Symbol]
     def self.uuid_algorithm(algorithm)
       self.thread_storage[:uuid_algorithm] = algorithm
     end
 
     # Defines an attribute for the model
     #
+    # @since 0.0.1
+    #
     # @param [Symbol, String] name name of the attribute
     #
     # @example Define some attributes for a model
@@ -122,49 +253,114 @@ module Couchbase
     #  post = Post.new(:title => 'Hello world',
     #                  :body => 'This is the first example...',
     #                  :published_at => Time.now)
-    def self.attribute(name)
-      define_method(name) do
-        @_attributes[name]
+    def self.attribute(*names)
+      options = {}
+      if names.last.is_a?(Hash)
+        options = names.pop
       end
-      define_method(:"#{name}=") do |value|
-        @_attributes[name] = value
+      names.each do |name|
+        name = name.to_sym
+        define_method(name) do
+          @_attributes[name]
+        end
+        define_method(:"#{name}=") do |value|
+          @_attributes[name] = value
+        end
+        attributes[name] = options[:default]
+      end
+    end
+
+    def self.view(*names)
+      options = {}
+      if names.last.is_a?(Hash)
+        options = names.pop
+      end
+      names.each do |name|
+        views << name
+        self.instance_eval <<-EOV, __FILE__, __LINE__ + 1
+          def #{name}(params = {})
+            View.new(bucket, "_design/\#{design_document}/_view/#{name}",
+                     params.merge(:wrapper_class => self, :include_docs => true))
+          end
+        EOV
       end
-      attributes << name unless attributes.include?(name)
     end
 
     # Find the model using +id+ attribute
     #
+    # @since 0.0.1
+    #
     # @param [String, Symbol] id model identificator
     # @return [Couchbase::Model] an instance of the model
+    # @raise [Couchbase::Error::NotFound] when given key isn't exist
     #
     # @example Find model using +id+
     #   post = Post.find('the-id')
     def self.find(id)
-      if id && (obj = bucket.get(id))
-        new({:id => id}.merge(obj))
+      if id && (res = bucket.get(id, :quiet => false, :extended => true))
+        obj, flags, cas = res
+        new({:id => id, :_meta => {'flags' => flags, 'cas' => cas}}.merge(obj))
+      end
+    end
+
+    # Find the model using +id+ attribute
+    #
+    # @since 0.1.0
+    #
+    # @param [String, Symbol] id model identificator
+    # @return [Couchbase::Model, nil] an instance of the model or +nil+ if
+    #   given key isn't exist
+    #
+    # @example Find model using +id+
+    #   post = Post.find_by_id('the-id')
+    def self.find_by_id(id)
+      if id && (res = bucket.get(id, :quiet => true))
+        obj, flags, cas = res
+        new({:id => id, :_meta => {'flags' => flags, 'cas' => cas}}.merge(obj))
       end
     end
 
     # Create the model with given attributes
     #
+    # @since 0.0.1
+    #
     # @param [Hash] args attribute-value pairs for the object
     # @return [Couchbase::Model] an instance of the model
     def self.create(*args)
       new(*args).create
     end
 
-    # Constructor for all subclasses of Couchbase::Model, which optionally
-    # takes a Hash of attribute value pairs.
+    # Constructor for all subclasses of Couchbase::Model
+    #
+    # @since 0.0.1
+    #
+    # Optionally takes a Hash of attribute value pairs.
     #
     # @param [Hash] attrs attribute-value pairs
     def initialize(attrs = {})
-      @id = nil
-      @_attributes = ::Hash.new
-      update_attributes(attrs)
+      if attrs.respond_to?(:with_indifferent_access)
+        attrs = attrs.with_indifferent_access
+      end
+      @id = attrs.delete(:id)
+      @_key = attrs.delete(:_key)
+      @_value = attrs.delete(:_value)
+      @_doc = attrs.delete(:_doc)
+      @_meta = attrs.delete(:_meta)
+      @_attributes = ::Hash.new do |h, k|
+        default = self.class.attributes[k]
+        h[k] = if default.respond_to?(:call)
+                 default.call
+               else
+                 default
+               end
+      end
+      update_attributes(@_doc || attrs)
     end
 
     # Create this model and assign new id if necessary
     #
+    # @since 0.0.1
+    #
     # @return [Couchbase::Model] newly created object
     #
     # @raise [Couchbase::Error::KeyExists] if model with the same +id+
@@ -175,12 +371,14 @@ module Couchbase
     #   p.create
     def create
       @id ||= Couchbase::Model::UUID.generator.next(1, model.thread_storage[:uuid_algorithm])
-      model.bucket.add(@id, attributes)
+      model.bucket.add(@id, attributes_with_values)
       self
     end
 
     # Create or update this object based on the state of #new?.
     #
+    # @since 0.0.1
+    #
     # @return [Couchbase::Model] The saved object
     #
     # @example Update the Post model
@@ -189,12 +387,14 @@ module Couchbase
     #   p.save
     def save
       return create if new?
-      model.bucket.set(@id, attributes)
+      model.bucket.set(@id, attributes_with_values)
       self
     end
 
     # Update this object, optionally accepting new attributes.
     #
+    # @since 0.0.1
+    #
     # @param [Hash] attrs Attribute value pairs to use for the updated
     #               version
     # @return [Couchbase::Model] The updated object
@@ -205,6 +405,8 @@ module Couchbase
 
     # Delete this object from the bucket
     #
+    # @since 0.0.1
+    #
     # @note This method will reset +id+ attribute
     #
     # @return [Couchbase::Model] Returns a reference of itself.
@@ -221,6 +423,8 @@ module Couchbase
 
     # Check if the record have +id+ attribute
     #
+    # @since 0.0.1
+    #
     # @return [true, false] Whether or not this object has an id.
     #
     # @note +true+ doesn't mean that record exists in the database
@@ -232,6 +436,8 @@ module Couchbase
 
     # Check if the key exists in the bucket
     #
+    # @since 0.0.1
+    #
     # @param [String, Symbol] id the record identifier
     # @return [true, false] Whether or not the object with given +id+
     #   presented in the bucket.
@@ -241,21 +447,40 @@ module Couchbase
 
     # Check if this model exists in the bucket.
     #
+    # @since 0.0.1
+    #
     # @return [true, false] Whether or not this object presented in the
     #   bucket.
     def exists?
       model.exists?(@id)
     end
 
-    # All the defined attributes within a class.
+    # All defined attributes within a class.
+    #
+    # @since 0.0.1
     #
     # @see Model.attribute
+    #
+    # @return [Hash]
     def self.attributes
       @@attributes[self]
     end
 
+    # All defined views within a class.
+    #
+    # @since 0.1.0
+    #
+    # @see Model.view
+    #
+    # @return [Array]
+    def self.views
+      @@views[self]
+    end
+
     # All the attributes of the current instance
     #
+    # @since 0.0.1
+    #
     # @return [Hash]
     def attributes
       @_attributes
@@ -263,18 +488,23 @@ module Couchbase
 
     # Update all attributes without persisting the changes.
     #
+    # @since 0.0.1
+    #
     # @param [Hash] attrs attribute-value pairs.
     def update_attributes(attrs)
       if id = attrs.delete(:id)
         @id = id
       end
       attrs.each do |key, value|
-        send(:"#{key}=", value)
+        setter = :"#{key}="
+        send(setter, value) if respond_to?(setter)
       end
     end
 
     # Reload all the model attributes from the bucket
     #
+    # @since 0.0.1
+    #
     # @return [Model] the latest model state
     #
     # @raise [Error::MissingId] for records without +id+
@@ -287,46 +517,99 @@ module Couchbase
     end
 
     # @private The thread local storage for model specific stuff
+    #
+    # @since 0.0.1
     def self.thread_storage
       Couchbase.thread_storage[self] ||= {:uuid_algorithm => :sequential}
     end
 
     # @private Fetch the current connection
+    #
+    # @since 0.0.1
     def self.bucket
       self.thread_storage[:bucket] ||= Couchbase.bucket
     end
 
     # @private Set the current connection
     #
+    # @since 0.0.1
+    #
     # @param [Bucket] connection the connection instance
     def self.bucket=(connection)
       self.thread_storage[:bucket] = connection
     end
 
     # @private Get model class
+    #
+    # @since 0.0.1
     def model
       self.class
     end
 
-    # @private Wrap the hash to the model class
-    #
-    # @param [Model, Hash] the Couchbase::Model subclass or the
-    #   attribute-value pairs
-    def self.wrap(object)
-      object.class == self ? object : new(object)
+    # @private Wrap the hash to the model class.
+    #
+    # @since 0.0.1
+    #
+    # @param [Bucket] bucket the reference to Bucket instance
+    # @param [Hash] data the Hash fetched by View, it should have at least
+    #   +"id"+, +"key"+ and +"value"+ keys, also it could have optional
+    #   +"doc"+ key.
+    #
+    # @return [Model]
+    def self.wrap(bucket, data)
+      doc = {
+        :_key => data['key'],
+        :_value => data['value'],
+        :_meta => {},
+        :id => data['id']
+      }
+      if doc[:_value].is_a?(Hash) && (_id = doc[:_value]['_id'])
+        doc[:id] = _id
+      end
+      if data['doc']
+        data['doc'].keys.each do |key|
+          if key.start_with?("$")
+            doc[:_meta][key.sub(/^\$/, '')] = data['doc'].delete(key)
+          end
+        end
+        doc.update(data['doc'])
+      end
+      new(doc)
     end
 
     # @private Returns a string containing a human-readable representation
     # of the record.
+    #
+    # @since 0.0.1
     def inspect
-      attrs = model.attributes.sort.map do |attr|
-        [attr, @_attributes[attr].inspect]
-      end
+      attrs = model.attributes.map do |attr, default|
+        [attr.to_s, @_attributes[attr].inspect]
+      end.sort
       sprintf("#<%s:%s %s>",
               model, new? ? "?" : id,
-              attrs.map{|a| a.join("=")}.join(" "))
+              attrs.map{|a| a.join("=")}.join(", "))
+    end
+
+    def self.inspect
+      buf = "#{name}"
+      if self != Couchbase::Model
+        buf << "(#{['id', attributes.map(&:first)].flatten.join(', ')})"
+      end
+      buf
     end
 
+    protected
+
+    # @private Returns a hash with model attributes
+    #
+    # @since 0.1.0
+    def attributes_with_values
+      ret = {:type => model.design_document}
+      model.attributes.keys.each do |attr|
+        ret[attr] = @_attributes[attr]
+      end
+      ret
+    end
   end
 
 end