CouchSurfer - CouchDB ORM
Description
CouchSurfer is an extraction of CouchRest::Model from the excellent CouchRest gem by J. Chris Anderson. In addition, it provides association and validation methods.
Associations
CouchSurfer provides the following 4 association kinds:
belongs_tohas_many-
has_many :inline; and has_many :through
All association kinds take an optional :class_name option should you want your association to be named differently to the associated model.
class Page
…
belongs_to :owner, :class_name => :user
…
end
page = Page.create(…)
page.owner # returns an instance of user
The belongs_to associations accept two additional options - :view and query, enabling you to customise your associations to fit your needs. You must explicitly declare the view on the child model for associations to work
Example 1: basic
class User
…
has_many :pages
…
end
class Page
…
view_by :user_id
…
end
user = User.create(…)
10.times {Page.create(…, :user_id => user.id)}
user.pages
Example 2: with options
class Account
…
has_many :employees,
:class_name, :user,
:view => :by_account_id_and_email,
:query => lambda { {:startkey => [account_id, nil], :endkey => [account_id, {}]} }
…
end
class User
…
view_by :account_id, :email # see validation examples below
…
end
account = Acccount.create(…)
10.times {User.create(…, :account_id => acount.id)}
account.employees
Example 3: :inline
class User
…
has_many :tasks, :inline => true
…
end
class Task
…
view_by :user_id
…
end
user = User.create(…)
10.times {user.tasks << Task.new(…)}
user.save
user.tasks
Example 4: :through
class Account
…
has_many :projects,
:through => :memberships
…
end
class Membership
…
view_by :account_id
…
end
class Project
…
view_by :account_id, :email # see validation examples below
…
end
account = Acccount.create(…)
10.times do
p = Project.create(…)
Membership.create(…, :account_id => account.id, :project_id => p.id)
end
account.projects
Note on HasManyThrough
With reference to the above example, HasManyThrough works by retrieving all memberships associated with the account, collecting their ids and running a bulk retrieval on the Project.all view, which is implicitly created for all models and, as of 0.0.4, emits it's id (see CHANGELOG).
Caveats
- Sorting needs to be done client side
- The results do not contain any extra information that may be present on the ':through' model.
Validations
Validations, with the exception of validates_uniqueness_of, have been implemented using the Validatable gem.
Example
class Employee
include CouchSurfer::Model
include CouchSurfer::Associations
include CouchSurfer::Validations
key_accessor :email, :account_id
belongs_to :account
view_by :account_id, :email
view_by :name
validates_presence_of :name
validates_format_of :email,
:with => /\A([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})\Z/i
validates_length_of :postcode, :is => 7, :message => "not the correct length"
# Will use the Employee.by_name view with {:key => employee_instance.name}
validates_uniqueness_of :name
# Uses a custom view and key for uniqueness within a specific scope
validates_uniqueness_of :email,
:view => :by_account_id_and_email,
:query => lambda{ {:key => [account_id, email]} },
:message => "The email address for this account is taken"
end
Please check out the specs as well :)
Next
- Error handling
- association methods with arguments:
@account.projects(:limit => 2, :offset => 1)