Permalink

Comparing changes

Choose two branches to see what’s changed or to start a new pull request. If you need to, you can also .

Open a pull request

Create a new pull request by comparing changes across two branches. If you need to, you can also .
  • 3 commits
  • 1 file changed
  • 0 commit comments
  • 1 contributor
Showing with 65 additions and 18 deletions.
  1. +65 −18 README.md
View
@@ -7,17 +7,12 @@ events. Monarch is written in CoffeeScript, but can also be used from
JavaScript.
-## Defining Models
+## Defining Model Classes
Monarch associates model constructors with tables in an in-memory relational
-database, in the same way ActiveRecord associates a Ruby class with a table on a
-database server.
+database. On the surface, the API resembles ActiveRecord.
-### In CoffeeScript
-
-To define a record class in CoffeeScript, create a subclass of `Monarch.Record`,
-then call the `@extended` class method with a reference to the current class and
-define the table's schema by passing a hash to the `@columns` class method.
+To define a record class in CoffeeScript, create a subclass of `Monarch.Record`.
```coffeescript
class Blog extends Monarch.Record
@@ -27,15 +22,18 @@ class Blog extends Monarch.Record
userId: 'integer'
title: 'string'
createdAt: 'datetime'
+
+ @belongsTo 'user'
+ @hasMany 'posts'
+ @hasMany 'postComments', through: 'posts', className: 'Comment'
```
-### In JavaScript
+Until CoffeeScript offers an automatic `@extended` hook, you'll need to
+call `@extended` manually at the top of the class body. Next, call `@columns`
+with a hash of field-name/type pairs, and optionally call `@hasMany` and
+`@belongsTo` association methods. More on those later...
-To define a record class in JavaScript, first create a constructor, then pass it
-to the top-level `Monarch` function along with a hash of column definitions. It
-will automatically be setup as a subclass of `Monarch.Record`. The `Monarch`
-function returns your constructor, so class methods like `hasMany` can be called
-immediately in a method-chaining style. More on that later.
+### In JavaScript
```javascript
function() Blog {}
@@ -44,11 +42,18 @@ Monarch(Blog, {
userId: 'integer',
title: 'string',
createdAt: 'datetime'
-});
+})
+ .belongsTo('user')
+ .hasMany('posts')
+ .hasMany('postComments', { through: 'posts', className: 'Comment' });
```
-Unless otherwise noted, examples will be shown in CoffeeScript from here on out.
-
+To define a record class in JavaScript, first create a constructor, then pass it
+to the top-level `Monarch` function along with a hash of column definitions. It
+will automatically be setup as a subclass of `Monarch.Record`. The `Monarch`
+function returns your constructor, so other class methods can be called in a
+method-chaining style. Unless otherwise noted, examples will be shown in
+CoffeeScript from here on out.
## Loading Data
@@ -143,7 +148,7 @@ query. You can also think of a relation as a set of records. More precisely,
it's a declarative recipe for constructing a set of records based on the current
contents of the local repository.
-### Accessing and Iterating Over Records in a Relation
+### Accessing Records in a Relation
To retrieve a relation's records, call its `all` method. You can also iterate
over every record in the relation using `each` and `map`. For example:
@@ -378,4 +383,46 @@ suggestToFollow = rankedAuthors.difference(followedAuthors)
## Working with Records
+### Reading / Writing Field Values
+
+Field accessor methods are available on your records for every column defined
+on their class.
+
+```coffeescript
+blog = Blog.find(11)
+console.log "#{blog.title()} by #{blog.user().fullName()}
+
+# just like in jQuery, call field accessors with an argument to assign values
+blog.title("New Title")
+blog.save() # more on saving later
+```
+
+### Observing Record Updates
+
+In addition to observing collections of objects via relations, you can also
+observe individual records with `onUpdate`.
+
+```coffeescript
+blog.onUpdate (changeset) ->
+ if changeset.title
+ oldTitle = changeset.title.oldValue
+ newTitle = changeset.title.newValue
+ console.log "The blog title changed from #{oldValue} to #{newValue}"
+```
+
+`onUpdate` returns a subscription object. Call `destroy` on it when you are no
+longer interested in updates.
+
+```coffeescript
+subscription = blog.onUpdate -> ...
+
+# I don't care about updates any more
+subscription.destroy()
+```
+
+### Synthetic Columns
+
+### Associations
+
+### CRUD Operations

No commit comments for this range