post_json 1.0.11 → 1.0.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fb5fea92951fd8ec7e82b70905b2ae78c5e28071
-  data.tar.gz: 412eaafc6a0b9c802dd02116898dc173f194d454
+  metadata.gz: 52a70dfcec7f3478c9b2fab7e465c5b33c97229b
+  data.tar.gz: 7d302f9d087bc00360e203320e0afd5b64e3eb1d
 SHA512:
-  metadata.gz: 4874f99abaec969d3544de9ad4e1db5f651a16d50625ecb9112e2913b2048e7c6183b5ab154efcec482a1d0a6ab957a37a7a8cb22ec33417db76e548e4f16fe0
-  data.tar.gz: 9fc7845cf1082ed2f0670d43aa8ab07ab27780340122d0f3d139b2e2c9f8a1f8d0aae686f073a4e2f44e8191b05f743cdecf98a8efe94f08ff86462ccc6791ff
+  metadata.gz: b17682fa4780f53680fc7c7c55bb423974208d79356ba6ec70a9ab2ebc16ce9c83a7cc60b6101b71b507797434d84ef33cf9c818b40bbeed268c4b7045d69782
+  data.tar.gz: 99bbe826b5aab7659aaa74fa2e8413023b398940b4bf50aa98ed540989d339a2488c9e7300fb0af0c35cebcbcb4c37dc7d54d7180f41c5f4509e486ce476d4b2

data/README.md

@@ -1,41 +1,38 @@
 # Welcome to PostJson
 
-PostJson is everything you expect of ActiveRecord and PostgreSQL, but with the dynamic nature of document databases 
-(free as a bird - no schemas).
+PostJson is everything you expect of ActiveRecord and PostgreSQL, with the added power and dynamic nature of a document database (Free as a bird! No schemas!). 
 
