ohm_util 0.1

data/benchmarks/common.rb

@@ -0,0 +1,28 @@
+require "bench"
+require_relative "../lib/ohm"
+
+Ohm.redis = Redic.new("redis://127.0.0.1:6379/15")
+Ohm.flush
+
+class Event < Ohm::Model
+  attribute :name
+  attribute :location
+
+  index :name
+  index :location
+end
+
+class Sequence
+  def initialize
+    @value = 0
+  end
+
+  def succ!
+    Thread.exclusive { @value += 1 }
+  end
+
+  def self.[](name)
+    @@sequences ||= Hash.new { |hash, key| hash[key] = Sequence.new }
+    @@sequences[name]
+  end
+end

data/benchmarks/create.rb

@@ -0,0 +1,21 @@
+require_relative "common"
+
+benchmark "Create Events" do
+  i = Sequence[:events].succ!
+
+  Event.create(:name => "Redis Meetup #{i}", :location => "London #{i}")
+end
+
+benchmark "Find by indexed attribute" do
+  Event.find(:name => "Redis Meetup 1").first
+end
+
+benchmark "Mass update" do
+  Event[1].update(:name => "Redis Meetup II")
+end
+
+benchmark "Load events" do
+  Event[1].name
+end
+
+run 5000

data/benchmarks/delete.rb

@@ -0,0 +1,13 @@
+require_relative "common"
+
+1000.times do |i|
+  Event.create(:name => "Redis Meetup #{i}", :location => "At my place")
+end
+
+benchmark "Delete event" do
+  Event.all.each do |event|
+    event.delete
+  end
+end
+
+run 1

data/examples/activity-feed.rb

@@ -0,0 +1,157 @@
+### Building an activity feed
+
+#### Common solutions using a relational design
+
+# When faced with this application requirement, the most common approach by
+# far have been to create an *activities* table, and rows in this table would
+# reference a *user*. Activities would typically be generated for each
+# follower (or friend) when a certain user performs an action, like posting a
+# new status update.
+
+#### Problems
+
+# The biggest issue with this design, is that the *activities* table will
+# quickly get very huge, at which point you would need to shard it on
+# *user_id*. Also, inserting thousands of entries per second would quickly
+# bring your database to its knees.
+
+#### Ohm Solution
+
+# As always we need to require `Ohm`.
+require "ohm"
+
+# We create a `User` class, with a `set` for all the other users he
+# would be `following`, and another `set` for all his `followers`.
+class User < Ohm::Model
+  set :followers, User
+  set :following, User
+
+  # Because a `User` literally has a `list` of activities, using a Redis
+  # `list` to model the activities would be a good choice. We default to
+  # getting the first 100 activities, and use
+  # [lrange](http://redis.io/commands/lrange) directly.
+  def activities(start = 0, limit = 100)
+    redis.call 'LRANGE', key[:activities], start, start + limit
+  end
+
+  # Broadcasting a message to all the `followers` of a user would simply
+  # be prepending the message for each if his `followers`. We also use
+  # the Redis command
+  # [lpush](http://redis.io/commands/lpush) directly.
+  def broadcast(str)
+    followers.each do |user|
+      redis.call 'LPUSH', user.key[:activities], str
+    end
+  end
+
+  # Given that *Jane* wants to follow *John*, we simply do the following
+  # steps:
+  #
+  # 1. *John* is added to *Jane*'s `following` list.
+  # 2. *Jane* is added to *John*'s `followers` list.
+  def follow(other)
+    following << other
+    other.followers << self
+  end
+end
+
+
+#### Testing
+
+# We'll use cutest for our testing framework.
+require "cutest"
+
+# The database is flushed before each test.
+prepare { Ohm.flush }
+
+# We define two users, `john` and `jane`, and yield them so all
+# other tests are given access to these 2 users.
+setup do
+  john = User.create
+  jane = User.create
+
+  [john, jane]
+end
+
+# Let's verify our model for `follow`. When `jane` follows `john`,
+# the following conditions should hold:
+#
+# 1. The followers list of `john` is comprised *only* of `jane`.
+# 2. The list of users `jane` is following is comprised *only* of `john`.
+test "jane following john" do |john, jane|
+  jane.follow(john)
+
+  assert_equal [john], jane.following.to_a
+  assert_equal [jane], john.followers.to_a
+end
+
+# Broadcasting a message should simply notify all the followers of the
+# `broadcaster`.
+test "john broadcasting a message" do |john, jane|
+  jane.follow(john)
+  john.broadcast("Learning about Redis and Ohm")
+
+  assert jane.activities.include?("Learning about Redis and Ohm")
+end
+
+#### Total Denormalization: Adding HTML
+
+# This may be a real edge case design decision, but for some scenarios this
+# may work. The beauty of this solution is that you only have to generate the
+# output once, and successive refreshes of the end user will help you save
+# some CPU cycles.
+#
+# This example of course assumes that the code that generates this does all
+# the conditional checks (possibly changing the point of view like *Me:*
+# instead of *John says:*).
+test "broadcasting the html directly" do |john, jane|
+  jane.follow(john)
+
+  snippet = '<a href="/1">John</a> says: How\'s it going ' +
+            '<a href="/user/2">jane</a>?'
+
+  john.broadcast(snippet)
+
+  assert jane.activities.include?(snippet)
+end
+
+#### Saving Space
+
+# In most cases, users don't really care about keeping their entire activity
+# history. This application requirement would be fairly trivial to implement.
+
+# Let's reopen our `User` class and define a new broadcast method.
+class User
+  # We define a constant where we set the maximum number of activity entries.
+  MAX = 10
+
+  # Using `MAX` as the reference, we truncate the activities feed using
+  # [ltrim](http://redis.io/commands/ltrim).
+  def broadcast(str)
+    followers.each do |user|
+      redis.call 'LPUSH', user.key[:activities], str
+      redis.call 'LTRIM', user.key[:activities], 0, MAX - 1
+    end
+  end
+end
+
+# Now let's verify that this new behavior is enforced.
+test "pushing 11 activities maintains the list to 10" do |john, jane|
+  jane.follow(john)
+
+  11.times { john.broadcast("Flooding your feed!") }
+
+  assert 10 == jane.activities.size
+end
+
+
+#### Conclusion
+
+# As you can see, choosing a more straightforward approach (in this case,
+# actually having a list per user, instead of maintaining a separate
+# `activities` table) will greatly simplify the design of your system.
+#
+# As a final note, keep in mind that the Ohm solution would still need
+# sharding for large datasets, but that would be again trivial to implement
+# using [redis-rb](http://github.com/redis/redis-rb)'s distributed support
+# and sharding it against the *user_id*.

