Permalink
Browse files

start of updating readme.

  • Loading branch information...
1 parent e291bed commit f8301941783fc2f90ebda50dad9bc1c29bb4af86 @robey committed Apr 5, 2013
Showing with 83 additions and 44 deletions.
  1. +83 −44 README.md
View
127 README.md
@@ -16,67 +16,106 @@ All API calls use the standard Q futures library
The packaging assumes you use browserify, or something very similar.
-Usage
-=====
+## Usage
This library is currently incomplete, and only implements the features I need
for the redpanda project. I intend to end up with a complete implementation of
the fauna v1 API, so please file an issue or contact me (Twitter & email
below) if you have suggestions, bug reports, or patches.
-Fauna works with "classes" and "instances" which should map to "models" and
-"objects" in your app. To define a model, describe a schema with the fields
-you intend to store in the database, and mark each field as being data or a
-reference:
-```javascript
-fauna = require("fauna-js")
-
-Schema = {
- messages: {
- author: fauna.Reference,
- body: fauna.Data
- }
- users: {
- email: fauna.Data
- }
-}
+## Models
+
+Fauna works with "classes" and "instances" which should map to models and
+objects in your app.
+
+A model is a prototype that extends `fauna.Class`. For example, here's a model
+for a song in coffeescript:
+
+```coffeescript
+fauna = require 'fauna-js'
+
+class Song extends fauna.Class
+ @field "title", "rating"
+ @reference "artist"
```
-When decoding objects from the fauna servers, items with class "messages" will
-be decoded from a json object like this:
+The static call `@field` registers "title" and "rating" as fields in your
+javascript object that should be submerged into the 'data' JSON blob when
+storing an object in fauna.
+
+Similarly, `@reference` registers "artist" as a field that refers to another
+object stored in fauna. It will be stored by instance ID in the 'references'
+JSON blob. Fauna will usually follow references when fetching objects (at
+least one or two levels deep), so when reading a Song object, the "artist"
+field may contain another full object.
+
+The `@field` and `@reference` calls can be used as many times as you want
+within a single class, or you may list all the relevant fields on a single
+line (like above), Check out the fauna documentation for more details about
+the 'data' and 'references' fields on stored instances.
+
+The javascript equivalent of declaring a model class looks like this:
```javascript
-"classes/messages/29192553537470464": {
- "ref" : "classes/messages/29192553537470464",
- "class" : "classes/messages",
- "ts" : 1364099038540000,
- "references": {
- "author" : "users/29183911200292864"
- },
- "data" : {
- "body" : "meet me on bernal hill!"
- }
+var fauna = require('fauna-js');
+
+var extends = function(child, parent) {
+ child.prototype = new parent;
+ for (var key in parent) { child[key] = parent[key]; }
+}
+
+function Song() {
+ fauna.Class.apply(this, arguments);
}
+extends(Song, fauna.Class);
+
+Song.field("title", "rating");
+Song.reference("artist");
```
-to an object like this:
+The definition of "extends" is shown only for convenience -- you should use
+the subclass mechanism your framework uses.
-```javascript
-{
- meta: {
- id: "classes/messages/29192553537470464",
- className: "messages",
- ts: Sat Mar 23 2013 21:23:58 GMT-0700 (PDT)
- },
- author: {
- meta: { ... },
- email: "robey@example.com"
- },
- body: "meet me on bernal hill!"
-}
+The fauna tracking info for an object will be stored in a field named
+'_fauna'. The tracking info contains the instance id (as `id`), timestamp (as
+`ts`), and class name in the database (as `className`).
+
+```coffeescript
+console.log "Song title is '#{song.title}' (fauna id #{song._fauna.id})"
```
+The fauna class name can be inferred (the lowercase name of the model class,
+plus an 's') or declared explicitly with `@faunaClass`:
+
+```coffeescript
+class Song extends fauna.Class
+ @faunaClass "all_songs"
+```
+
+
+## Event sets
+
+Custom event sets can be declared on a model class with `@eventSet`:
+
+```coffeescript
+class Album extends fauna.Class
+ @eventSet "tracks"
+```
+
+This will create a special field 'tracks' on any Album object, which refers to
+an object with methods for manipulating the set. The methods are:
+
+- `add(object)`
+
+ foo
+
+
+
+
+
+
+
License
=======

0 comments on commit f830194

Please sign in to comment.