README.md in active_model_cachers-2.0.3 vs README.md in active_model_cachers-2.1.0
- old
+ new
@@ -38,19 +38,36 @@
end
```
## Usage
+### Cache whatever you want by `cache_at` method
+
`cache_at(name, query = nil, options = {})`
-Specifie a cache on the model.
+Specify a cache on the model.
- name: the attribute name.
- query: how to get data on cache miss. It will be set automatically if the name match an association or an attribute.
- options: see [here](#options)
-## Cache whatever you want
+### Asscess the cached attributes
+The `cacher` is defined as `class method` and `instance method` of Model. You could call the method and get the cacher instance, e.g. `User.cacher` or `user.cacher`. An attribute will define a method on cacher, cached attributes are asscessable via it, e.g. `user.cacher.the_attribute_name`.
+
+
+### Basic Example
+```rb
+class User < ActiveRecord::Base
+ cache_at :something_you_want_to_cache, ->{ get_the_data_on_cache_miss }
+end
+
+user.cacher.something_you_want_to_cache
+```
+
+
+## Examples
+
### Example 1: Cache the number of active user
After specifying the name as `active_count` and how to get data when cache miss by lambda `User.active.count`.
You could access the cached data by calling `active_count` method on the cacher, `User.cacher`.
@@ -115,12 +132,36 @@
render_error if not current_user.cacher.email_valid?
```
It can also be accessed from instance cacher. But you have to set [`primary_key`](#primary_key), which is needed to know which attribute should be passed to the parameter.
-### Example 5: Clean the cache manually
+### Example 5: Store all data in hash
+Sometimes you may need to query multiple objects. Although the query results will be cached, the application still needs to query the cache server multiple times. If one communication take 0.1 ms, 1000 communications will take 100ms! For example:
+
+```rb
+class Skill < ActiveRecord::Base
+ cache_at :atk_power
+end
+
+# This will retrieve the data from cache servers multiple times.
+@attack = skill_ids.inject(0){|sum, id| sum + Skill.cacher_at(id).atk_power }
+```
+
+One of the solution is that you could store a lookup table into cache, so that only one cache object is stored and you can retrieve all of the needed data in one query.
+
+```rb
+class Skill < ActiveRecord::Base
+ cache_at :atk_powers, ->{ Skill.pluck(:id, :atk_power).to_h }, expire_by: 'Skill#atk_power'
+end
+
+# This will retrieve the data from cache servers only 1 times.
+@attack = skill_ids.inject(0){|sum, id| sum + Skill.cacher.atk_powers[id] }
+```
+
+### Example 6: Clean the cache manually
+
Sometimes it needs to maintain the cache manually. For example, after calling `update_all`, `delete_all` or `import` records without calling callbacks.
```rb
class User < ActiveRecord::Base
has_one :profile
@@ -128,17 +169,38 @@
end
# clean the cache by name
current_user.cacher.clean(:profile)
-# Or calling the clean_* method
+# or calling the clean_* method
current_user.cacher.clean_profile
# clean the cache without loading model
User.cacher_at(user_id).clean_profile
```
+### Example 7: Peek the data stored in cache
+
+If you just want to check the cached objects, but don't want it to load from database automatically when there is no cache. You could use `peek` method on `cacher`.
+
+```rb
+class User < ActiveRecord::Base
+ has_one :profile
+ cache_at :profile
+end
+
+# peek the cache by name
+current_user.cacher.peek(:profile)
+
+# or calling the peek_* method
+current_user.cacher.peek_profile
+
+# peek the cache without loading model
+User.cacher_at(user_id).peek_profile
+```
+
+
## Smart Caching
### Multi-level Cache
There is multi-level cache in order to make the speed of data access go faster.
@@ -182,20 +244,32 @@
```rb
class User < ActiveRecord::Base
cache_self
end
-@user = User.cacher_at(user_id).self
+@user = User.cacher.find_by(id: user_id)
+
+# peek cache
+User.cacher.peek_by(id: user_id)
+
+# clean cache
+User.cacher.clean_by(id: user_id)
```
Also support caching self by other columns.
```rb
class User < ActiveRecord::Base
- cache_self, by: :account
+ cache_self by: :account
end
-@user = User.cacher_at('khiav').self_by_account
+@user = User.cacher.find_by(account: 'khiav')
+
+# peek cache
+User.cacher.peek_by(account: 'khiav')
+
+# clean cache
+User.cacher.clean_by(account: 'khiav')
```
### Caching Attributes
```rb
@@ -248,7 +322,19 @@
This option is needed to know which attribute should be passed to the parameter when you are using instance cacher. For example, if a query, named `email_valid?`, uses `user.email` as parameter, and you call it from instance: `user.cacher.email_valid?`. You need to tell it to pass `user.email` instead of `user.id` as the argument.
- Default value is `:id`
+## Development
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/khiav223577/active_model_cachers. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).