data/examples/chaining.rb

@@ -0,0 +1,162 @@
+### Chaining Ohm Sets
+
+#### Doing the straight forward approach
+
+# Let's design our example around the following requirements:
+#
+# 1. a `User` has many orders.
+# 2. an  `Order` can be pending, authorized or captured.
+# 3. a `Product` is referenced by an `Order`.
+
+#### Doing it the normal way
+
+# Let's first require `Ohm`.
+require "ohm"
+
+# A `User` has a `collection` of *orders*. Note that a collection
+# is actually just a convenience, which implemented simply will look like:
+#
+#   def orders
+#     Order.find(user_id: self.id)
+#   end
+#
+class User < Ohm::Model
+  collection :orders, :Order
+end
+
+# The product for our purposes will only contain a name.
+class Product < Ohm::Model
+  attribute :name
+end
+
+# We define an `Order` with just a single `attribute` called `state`, and
+# also add an `index` so we can search an order given its state.
+#
+# The `reference` to the `User` is actually required for the `collection`
+# of *orders* in the `User` declared above, because the `reference` defines
+# an index called `:user_id`.
+#
+# We also define a `reference` to a `Product`.
+class Order < Ohm::Model
+  attribute :state
+  index :state
+
+  reference :user, User
+  reference :product, Product
+end
+
+##### Testing what we have so far.
+
+# For the purposes of this tutorial, we'll use cutest for our test framework.
+require "cutest"
+
+# Make sure that every run of our test suite has a clean Redis instance.
+prepare { Ohm.flush }
+
+# Let's create a *user*, a *pending*, *authorized* and a captured order.
+# We also create two products named *iPod* and *iPad*.
+setup do
+  @user = User.create
+
+  @ipod = Product.create(name: "iPod")
+  @ipad = Product.create(name: "iPad")
+
+  @pending =    Order.create(user: @user, state: "pending",
+                             product: @ipod)
+  @authorized = Order.create(user: @user, state: "authorized",
+                             product: @ipad)
+  @captured =   Order.create(user: @user, state: "captured",
+                             product: @ipad)
+end
+
+# Now let's try and grab all pending orders, and also pending
+# *iPad* and *iPod* ones.
+test "finding pending orders" do
+  assert @user.orders.find(state: "pending").include?(@pending)
+
+  assert @user.orders.find(state: "pending",
+                           product_id: @ipod.id).include?(@pending)
+
+  assert @user.orders.find(state: "pending",
+                           product_id: @ipad.id).empty?
+end
+
+# Now we try and find captured and/or authorized orders.
+test "finding authorized and/or captured orders" do
+  assert @user.orders.find(state: "authorized").include?(@authorized)
+  assert @user.orders.find(state: "captured").include?(@captured)
+
+  results = @user.orders.find(state: "authorized").union(state: "captured")
+
+  assert results.include?(@authorized)
+  assert results.include?(@captured)
+end
+
+#### Creating shortcuts
+
+# You can of course define methods to make that code more readable.
+class User < Ohm::Model
+  def authorized_orders
+    orders.find(state: "authorized")
+  end
+
+  def captured_orders
+    orders.find(state: "captured")
+  end
+end
+
+# And we can now test these new methods.
+test "finding authorized and/or captured orders" do
+  assert @user.authorized_orders.include?(@authorized)
+  assert @user.captured_orders.include?(@captured)
+end
+
+# In most cases this is fine, but if you want to have a little fun,
+# then we can play around with some chainability using scopes.
+
+# Let's require `ohm-contrib`, which we will be using for scopes.
+require "ohm/contrib"
+
+# Include `Ohm::Scope` module and desired scopes.
+class Order
+  include Ohm::Scope
+
+  scope do
+    def pending
+      find(state: "pending")
+    end
+
+    def authorized
+      find(state: "authorized")
+    end
+
+    def captured
+      find(state: "captured")
+    end
+
+    def accepted
+      find(state: "authorized").union(state: "captured")
+    end
+  end
+end
+
+# Ok! Let's put all of that chaining code to good use.
+test "finding pending orders using a chainable style" do
+  assert @user.orders.pending.include?(@pending)
+  assert @user.orders.pending.find(product_id: @ipod.id).include?(@pending)
+
+  assert @user.orders.pending.find(product_id: @ipad.id).empty?
+end
+
+test "finding authorized and/or captured orders using a chainable style" do
+  assert @user.orders.authorized.include?(@authorized)
+  assert @user.orders.captured.include?(@captured)
+
+  assert @user.orders.accepted.include?(@authorized)
+  assert @user.orders.accepted.include?(@captured)
+
+  accepted = @user.orders.accepted
+
+  assert accepted.find(product_id: @ipad.id).include?(@authorized)
+  assert accepted.find(product_id: @ipad.id).include?(@captured)
+end

