updated docs + added HISTORY

HISTORY.md

@@ -0,0 +1,12 @@
+0.0.2 / October 24 2013
+=======================
+
+* Model: added automatic table creation
+* Model: putItem can now return a mapped item
+
+0.0.1 / October 23 2013
+=======================
+
+* initial release
+* incomplete features
+* incomplete documentation

README.md

@@ -202,7 +202,7 @@ var myTable = new DynamoDBModel.Model(tableName, schema, {
 
 When creating a model instance, a `describeTable` call is immediately performed to check for table existence. If the table does not exist, a `createTable` call follows immediately.
 
-If the table is not yet active (table status is not `"ACTIVE"`), all operations are queued and will not be executed until the table is ready. When the table becomes active, operations from the queue are executed in sequential order.
+If the table is not yet active (table status is not `"ACTIVE"`), all operations are queued and will not be executed until the table is ready. When the table becomes active, operations from the queue are executed in sequential order. This means that you can create a model instance and start writing data immediately, even if the table does not exist.
 
 If you wish to wait for the table to become available before performing an action, use the `waitForActiveTable` method, which invokes `describeTable` repeatedly until the status switches to `"ACTIVE"`.
 
@@ -211,30 +211,49 @@ If you wish to wait for the table to become available before performing an actio
 #### Model.batchGetItem
 
 This method is not yet implemented.
+
 [AWS Documentation for BatchGetItem](http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchGetItem.html)
 
 #### Model.batchWriteItem
 
 This method is not yet implemented.
+
 [AWS Documentation for BatchWriteItem](http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchWriteItem.html)
 
-#### Model.createTable
+#### Model.createTable(options, callback)
 
 Creates the DynamoDB table represented by the schema and returns the AWS service response.
 
++ options: attributes to add to the AWS.Request instance (optional)
++ callback: the callback function to invoke with the AWS response (optional)
+
+Callback arguments:
++ err: the error, if any
++ response: the AWS service response
+
 ```javascript
 var myTable = new DynamoDBModel.Model(tableName, schema);
 myTable.createTable(function (err, response) {
   // table creation started
 })
 ```
 
+Note: table creation in DynamoDB are asynchronous. The table is not ready until its status property is set to "ACTIVE". If you need to wait for the table to become active, use the `waitForActiveTable` method.
+
 [AWS Documentation for CreateTable](http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_CreateTable.html)
 
-#### Model.deleteItem
+#### Model.deleteItem(key, options, callback)
 
 Deletes a single item in a table by primary key and returns the AWS service response.
 
++ key: an object representing the primary key of the item to remove
++ options: attributes to add to the AWS.Request instance (optional)
++ callback: the callback function to invoke with the AWS response (optional)
+
+Callback arguments:
++ err: the error, if any
++ response: the AWS service response
+
 ```javascript
 var myTable = new DynamoDBModel.Model(tableName, schema);
 myTable.deleteItem({ id: 1 }, function (err, response) {
@@ -246,10 +265,17 @@ myTable.deleteItem({ id: 1 }, function (err, response) {
 
 Note: conditional deletes are not yet implemented.
 
-#### Model.deleteTable
+#### Model.deleteTable(options, callback)
 
 Removes the table represented by the schema, as well as all items in the table, then returns the AWS service response.
 
++ options: attributes to add to the AWS.Request instance (optional)
++ callback: the callback function to invoke with the AWS response
+
+Callback arguments:
++ err: the error, if any
++ response: the AWS service response
+
 ```javascript
 var myTable = new DynamoDBModel.Model(tableName, schema);
 myTable.deleteTable(function (err, response) {
@@ -259,24 +285,34 @@ myTable.deleteTable(function (err, response) {
 
 [AWS Documentation for DeleteTable](http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DeleteTable.html)
 
-#### Model.describeTable
+#### Model.describeTable(options, callback)
 
 Returns information about the table represented by the schema, including the current status of the table, when it was created, the primary key schema, and any indexes on the table. The table description is the AWS service response.
 
++ options: attributes to add to the AWS.Request instance (optional)
++ callback: the callback function to invoke with the AWS response
+
+Callback arguments:
++ err: the error, if any
++ response: the AWS service response
+
 ```javascript
 var myTable = new DynamoDBModel.Model(tableName, schema);
 myTable.describeTable(function (err, response) {
   // response contains the table description, see AWS docs for more details
 })
 ```
 
-#### Model.waitForActiveTable
+#### Model.waitForActiveTable(pollingInterval, callback)
 
 Invokes `describeTable` repeatedly until the table status is `"ACTIVE"`.
 
-Model.waitForActiveTable(pollingInterval, callback)
-+ pollingInterval: the delay in milliseconds between each invocation of `describeTable` (optional, default: 3000)
-+ callback: the callback function to invoke with the AWS response from `describeTable`
++ pollingInterval: the delay in milliseconds between each invocation of `describeTable` (optional, default value is 3000)
++ callback: the callback function to invoke with the AWS response from `describeTable` (optional)
+
+Callback arguments:
++ err: the error, if any
++ response: the AWS service response
 
 ```javascript
 var myTable = new DynamoDBModel.Model(tableName, schema);
@@ -286,10 +322,19 @@ myTable.waitForActiveTable(pollingInterval, function (err, response) {
 })
 ```
 
-#### Model.getItem
+#### Model.getItem(key, options, callback)
 
 Retrieves a specific item based on its primary key, returning the mapped item as well as the AWS service response.
 
++ key: an object representing the primary key of the item to retrieve
++ options: attributes to add to the AWS.Request instance (optional)
++ callback: the callback function to invoke with the AWS response
+
+Callback arguments:
++ err: the error, if any
++ item: the resulting item mapped according to the schema, or null
++ response: the AWS service response
+
 ```javascript
 var myTable = new DynamoDBModel.Model(tableName, schema);
 myTable.getItem({ id: 1 }, function (err, item, response) {
@@ -299,34 +344,47 @@ myTable.getItem({ id: 1 }, function (err, item, response) {
 
 [AWS Documentation for GetItem](http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_GetItem.html)
 
-#### Model.listTables
+#### Model.listTables(options, callback)
 
 This method is not yet implemented.
+
++ options: attributes to add to the AWS.Request instance (optional)
++ callback: the callback function to invoke with the AWS response
+
+Callback arguments:
++ err: the error, if any
++ response: the AWS service response
+
 [AWS Documentation for ListTables](http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_ListTables.html)
 
-#### Model.putItem
+#### Model.putItem(item, options, callback)
 
 TBD
+
 [AWS Documentation for PutItem](http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html)
 
 #### Model.query
 
 TBD
+
 [AWS Documentation for Query](http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html)
 
 #### Model.scan
 
 TBD
+
 [AWS Documentation for Scan](http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Scan.html)
 
 #### Model.updateItem
 
 TBD
+
 [AWS Documentation for UpdateItem](http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_UpdateItem.html)
 
 #### Model.updateTable
 
 TBD
+
 [AWS Documentation for UpdateTable](http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_UpdateTable.html)
 
 ### Reading results with DynamoDBModel.Query
@@ -348,18 +406,15 @@ This is the initial release of `dynamodb-model` and should not be considered pro
 * Improve API to be closer to Mongoose, using aliases for common methods
 * Check for table key changes, which are unsupported by DynamoDB
 
-## Changelog
-
-* 0.0.1: initial version
-
 ## Compatibility
 
 + Tested with Node 0.10.x
 + Tested on Mac OS X 10.8
 
 ## Dependencies
 
-+ [aws-sdk](https://github.com/aws/aws-sdk-js)
++ [async](http://github.com/caolan/async)
++ [aws-sdk](http://github.com/aws/aws-sdk-js)
 
 ## License