Update README and package.json

README.md

@@ -1,13 +1,19 @@
-NAME
-----
+# NAME
 
 node-sqlite - Asynchronous SQLite3 driver for Node.js
 
-SYNOPSIS
---------
+This distribution includes two SQLite libraries: a low level driver
+written in C++ and a high level driver. The latter wraps the former to add
+simpler API.
+
+SQLite calls block, so to work around this, synchronous calls happen within
+Node's libeio thread-pool, in a similar manner to how POSIX calls are
+currently made. SQLite's serialized threading mode is used to make sure we
+use SQLite safely. See http://www.sqlite.org/threadsafe.html for more info.
+
+# SYNOPSIS
 
-High-level Driver
-=================
+## High-level Driver
 
 High-level bindings provide a simple interface to SQLite3. They should be
 fast enough for most purposes, but if you absolutely need more performance,
@@ -43,15 +49,13 @@ additional steps.
       });
     });
 
-Low-level Driver
-================
+## Low-level Driver
 
 The low-level bindings directly interface with the SQLite C API. The API
-approximately matches the SQLite3 API when it makes sense. Some deviations
-from the API have been made to improve performance.
+approximately matches the SQLite3 API when it makes sense.
 
     var sys    = require('sys'),
-        sqlite = require('sqlite_bindings');
+        sqlite = require('sqlite/sqlite3_bindings');
 
     var db = new sqlite.Database();
 
@@ -60,17 +64,12 @@ from the API have been made to improve performance.
 
     db.open("lilponies.db", function () {
       var colour = 'pink';
-      var sql = 'SELECT name FROM ponies WHERE hair_colour = $hair_colour and gemstones = ?';
+      var sql = 'SELECT name FROM ponies' +
+                ' WHERE hair_colour = $hair_colour' +
+                ' AND gemstones = ?';
 
       var ponies = [];
 
-      // The prepare method will try to prefetch one row of results, so that
-      // if there are no rows we can avoid having to make two trips into the
-      // thread-pool.
-      // If `statement` and didn't have any variable place-holders to bind
-      // and doesn't evaluate to true, then it means the statement
-      // executed successfully but returned no rows (think INSERT's).
-
       db.prepare(sql, function (error, statement) {
         if (error) throw error;
 
@@ -93,73 +92,133 @@ from the API have been made to improve performance.
       });
     });
 
+# API
 
-DESCRIPTION
------------
+## Database Objects
 
-This distribution includes two SQLite version 3 drivers: a low level driver
-written in C++ and a high level driver. The latter wraps the former to add
-nicer API.
+To create a new database object:
+
+    var db = sqlite_bindings.Database();
+
+### database.open(filename, function (error) {})
+
+Open a database handle to the database at the specified filename. If the file
+does not exist the bindings will attempt to create it. The callback takes no
+arguments.
+
+A filename of ":memory:" may be used to create an in-memory database.
+
+### database.close(function (error) {})
+
+Close the database handle.
+
+### database.prepare(SQL, [options,] function (error, statement) {})
+
+Create a prepared statement from an SQL string. Prepared statements can be
+used used to iterate over results and to avoid compiling SQL each time a query
+is performed.  
+
+Options:
+
+- lastInsertRowID: boolean, default false.
+    If true, when this statement is stepped over, the context object (this) in
+    the callback will contain a lastInsertRowID member with the ID of the last
+    inserted row.
+
+- affectedRows: boolean, default false.
+    If true, when this statement is stepped over, the context object (this) in
+    the callback will contain an affectedRows member with the number of
+    affected rows for the last step.
+
+## Statement Objects
+
+### statement.bindArray(array, function (error) {})
+
+    statement.bindArray([1, 'robots', 4.20], callback)
+
+Bind array items to place-holder values (? or $foo) in statement.
+
+### statement.bindObject(object, function (error) {})
+
+    statement.bindObject({ $name: 'meatwad',
+                           $occupation: 'Former detective' }, callback)
+
+Bind object properties to named place-holder values ($foo, $bar, $baz) in
+statement.
+
+### statement.bind(position, value, function (error) {})
+
+    statement.bind(1, "tango", function (error) {})
+
+Bind a value to a place-holder position. Because binding place-holders is done
+by position (not index), the first place-holder is at position 1, second at
+place-holder position 2, etc.
+
+### statement.clearBindings()
+
+Immediately clear the bindings from the statement. There is no callback.
+
+### statement.step(function (error, row) {})
+
+Fetch one row from a prepared statement and hand it off to a callback. If
+there are no more rows to be fetched, row will be undefined. Rows are
+represented as objects with
+properties named after the respective columns.
+
+### statement.fetchAll(function (error, rows) {})
+
+Fetch all rows in statement and pass them to the callback as an array of
+objects, each object representing one row.
+
+### statement.reset()
 
