Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

some review feedback.

  • Loading branch information...
commit 7a35e8986f57b35181d1edf97f8ded1cc467cc03 1 parent e7f4af7
@robey authored
Showing with 28 additions and 24 deletions.
  1. +28 −24 docs/example.md
View
52 docs/example.md
@@ -4,6 +4,9 @@
The best way to get the feel of this library is probably through a simple
example. Let's say we'd like to build a small chat server, like redpanda.
+This example assumes you're familiar with the basic concepts of fauna, and
+have browsed the API.
+
## Promises
Fauna-js is written in coffeescript and uses the Q promises library, but
@@ -37,14 +40,14 @@ is finished, either by finding nuts, or because there was an error.
## Schema
-The first thing we need to do is define our schema. For the littlest chat
-server, we just need three models:
+The first thing we need to do is define our fauna object schema. For the
+littlest chat server, we just need three classes:
- users
- messages
- chat rooms
-Users already exist as a native model in fauna, but we'll create the other
+Users already exist as a native class in fauna, but we'll create the other
two. In addition, we need to define relationships between them.
- A message is written by a user.
@@ -81,29 +84,30 @@ class ChatRoom extends fauna.Class
@eventSet "messages"
```
-This defines a class `User` and marks it as a native fauna model, so it will
-live in the fauna namespace instead of being created as a user-defined class.
-`User` is usually the only class that needs this special treatment. We can
-add our own fields and references here, just like any other class, so we add
-a display name.
+User-defined classes live in the `classes/` namespace in fauna, so normally
+fauna-js will determine the fauna class name by converting the javascript
+class name to lowercase, adding an "s", and using the `classes/` namespace:
+`Message` becomes `classes/messages`. We've marked `User` as a native fauna
+class, so it will use the fauna built-in class `users` instead of creating a
+new user-defined class. But we can add our own fields and references here,
+just like any other class, so we add a display name.
`Message` has a text field for the message content, and a reference named
"author". Marking it as a reference lets fauna know that it's a reference to
another object in the database (usually with an identifier like
-`user/95183857239` or `classes/message/18374838271`). Usually, when
-responding to a query, fauna will helpfully look up these objects and fill
-them in, so that our response doesn't contain just the object id, but the
-whole object.
+`user/95183857239` or `classes/message/18374838271`). When responding to a
+query, fauna will helpfully look up these objects and fill them in, so that
+our response doesn't contain just the object id, but the whole object.
`ChatRoom` has a name field, and also an event set for holding messages. Event
-sets are like containers with history, but read the fauna documentation for
+sets are like containers with history -- but read the fauna documentation for
the finer points.
## Schema in javascript
The javascript syntax for creating new prototypes and calling static methods
-on them is a bit more opaque, and usually requires a helper library to define
-the "extends" function, but it will generally look like this:
+on them is a bit more opaque, and requires a helper library to define the
+"extends" function, but it will generally look like this:
```javascript
function User() {
@@ -137,15 +141,15 @@ var faunaClient = require('fauna-js').FaunaClient;
faunaClient.addPrototypes(User, Message, ChatRoom);
```
-Fauna authentication takes a few forms (again, read the fauna documentation,
-if you haven't already). Fauna-js knows which methods require which kind of
-authentication, so usually you can set authentication keys once, and the
-library will use the right kind of authentication for each call. If a fauna
-request can be authenticated multiple ways, fauna-js prefers to use a less-
-capable key first. For example, if a fauna operation can be done by either a
-user or publisher, then fauna-js will use a user token if one has been set,
-falling back to a publisher token otherwise. If a key of the right type hasn't
-been set, an exception will be thrown without bothering to talk to the server.
+Fauna authentication uses different types of tokens to grant different access
+levels. Fauna-js knows which API methods require which kind of authentication,
+so usually you can set authentication keys once, and the library will use the
+right kind of authentication for each call. If a fauna request can be
+authenticated multiple ways, fauna-js prefers to use a less- capable key
+first. For example, if a fauna operation can be done by either a user or
+publisher, then fauna-js will use a user token if one has been set, falling
+back to a publisher token otherwise. If a key of the right type hasn't been
+set, an exception will be thrown without bothering to talk to the server.
So, to set the publisher key, which is needed to define new classes:
Please sign in to comment.
Something went wrong with that request. Please try again.