data/examples/json-hash.rb

@@ -0,0 +1,75 @@
+### Make Peace wih JSON and Hash
+
+#### Why do I care?
+
+# If you've ever needed to build an AJAX route handler, you may have noticed
+# the prevalence of the design pattern where you return a JSON response.
+#
+#     on get, "comments" do
+#       res.write Comment.all.to_json
+#     end
+#
+# `Ohm` helps you here by providing sensible defaults. It's not very popular,
+# but `Ohm` actually has a `to_hash` method.
+
+# Let's start by requiring `ohm` and `ohm/json`.
+require "ohm"
+require "ohm/json"
+
+# Here we define our `Post` model with just a single `attribute` called `title`.
+class Post < Ohm::Model
+  attribute :title
+end
+
+# Now let's load the test framework `cutest` to test our code.
+require "cutest"
+
+# We also call `Ohm.flush` for each test run.
+prepare { Ohm.flush }
+
+# When we successfully create a `Post`, we can see that it returns
+# only the *id* and its value in the hash.
+test "hash representation when created" do
+  post = Post.create(title: "my post")
+
+  assert_equal Hash[id: post.id], post.to_hash
+end
+
+# The JSON representation is actually just `post.to_hash.to_json`, so the
+# same result, only in JSON, is returned.
+test "json representation when created" do
+  post = Post.create(title: "my post")
+
+  assert_equal "{\"id\":\"#{post.id}\"}", post.to_json
+end
+
+#### Whitelisted approach
+
+# Unlike other frameworks which dumps out all attributes by default,
+# `Ohm` favors a whitelisted approach where you have to explicitly
+# declare which attributes you want.
+#
+# By default, only `:id` will be available if the model is persisted.
+
+# Let's re-open our Post class, and add a `to_hash` method.
+class Post
+  def to_hash
+    super.merge(title: title)
+  end
+end
+
+# Now, let's test that the title is in fact part of `to_hash`.
+test "customized to_hash" do
+  post = Post.create(title: "Override FTW?")
+
+  assert_equal Hash[id: post.id, title: post.title], post.to_hash
+end
+
+#### Conclusion
+
+# Ohm has a lot of neat intricacies like this. Some of the things to keep
+# in mind from this tutorial would be:
+#
+# 1. `Ohm` doesn't assume too much about your needs.
+# 2. If you need a customized version, you can always define it yourself.
+# 3. Customization is easy using basic OOP principles.