Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Updated README to not suck as much.

  • Loading branch information...
commit ffa879191657adbec7d01501f08729b90a7af189 1 parent 87a8360
@bcoe authored
Showing with 169 additions and 24 deletions.
  1. +20 −0 LICENSE.txt
  2. +149 −0 README.markdown
  3. +0 −24 README.textile
View
20 LICENSE.txt
@@ -0,0 +1,20 @@
+Copyright (c) 2011 Attachments.me
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
View
149 README.markdown
@@ -0,0 +1,149 @@
+Endtable
+========
+
+Endtable is an experimental ORM built on top of Node.js and CouchDB.
+
+The concept? long-lived, self-monitoring, objects that persist only periodically as modifications are made to them.
+
+This paradigm reduces the frequency with which writes are made to the database, and works well for domains such as games.
+
+The Engine Object
+-----------------
+
+A single engine object is instantiated and passed as a dependency to an Endtable Class:
+
+```javascript
+var engine = new endtable.Engine({
+ database: 'people_example',
+ host: 'localhost',
+ user: '',
+ password: '',
+ errorCallback: function(error) {
+ // When views aren't found they raise a warning.
+ sys.puts(JSON.stringify(error));
+ }
+});
+
+The Error Callback
+------------------
+
+Errors that occur in Endtable are propagated up to the _errorCallback_ passed to the Engine's constructor.
+
+Error objects provide the following information:
+
+* _error.error_ the raw error message.
+* _error.reason_ the reason for the error.
+* _error.raisedByObject_ the underlying object that raised the error.
+* _error.raisedByMethod_ the method that caused the error.
+* _error.raisedByParameters_ the parameters passed to the method that caused the error.
+
+Endtable Classes
+----------------
+
+Endtable Classes describe the ORM-backed objects.
+
+```javascript
+var Dog = endtable.Object.extend(
+ {
+ bark: function() {
+ sys.puts('Woof!!!');
+ }
+ },
+ {
+ engine: engine,
+ type: 'dog'
+ }
+);
+```
+
+* The first parameter contains all the methods that will be inherited by objects that instantiate the class.
+* The second parameter provides meta information:
+** _type_ represents the corresponding CouchDB resource name.
+** _engine_ is an instance of the Endtable Engine described previously.
+
+Creating ORM-Backed Objects
+---------------------------
+
+Once you've created some Endtable Classes simply instantiate them to create auto-persisting CouchDB-backed objects.
+
+```javascript
+var dog = new Dog({
+ name: 'Spike',
+ owner: 'Benjamin Coe',
+ coat: 'soft'
+})
+
+var dog2 = new Dog({
+ name: 'Fluffy',
+ owner: 'Eric Brown',
+ coat: 'rough'
+}, function(err, message) {
+ // Called after the first save.
+});
+```
+
+The first parameter passed to the constructor provides the instance variables for the object.
+
+An optional callback can be provided for the second parameter and will be executed the first time the object persists to CouchDB.
+
+Loading Objects
+---------------
+
+You can lookup objects based on any of their keys.
+
+Simply call the _load_ method on an Endtable Class:
+
+
+```javascript
+Dog.load({
+ keys: ['owner', 'coat'],
+ key: ['Benjamin Coe', 'soft']
+}, function(error, obj) {
+ if (!error) {
+ obj[0].bark();
+ }
+})
+```
+
+* _keys_ indicates the keys that an object will be looked up by. A CouchDB view will be generated to allow for this lookup.
+* _key_ is a set of concrete values that correspond with the keys described in keys.
+
+You can also load objects based on a range of keys.
+
+```javascript
+Person.load({
+ keys: 'age',
+ startkey: 28,
+ endkey: 50
+}, function(error, obj) {
+ if (!error) {
+ for (var i = 0; i < obj.length; i++) {
+ obj[i].sayName();
+ }
+ }
+})
+```
+
+This will load individuals with an age ranging from 28 to 50.
+
+Examples
+--------
+
+Run _node examples/person.js_ to get an idea of Endtable in action.
+
+Contributing to karait
+----------------------
+
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+Copyright
+---------
+
+Copyright (c) 2011 Benjamin Coe. See LICENSE.txt for
+further details.
View
24 README.textile
@@ -1,24 +0,0 @@
-h1. Endtable
-
-A ridiculously simple Object Mapper for Node running on top of CouchDB.
-
-h2. Known Issues
-
-* [FIXED] When running all specs periodic failures seem to be occurring. I think this is related to asynchronous tests and timing issues, the problem should however be investigated.
-** I seem to have narrowed the issue down to being caused by automatic view creation when two views are created simultaneously.
-* [FIXED] Periodically a document appears to fail to load, causing a spec to fail.
-** Synchronously saving documents seems to have fixed this problem.
-* [Fixed] Some IO operations do not fail gracefully, I would like to find a way to intercept these operations.
-** Currently connecting to CouchDB with an invalid host or port will cause it to explode.
-
-h2. Contributing
-
-# Fork the Endtable repo on Github.
-# Write a spec in */spec* that explains the behavior you are fixing and/or adding.
-# Write the corresponding code to fix the issue.
-# run __> node spec/all-specs.js__ to run all the specs (you will need a local copy of CouchDB running)
-# Send a pull request.
-
-h2. Ideas
-
-* I would like to abstract the Getter/Setter hooks out further in preparation for adding validation hooks.
Please sign in to comment.
Something went wrong with that request. Please try again.