Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jnunemaker/toystore

Object mapper for anything that can read, write and delete data
https://github.com/jnunemaker/toystore

Last synced: about 2 months ago
JSON representation

Object mapper for anything that can read, write and delete data

Awesome Lists containing this project

README 

        
# Toystore



An object mapper for any [adapter](https://github.com/jnunemaker/adapter) that can read, write, delete, and clear data.



## Examples



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).



### Toy::Object



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



```ruby

class Person

  include Toy::Object



  attribute :name, String

  attribute :age,  Integer

end



# Pretty class inspecting

pp Person



john  = Person.new(:name => 'John',  :age => 30)

steve = Person.new(:name => 'Steve', :age => 31)



# Pretty inspecting

pp john



# Attribute dirty tracking

john.name = '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

end



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



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



```ruby

class Person

  include Toy::Store



  attribute :name, String

  attribute :age,  Integer, :default => 0

end



# 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 = Person.new(:name => 'Hacker', :age => 13, :role => 'admin')

pp person.role # "guest"



# Querying

pp Person.read(john.id)

pp Person.read_multiple([john.id])

pp Person.read('NOT HERE') # nil



begin

  Person.read!('NOT HERE')

rescue Toy::NotFound

  puts "Could not find person with id of 'NOT HERE'"

end



# Reloading

pp john.reload



# Callbacks

class Person

  before_create :add_fifty_to_age



  def add_fifty_to_age

    self.age += 50

  end

end



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



# Validations

class Person

  validates_presence_of :name

end



person = Person.new

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

end



class Person

  list :skills, Skill

end



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

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



pp john.skills.map(&:id) == john.skill_ids # true



# References (think foreign keyish)

class Person

  reference :mom, Person

end



mom = Person.create(:name => 'Mum')

john.mom = mom

john.save

pp john.reload.mom_id == mom.id # true



# Identity Map

Toy::IdentityMap.use do

  frank = Person.create(:name => 'Frank')



  pp Person.read(frank.id).equal?(frank)                # true

  pp Person.read(frank.id).object_id == frank.object_id # true

end



# Or you can turn it on globally

Toy::IdentityMap.enabled = true

frank = Person.create(:name => 'Frank')



pp Person.read(frank.id).equal?(frank)                # true

pp Person.read(frank.id).object_id == 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 })

      record

    end

  end



  def write(key, value)

    client << [key, value]

    value

  end



  def delete(key)

    client.delete_if { |row| row[0] == key }

  end



  def clear

    client.clear

  end

end



client = []

Person.adapter :append_only_array, client



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



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

person.age = 56

person.save



pp client



pp Person.read(person.id) # 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](https://github.com/jnunemaker/toystore/tree/master/examples) and I created a few power user guides, which I will kindly link next.



## Instrumentation



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:



```ruby

# Gemfile

gem 'activesupport'



# config/initializers/toystore.rb (or wherever you want it)

require 'toy/instrumentation/log_subscriber'

```



To use the metriks instrumentation:



```ruby

# Gemfile

gem 'activesupport'

gem 'metriks'



# config/initializers/toystore.rb (or wherever you want it)

require 'toy/instrumentation/metriks'

```



## ToyStore Power User Guides



* [Wiki Home](https://github.com/jnunemaker/toystore/wiki)

* [Identity](https://github.com/jnunemaker/toystore/wiki/Identity)

* [Types](https://github.com/jnunemaker/toystore/wiki/Types)

* [Exceptions](https://github.com/jnunemaker/toystore/wiki/Exceptions)



## Changelog



As of 0.8.3, I started keeping a [changelog](https://github.com/jnunemaker/toystore/blob/master/Changelog.md). All significant updates will be summarized there.



## Compatibility



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

* Ruby 1.9.3 only



## Mailing List



https://groups.google.com/forum/#!forum/toystoreadapter



## Contributing



* 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.