ShyCouch

ShyCouch

Ruby library for CouchDB providing a native objects layer, abstracting the HTTP interface.

It's for those who think that ActiveRecord and even Django's lovely ORMs don't get you far enough away from SQL. It's for people who want to make funky websites and self-managed / self-hosted web services, not like, you know, Define Business Requirements And Cardinalities or whatever.

Soon it'll have support for native Ruby views on the view server. In the meantime, views are written inline in Ruby and then parsed in JavaScript using ShyRubyJS. ShyRubyJS is not very mature, so for anything complex you should write them as inline JavaScript.

If anyone can think of a good semantics to prevent confusion between Couch views and the views in an MVC framework that might use this library, I'd love to hear it.

Usage

Create a database object, automatically initializing the database on the CouchDB instance if it doesn't exist

couch_settings = {
  "db"=> {
      "host" => "localhost",
      "port" => 5984,
      "name" => "food-app",
      "user" => "myUsername",
      "password" => "myPassword"
    }
}

@couchdb = ShyCouch::getDB(couch_settings)

Create a design document and give it some views.

Note: soon there'll be a syntax for having default HTTP query options (e.g. ?include_docs=true) on particular views.

design = ShyCouch::Data::Design.new :food, {:push_to => @couchdb}

view1 = ShyCouch::Data::View :all_recipes do
	map do
		emit(doc._id, null) if doc.kind == "Recipe"
	end
end
view2 = ShyCouch::Data::View :recipe_count do
	map do
		emit(doc._id, null) if doc.kind == "Recipe"
	end
	reduce do
		return sum(values)
	end
end

design.add_views [view1, view2]
design.push!

Subclass the CouchDocument class to represent your data types:

class Recipe < ShyCouch::Data::CouchDocument
	needs :name
	needs :ingredients
	needs :difficulty
	suggests :cost
end

Do whatever application logic, and then push your documents (soon you'll be able to define the default :push_to for the whole class):

recipe_data = {
	:name = "tuesday snack"
	:ingredients => "sawdust, apples",
	:difficulty => "not hard enough needs more boss fights",
	:cost => "cheap eh"
}
recipe = Recipe.new(:push_to => @couchdb, :data => recipe_data)
recipe.push!

Note the :needs and :suggests syntax when you define a class. Your documents will always raise an error if you try to push without something that's in :needs but you can override :suggests:

recipe_data = {
	:name => "soup for guests"
	:ingredients => "king rat, chicken stock"
	:difficult => "extr3m3"
}
recipe = Recipe.new(:push_to => @couchdb, :data => recipe_data)
recipe.push! :ignore_suggests => :cost

Class inheritence maintains document validation:

class FascistRecipe < CouchDocument
	needs :who_is_allowed_to_cook_it
end
recipe_data = {
  :who_is_allowed_to_cook_it => "alan"
}
recipe = Recipe.new :push_to => @couchdb
recipe.push!
>>>ShyCouch::DocumentValidationError: Document Missing required fields: [:name, :ingredients, :difficulty]

You can query your views:

recipes = @couchdb.design(:food).query_view(:all_recipes)

Querying your views will return the raw view results as a hash keyed by whatever the view was keyed by.

If you call it like this, though:

recipes = @couchdb.design(:food).query_view(:all_recipes, :include_docs => true)

Then you'll get your view results as a ShyCouch::Data::DocumentCollection object, where each object is an instance of ShyCouch::Data::CouchDocument.