-PostJson take full advantage of PostgreSQL 9.2+ support for JavaScript (Google's V8 engine). We started the work on 
-PostJson, because we love document databases and PostgreSQL. PostJson combine features of Ruby, ActiveRecord and 
-PostgreSQL to provide a great document database.
+PostJson combines features of Ruby, ActiveRecord and PostgreSQL to provide a great document database by taking advantage of PostgreSQL 9.2+ support for JavaScript (Google's V8 engine). We started the work on PostJson, because we love document databases **and** PostgreSQL. 
 
-See example of how we use PostJson as part of <a href="https://github.com/webnuts/jumpstarter">Jumpstarter</a>.
+See the example of how we use PostJson as part of [Jumpstarter](https://github.com/webnuts/jumpstarter).
 
 
-## Getting started
+## Installation
 
-### Add the gem to your Ruby on Rails application `Gemfile`:
+Add the gem to your `Gemfile`:
 
     gem 'post_json'
-        
-### At the command prompt, install the gem, run the generator, and migrate the db:
 
-    bundle install
-    rails g post_json:install
-    rake db:migrate
+Then:
+
+    $ bundle install
+
+Run the generator and migrate the db:
+
+    $ rails g post_json:install
+    $ rake db:migrate
         
 That's it!
 
 (See POSTGRESQL_INSTALL.md if you need the install instructions for PostgreSQL with PLV8)
 
-## Using it
-
-You should feel home right away, if you already know ActiveRecord. PostJson try hard to respect the ActiveRecord 
-API, so methods work and do as you would expect from ActiveRecord.
+## Usage
 
-PostJson is all about collections. All models represent a collection.
+PostJson also tries hard to respect the ActiveRecord API, so, if you have experience with ActiveRecord, the model methods work as you would expect.
 
-Also, __notice you don't have to define model attributes anywhere!__
+### Model
 
-### Lets create your first model.
+All PostJson models represent a collection.
 
 ```ruby
 class Person < PostJson::Collection["people"]
@@ -43,12 +40,11 @@ end
         
 me = Person.create(name: "Jacob")
 ```
+
+__Notice you don't have to define model attributes anywhere!__
         
-As you can see it look the same as ActiveRecord, except you define `PostJson::Collection["people"]` instead of 
-`ActiveRecord::Base`.
-    
-`Person` can do the same as any model class inheriting `ActiveRecord::Base`.
-    
+As you can see, this is very similar to a standard ActiveRecord model. `PostJson::Collection["people"]` inherits from `PostJson::Base`, which, in turn, inherits from `ActiveRecord::Base`. This is part of the reason the `Person` model will seem so familiar.
+
 You can also skip the creation of a class:
 
 ```ruby    
@@ -56,7 +52,9 @@ people = PostJson::Collection["people"]
 me = people.create(name: "Jacob")
 ```
 
-### Adding some validation:
+### Validations
+
+Use standard `ActiveRecord` validations in your models:
 
 ```ruby
 class Person < PostJson::Collection["people"]
@@ -64,20 +62,13 @@ class Person < PostJson::Collection["people"]
 end
 ```
 
-PostJson::Collection["people"] returns a class, which is based on `PostJson::Base`, which is based on 
-`ActiveRecord::Base`. So its the exact same validation as you may know.
-    
 Read the <a href="http://guides.rubyonrails.org/active_record_validations.html" target="_blank">Rails guide about validation</a> if you need more information.
 
-### Lets create a more complex document and do a query:
+### Querying
 
 ```ruby
 me = Person.create(name: "Jacob", details: {age: 33})
-```
 
-Now we can make a query and get the document:
-
-```ruby    
 # PostJson supports filtering on nested attributes
 also_me_1 = Person.where(details: {age: 33}).first
 also_me_2 = Person.where("details.age" => 33).first
@@ -89,9 +80,7 @@ also_me_3 = Person.where("function(doc) { return doc.details.age == 33; }").firs
 also_me_4 = Person.where("json_details.age = ?", 33).first
 ```        
 
-### Accessing attributes:
-
-Like you would expect with ActiveRecord:
+### Accessing attributes
 
 ```ruby
 person = Person.create(name: "Jacob")
@@ -115,22 +104,55 @@ puts person.name_changed?   # => false
 puts person.name_change     # => nil
 ```
 
-### Introduction to select and selectors.
+### Transformation with `select`
 
-Sometimes we need a transformed version of documents. This is very easy with `select`
+The `select` method allows you to transform a collection of documents into an array of hashes that contain only the attributes you want. The hash passed to `select` maps keys to selectors of arbitrary depth. 
+
+> In this example we only want the 'name' and 'age' attributes from the `Person` but 'age' is nested under 'details'.
 
 ```ruby
+# create a person with age nested under details
 me = Person.create(name: "Jacob", details: {age: 33})
 
+# the dot (.) signifies that the selector is looking for a nested attribute
 other_me = Person.limit(1).select({name: "name", age: "details.age"}).first
 
 puts other_me   
 # => {name: "Jacob", age: 33}
+```
+
+### Dates
+
+Dates are not natively supported by JSON. This is why dates are persisted as strings.
+
+```ruby
+me = Person.create(name: "Jacob", nested: {now: Time.now})
+puts me.attributes
+# => {"name"=>"Jacob", "nested"=>{"now"=>2013-10-24 16:15:05 +0200}, "id"=>"fb9ef4bb-1441-4392-a95d-6402f72829db", "version"=>1, "created_at"=>Thu, 24 Oct 2013 14:15:05 UTC +00:00, "updated_at"=>Thu, 24 Oct 2013 14:15:05 UTC +00:00}
+```
+
+Lets reload it and see how it is stored:
 
+```ruby
+me.reload
+puts me.attributes
+# => {"name"=>"Jacob", "nested"=>{"now"=>"2013-10-24T14:15:05.783Z"}, "id"=>"fb9ef4bb-1441-4392-a95d-6402f72829db", "version"=>1, "created_at"=>"2013-10-24T14:15:05.831Z", "updated_at"=>"2013-10-24T14:15:05.831Z"}
 ```
-`select` takes a hash as argument and return an array of hashes. The value of each key/value pair in the hash argument is a selector. Selectors can point at attributes at root level, but also nested attributes. Each level of attributes is seperated with a dot (.).
 
-### Check out the initializer at `config/initializers/post_json.rb`
+PostJson will serialize Time and DateTime to format `strftime('%Y-%m-%dT%H:%M:%S.%LZ')` when persisting documents.
+
+PostJson will also parse an attribute's value to a `Time` object, if the value is a string and matches the format.
+
+### Supported methods
+
+all, any?, blank?, count, delete, delete_all, destroy, destroy_all, each, empty?, except, exists?, find, find_by, 
+find_by!, find_each, find_in_batches, first, first!, first_or_create, first_or_initialize, ids, last, limit, load, 
+many?, offset, only, order, pluck, reorder, reverse_order, select, size, take, take!, to_a, to_sql, and where.
+        
+We also added `page(page, per_page)`, which translate into `offset((page-1)*per_page).limit(per_page)`.
+
+
+## Configuration Options
 
 ```ruby
 PostJson.setup "people" do |collection|
@@ -144,14 +166,7 @@ PostJson.setup "people" do |collection|
 end
 ```
 
-#### All of the following methods are supported
-
-all, any?, blank?, count, delete, delete_all, destroy, destroy_all, each, empty?, except, exists?, find, find_by, 
-find_by!, find_each, find_in_batches, first, first!, first_or_create, first_or_initialize, ids, last, limit, load, 
-many?, offset, only, order, pluck, reorder, reverse_order, select, size, take, take!, to_a, to_sql, and where.
-        
-We also added `page(page, per_page)`, which translate into `offset((page-1)*per_page).limit(per_page)`.
-
+For a Rails project this configuration could go in an initializer (`config/initializers/post_json.rb`).
 
 ## Performance
 
@@ -163,7 +178,7 @@ test_model = PostJson::Collection["test"]
 content = test_model.last.content
         
 result = test_model.where(content: content).count
-# Rails debug tells me the duration was 975.5ms
+# Rails debug duration was 975.5ms
 ```
 
 The duration was above 50ms as you can see.
@@ -174,7 +189,7 @@ Now lets see how the performance will be on the second and future queries using
 
 ```ruby
 result = test_model.where(content: content).count
-# Rails debug tells me the duration was 1.5ms
+# Rails debug duration was 1.5ms
 ```
 
 It shows PostgreSQL as a document database combined with indexing has great performance out of the box.
@@ -183,45 +198,46 @@ See the next section about "Dynamic Indexes" for details.
 
 ## Dynamic Indexes
 
-Most applications do the same queries over and over again. This is why we think it is useful, if PostJson create indexes on slow queries.
+PostJson will measure the duration of each `SELECT` query and instruct PostgreSQL to create an index, 
+if the query duration is above a specified threshold. This feature is called `Dynamic Index`. Since most 
+applications perform the same queries over and over again we think you'll find this useful.
 
-So we have created a feature we call `Dynamic Index`. It will automatically create indexes on slow queries, 
-so queries speed up considerably.
+Each collection (like `PostJson::Collection["people"]` above) has two index attributes:
 
-PostJson will measure the duration of each `SELECT` query and instruct PostgreSQL to create an Index, 
-if the query duration is above a specified threshold.
+* **use_dynamic_index** (default: true) 
+* **create_dynamic_index_milliseconds_threshold** (default: 50)
 
-Each collection (like PostJson::Collection["people"]) have attribute `use_dynamic_index` (which is true by default) and 
-attribute `create_dynamic_index_milliseconds_threshold` (which is 50 by default).
+### Example
 
-Lets say that you execute the following query and the duration is above the threshold of 50 milliseconds:
+```ruby
+PostJson::Collection["people"].where(name: "Jacob").count
 
-`PostJson::Collection["people"].where(name: "Jacob").count`
+# => query duration > 50ms
+```
 
-PostJson will create (unless it already exists) an Index on `name` behind the scenes. The next time 
-you execute a query with `name` the performance will be much improved.
+PostJson will check for an index on `name` and create it if it doesn't exist.
 
-You can adjust the settings:
+### Index configuration
 
 ```ruby
 class Person < PostJson::Collection["people"]
   self.create_dynamic_index_milliseconds_threshold = 75
 end
+```
 
-# Or you can do:
+or:
 
+```ruby
 PostJson::Collection["people"].create_dynamic_index_milliseconds_threshold = 75
-
-# Now indexes are only created if queries are slower than 75 milliseconds.
 ```
 
-You might already know this about User Interfaces, but it is usual considered good practice if auto-complete responses are served to the user within 100 milliseconds. Other results are usual okay within 500 milliseconds. So leave room for application processing and network delay.
+### WARNING
 
-Do not set create_dynamic_index_milliseconds_threshold too low as PostJson will try to create an index for every query. Like a threshold of 1 millisecond will be less than the duration of almost all queries.
+Do not set the dynamic index threshold too low as PostJson will try to create an index for every query. A threshold of 1 millisecond would be less than the duration of almost all queries.
 
 ## Primary Keys
 
-PostJson assign UUID as primary key (id):
+PostJson assigns UUID as primary key (id):
 
 ```ruby
 me = Person.create(name: "Jacob")
@@ -230,13 +246,13 @@ puts me.id
 # => "297a2500-a456-459b-b3e9-e876f59602c2"
 ```
 
-But you also set the primary key yourself:
+or you can set it directly:
 
 ```ruby
 john_doe = Person.create(id: "John Doe")
 ```
 
-Notice the primary key is downcased when doing a query or finding records:
+The primary key is downcased when doing a query or finding records:
 
 ```ruby
 found = Person.where(id: "JOhN DoE").first

data/lib/post_json/base.rb

@@ -110,15 +110,15 @@ module PostJson
     def __doc__body_convert_attribute_type(attribute_name, value)
       case value
       when /^[0-9]{4}-[0-1][0-9]-[0-3][0-9]T[0-2][0-9]:[0-5][0-9]:[0-5][0-9]\.[0-9]{3}Z$/
-        Time.parse(value).in_time_zone
+        Time.zone.parse(value)
       when Hash
         value.inject(HashWithIndifferentAccess.new) do |result, (key, value)|
-          result[key] = convert_document_attribute_type("#{attribute_name}.#{key}", value)
+          result[key] = __doc__body_convert_attribute_type("#{attribute_name}.#{key}", value)
           result
         end
       when Array
         value.map.with_index do |array_value, index|
-          convert_document_attribute_type("#{attribute_name}[#{index}]", array_value)
+          __doc__body_convert_attribute_type("#{attribute_name}[#{index}]", array_value)
         end
       else
         value
@@ -173,11 +173,11 @@ module PostJson
                           method_name
                         end
 
-      if attribute_name.in?(attribute_names) == false
+      if attribute_name.in?(attribute_names) || self.class.column_names.include?(attribute_name) || super_respond_to?(attribute_name.to_sym)
+        super
+      else
         self.class.define_attribute_accessor(attribute_name)
         send(method_symbol, *args)
-      else
-        super
       end
     end
 
@@ -253,6 +253,54 @@ module PostJson
           end
         RUBY
       end
+
+      def convert_attribute_value_before_save(primary_key, selector, value)
+        case value
+        when Time
+          value.in_time_zone
+        when DateTime
+          value.to_time.in_time_zone
+        else
+          value
+        end
+      end
+
+      def convert_document_hash_before_save(primary_key, document_hash, prefix = nil)
+        if document_hash
+          document_hash.inject(HashWithIndifferentAccess.new) do |result_hash, (key, value)|
+            selector =  if prefix
+                          "#{prefix}.#{key}"
+                        else
+                          key
+                        end
+            case value
+            when Hash
+              result_hash[key] = convert_document_hash_before_save(primary_key, value, selector)
+            when Array
+              result_hash[key] = convert_document_array_before_save(primary_key, value, selector)
+            else
+              result_hash[key] = convert_attribute_value_before_save(primary_key, selector, value)
+            end
+            result_hash
+          end
+        end
+      end
+
+      def convert_document_array_before_save(primary_key, document_array, prefix = nil)
+        if document_array
+          document_array.map.with_index do |value, index|
+            selector = "#{prefix}[#{index}]"
+            case value
+            when Hash
+              convert_document_hash_before_save(primary_key, value, selector)
+            when Array
+              convert_document_array_before_save(primary_key, value, selector)
+            else
+              convert_attribute_value_before_save(primary_key, selector, value)
+            end
+          end
+        end
+      end
     end
 
   protected
@@ -280,10 +328,11 @@ module PostJson
       end
 
       if self.class.persisted_settings.use_timestamps
-        __local__current_time = Time.zone.now.strftime('%Y-%m-%dT%H:%M:%S.%LZ')
+        __local__current_time = Time.zone.now
         __doc__body_write_attribute(self.class.persisted_settings.created_at_attribute_name, __local__current_time)
         __doc__body_write_attribute(self.class.persisted_settings.updated_at_attribute_name, __local__current_time)
       end
+
       super
     end
 
@@ -302,10 +351,20 @@ module PostJson
       end
 
       if self.class.persisted_settings.use_timestamps && __doc__body_attribute_changed?(self.class.persisted_settings.updated_at_attribute_name)
-        __local__current_time = Time.zone.now.strftime('%Y-%m-%dT%H:%M:%S.%LZ')
+        __local__current_time = Time.zone.now
         __doc__body_write_attribute(self.class.persisted_settings.updated_at_attribute_name, __local__current_time)
       end
       super
     end
+
+    def typecasted_attribute_value(name)
+      result = super
+      name = name.to_s
+      if name == '__doc__body'
+        self.class.convert_document_hash_before_save(self[self.primary_key], result)
+      else
+        result
+      end
+    end
   end
 end 

data/lib/post_json/version.rb

@@ -1,3 +1,3 @@
 module PostJson
-  VERSION = "1.0.11"
+  VERSION = "1.0.12"
 end

data/spec/models/base_spec.rb

@@ -433,4 +433,52 @@ describe "Base model" do
       it { subject.find("John").age.should == 25 }
     end
   end
-end
+
+  context "dates" do
+    let(:time) { Time.now }
+    let(:time_in_zone) { time.in_time_zone }
+    let(:date_time) { time.to_datetime }
+    let(:time_result) { Time.parse(time_in_zone.strftime('%Y-%m-%dT%H:%M:%S.%LZ')) }
+    let(:time_hash) { { 'time' => time, 'time_in_zone' => time_in_zone, 'date_time' => date_time } }
+    let(:time_array) { [time, time_in_zone, date_time] }
+    let(:record) { PostJson::Collection["dates"].new(time: time, time_in_zone: time_in_zone, date_time: date_time, time_hash: time_hash, time_array: time_array) }
+
+    context "before save" do
+      subject { record }
+
+      its(:time) { should == time }
+      its(:time_in_zone) { should == time_in_zone }
+      its(:date_time) { should == date_time }
+      its(:time_hash) { should == time_hash }
+      its(:time_array) { should == time_array }
+    end
+
+    context "after save" do
+      subject { record }
+
+      before do
+        subject.save!
+      end
+
+      its(:time) { should == time }
+      its(:time_in_zone) { should == time_in_zone }
+      its(:date_time) { should == date_time }
+      its(:time_hash) { should == time_hash }
+      its(:time_array) { should == time_array }
+
+      context "and reload" do
+        
+
+        before do
+          subject.reload
+        end
+
+        its(:time) { should == time_result }
+        its(:time_in_zone) { should == time_result }
+        its(:date_time) { should == time_result }
+        its(:time_hash) { should == { 'time' => time_result, 'time_in_zone' => time_result, 'date_time' => time_result } }
+        its(:time_array) { should == [time_result]*3 }
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: post_json
 version: !ruby/object:Gem::Version
-  version: 1.0.11
+  version: 1.0.12
 platform: ruby
 authors:
 - Jacob Madsen and Martin Thoegersen