Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Object mapper for anything that can read, write and delete data
Pull request Compare This branch is 296 commits ahead of cyruslopez:master.
Failed to load latest commit information.
examples Update readme and all examples.
gemfiles Fix gemfiles for rails 3.0 and 3.1
lib Release 0.13.2.
perf Remove logging. There is now a log subscriber. Use that instead.
.gitignore Ignore bin and vendor.
.travis.yml Remove support for 1.8 versions of ruby. Release 0.13.2.
Gemfile Fix rubygems deprecation in gemfile.
Guardfile Minor whitespace fix in guardfile.
LICENSE license to BSD Document instrumentation goodies in readme.
Rakefile Development updates.
toystore.gemspec Updates for adapter 0.7.0. Changed read multiple methods.


An object mapper for any adapter that can read, write, delete, and clear data.


The project comes with two main includes that you can use -- Toy::Object and Toy::Store.

Toy::Object comes with all the goods you need for plain old ruby objects -- attributes, dirty attribute tracking, equality, inheritance, serialization, cloning, logging and pretty inspecting.

Toy::Store includes Toy::Object and adds identity, persistence and querying through adapters, mass assignment, callbacks, validations and a few simple associations (lists and references).


First, join me in a whirlwind tour of Toy::Object.

class Person
  include Toy::Object

  attribute :name, String
  attribute :age,  Integer

# Pretty class inspecting
pp Person

john  = => 'John',  :age => 30)
steve = => 'Steve', :age => 31)

# Pretty inspecting
pp john

# Attribute dirty tracking = 'NEW NAME!'
pp john.changes       # {"name"=>["John", "NEW NAME!"], "age"=>[nil, 30]}
pp john.name_changed? # true

# Equality goodies
pp john.eql?(john)  # true
pp john.eql?(steve) # false
pp john == john     # true
pp john == steve    # false

# Cloning
pp john.clone

# Inheritance
class AwesomePerson < Person

pp Person.attributes.keys.sort          # ["age", "name"]
pp AwesomePerson.attributes.keys.sort   # ["age", "name", "type"]

# Serialization
puts john.to_json
puts john.to_xml

Ok, that was definitely awesome. Please continue on your personal journey to a blown mind (very similar to a beautiful mind).


Toy::Store is a unique bird that builds on top of Toy::Object. Below is a quick sample of what it can do.

class Person
  include Toy::Store

  attribute :name, String
  attribute :age,  Integer, :default => 0

# Persistence
john = Person.create(:name => 'John', :age => 30)
pp john
pp john.persisted?

# Mass Assignment Security
Person.attribute :role, String, :default => 'guest'
Person.attr_accessible :name, :age

person = => 'Hacker', :age => 13, :role => 'admin')
pp person.role # "guest"

# Querying
pp Person.read_multiple([])
pp'NOT HERE') # nil

begin!('NOT HERE')
rescue Toy::NotFound
  puts "Could not find person with id of 'NOT HERE'"

# Reloading
pp john.reload

# Callbacks
class Person
  before_create :add_fifty_to_age

  def add_fifty_to_age
    self.age += 50

pp Person.create(:age => 10).age # 60

# Validations
class Person
  validates_presence_of :name

person =
pp person.valid?        # false
pp person.errors[:name] # ["can't be blank"]

# Lists (array key stored as attribute)
class Skill
  include Toy::Store

  attribute :name, String
  attribute :truth, Boolean

class Person
  list :skills, Skill

john.skills = [Skill.create(:name => 'Programming', :truth => true)]
john.skills << Skill.create(:name => 'Mechanic', :truth => false)

pp == john.skill_ids # true

# References (think foreign keyish)
class Person
  reference :mom, Person

mom = Person.create(:name => 'Mum') = mom
pp john.reload.mom_id == # true

# Identity Map
Toy::IdentityMap.use do
  frank = Person.create(:name => 'Frank')

  pp                # true
  pp == frank.object_id # true

# Or you can turn it on globally
Toy::IdentityMap.enabled = true
frank = Person.create(:name => 'Frank')

pp                # true
pp == frank.object_id # true

# All persistence runs through an adapter.
# All of the above examples used the default in-memory adapter.
# Looks something like this:
Person.adapter :memory, {}

puts "Adapter: #{Person.adapter.inspect}"

# You can make a new adapter to your awesome new/old data store
Adapter.define(:append_only_array) do
  def read(key)
    if (record = client.reverse.detect { |row| row[0] == key })

  def write(key, value)
    client << [key, value]

  def delete(key)
    client.delete_if { |row| row[0] == key }

  def clear

client = []
Person.adapter :append_only_array, client

pp "Client: #{Person.adapter.client.equal?(client)}"

person = Person.create(:name => 'Phil', :age => 55)
person.age = 56

pp client

pp # Phil with age 56

If that doesn't excite you, nothing will. At this point, you are probably wishing for more.

Luckily, there is an entire directory full of examples and I created a few power user guides, which I will kindly link next.


ToyStore comes with a log subscriber and automatic metriks instrumentation. By default these work with ActiveSupport::Notifications, but only require the pieces of ActiveSupport that are needed and only do so if you actually attempt to require the instrumentation files listed below.

To use the log subscriber:

# Gemfile
gem 'activesupport'

# config/initializers/toystore.rb (or wherever you want it)
require 'toy/instrumentation/log_subscriber'

To use the metriks instrumentation:

# Gemfile
gem 'activesupport'
gem 'metriks'

# config/initializers/toystore.rb (or wherever you want it)
require 'toy/instrumentation/metriks'

ToyStore Power User Guides


As of 0.8.3, I started keeping a changelog. All significant updates will be summarized there.


  • Rails 3.0., 3.1., 3.2.*, Sinatra, etc. No Rails 2 (because it uses Active Model).
  • Ruby 1.9.3 only

Mailing List!forum/toystoreadapter


  • Fork the project.
  • Make your feature addition or bug fix in a topic branch.
  • Add tests for it. This is important so we don't break it in a future version unintentionally.
  • Commit, do not mess with rakefile, version, or changelog. (if you want to have your own version, that is fine, but bump version in a commit by itself so we can ignore when we pull)
  • Send a pull request.
Something went wrong with that request. Please try again.