-It's HTML5 WebDatabasish but much, much simpler.
+Immediately reset a statement object back to it's initial state, ready to be
+step() or fetchAll()'d again.
 
-At the moment, this library is the bare minimum necessary to get results out
-of SQLite, but extending either driver should be quite straight forward.
+### statement.finalize(function (error) {})
 
-This SQLite interface is incompatible with version 2.
+Free SQLite objects associated with this statement and mark it for garbage
+collection.
 
-SQLite's synchronous nature is fundamentally incompatible with a non-blocking
-system such as Node. To get around this synchronous calls happen within Node's
-libeio thread-pool, in a similar manner to how POSIX calls are currently made.
-SQLite's serialized threading mode is used to make sure we use SQLite safely.
-See http://www.sqlite.org/threadsafe.html for more info.
+## Supported Types
 
-The author is aware that SQLite ships with an asynchronous interface. This
-interface however lacks the necessary notification mechanism to alert the
-caller when the SQLite call has completed. In other words, to be able to
-support callbacks, we use the synchronous driver within a seperate thread.
+At the moment, the supported types are TEXT, NUMBER, FLOAT and NULL.
 
-BUILDING
---------
+# BUILDING
 
-To build the bindings:
+To obtain and build the bindings:
 
     git clone http://github.com/orlandov/node-sqlite.git
     cd node-sqlite
     node-waf configure build
 
-TESTS
------
+# TESTS
 
 Running the unit tests could not be easier. Simply:
 
     git submodule update --init
     ./run-tests
 
-SEE ALSO
---------
+# SEE ALSO
 
 * http://sqlite.org/docs.html
 * http://github.com/grumdrig/node-sqlite/
 
-AUTHORS
--------
+# AUTHORS
 
 Orlando Vazquez [ovazquez@gmail.com]
 
 Ryan Dahl [ry@tinyclouds.org]
 
-THANKS
-------
+# THANKS
 
 Many thanks to Eric Fredricksen for his synchronous driver on which this
 driver was originally based.
 
 * http://github.com/grumdrig/node-sqlite/
 * http://grumdrig.com/node-sqlite/
 
-LICENSE
--------
+# LICENSE
 
 node-sqlite is BSD licensed.
 

package.json

@@ -1,6 +1,6 @@
 { "name": "sqlite"
 , "description": "SQLite3 bindings for Node"
-, "version": "0.0.2"
+, "version": "0.0.3"
 , "homepage": "http://github.com/orlandov/node-sqlite"
 , "author":
     "Orlando Vazquez <ovazquez@gmail.com> (http://2wycked.net)"
@@ -15,7 +15,7 @@
   , "url": "http://github.com/orlandov/node-sqlite.git"
   }
 , "directories" : { "lib" : "." }
-, "engines" : { "node" : ">=0.1.103" }
+, "engines" : { "node" : ">=0.2.0" }
 , "scripts" : { "test" : "./run-tests" }
 , "licenses" :
   [ { "type" : "BSD" }