Clean up README

README.md

@@ -1,37 +1,23 @@
-dynalite
---------
+# dynalite
 
-[![Build Status](https://secure.travis-ci.org/mhart/dynalite.png?branch=master)](http://travis-ci.org/mhart/dynalite)
+[![Build Status](https://api.travis-ci.org/mhart/dynalite.png?branch=master)](https://travis-ci.org/github/mhart/dynalite)
 
-An implementation of Amazon's DynamoDB, focussed on correctness and performance, and built on LevelDB
-(well, [@rvagg](https://github.com/rvagg)'s awesome [LevelUP](https://github.com/rvagg/node-levelup) to be precise).
+An implementation of Amazon's DynamoDB built on LevelDB
+(well, [@rvagg](https://github.com/rvagg)'s awesome [LevelUP](https://github.com/Level/levelup) to be precise)
+for fast in-memory or persistent usage.
 
 This project aims to match the live DynamoDB instances as closely as possible
 (and is tested against them in various regions), including all limits and error messages.
 
-NB: Schema changes in v2.x
---------------------------
+## What about Amazon's DynamoDB Local?
 
-If you've been using v1.x or v0.x or with a saved path on your filesystem, you
-should note that key schema may have changed with the move from
-`level-sublevel` to `subleveldown`. The safest way to deal with this is to
-export your DB to JSON using Scans, then upgrade and import with BatchWrites
-into the new version.
+This project was created before DynamoDB Local existed, and when it did, it differed a lot from the live instances
+in ways that caused my company issues. Since then it's had a lot more development and resources thrown at it,
+and is probably more up-to-date than dynalite is. I'd recommend using it over dynalite if you don't mind the
+overhead of starting the JVM (or docker) each time. If you need a fast in-memory option that you can start up in
+milliseconds, then dynalite might be more suitable for you.
 
-Why not Amazon's DynamoDB Local?
---------------------------------
-
-Good question! These days it's actually pretty good, and considering it's now probably
-used by countless AWS devs, it'll probably be well supported going forward. Unless you
-specifically can't, or don't want to, use Java, or you're having problems with it,
-you'll probably be better off sticking with it! Originally, however, DynamoDB Local
-didn't exist, and when it did, differed a lot from the live instances in ways that caused
-my company issues. Most of those issues have been addressed in time, but DynamoDB Local
-does still differ in a number of ways from the live DynamoDB instances –
-([see below](#problems-with-amazons-dynamodb-local-updated-2016-04-19)) for details.
-
-Example
--------
+## Example
 
 ```sh
 $ dynalite --help
@@ -57,8 +43,8 @@ Or programmatically:
 
 ```js
 // Returns a standard Node.js HTTP server
-var dynalite = require('dynalite'),
-    dynaliteServer = dynalite({path: './mydb', createTableMs: 50})
+var dynalite = require('dynalite')
+var dynaliteServer = dynalite({ path: './mydb', createTableMs: 50 })
 
 // Listen on port 4567
 dynaliteServer.listen(4567, function(err) {
@@ -68,53 +54,35 @@ dynaliteServer.listen(4567, function(err) {
 ```
 
 Once running, here's how you use the [AWS SDK](https://github.com/aws/aws-sdk-js) to connect
-(after [configuring the SDK](http://docs.aws.amazon.com/AWSJavaScriptSDK/guide/node-configuring.html)):
+(after [configuring the SDK](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/configuring-the-jssdk.html)):
 
 ```js
 var AWS = require('aws-sdk')
 
-var dynamo = new AWS.DynamoDB({endpoint: 'http://localhost:4567'})
+var dynamo = new AWS.DynamoDB({ endpoint: 'http://localhost:4567' })
 
 dynamo.listTables(console.log.bind(console))
 ```
 
-Installation
-------------
+## Installation
 
-With [npm](http://npmjs.org/) do:
+With [npm](https://www.npmjs.com/), to install the CLI:
 
 ```sh
-$ npm install -g dynalite
+npm install -g dynalite
 ```
 
-TODO
-----
+Or to install for development/testing in your project:
 
+```sh
+npm install -D dynalite
+```
+
+## TODO
+
+- Implement [Transactions](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/transaction-apis.html)
 - Implement DynamoDB Streams
 - Implement `ReturnItemCollectionMetrics` on all remaining endpoints
 - Implement size info for tables and indexes
 - Add ProvisionedThroughput checking
 - See [open issues on GitHub](https://github.com/mhart/dynalite/issues) for any further TODOs
-
-Problems with Amazon's DynamoDB Local (UPDATED 2016-04-19)
--------------------------------------
-
-Part of the reason I wrote dynalite was due to the existing mock libraries not exhibiting the same behaviour as the
-live instances. Amazon then released their DynamoDB Local Java, but the early versions were still very different.
-The latest version I checked (2016-04-19) is much better, but still has a few differences.
-
-[Some of these are documented](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.UsageNotes.html#DynamoDBLocal.Differences),
-but most aren't - the items below are a rough list of the issues found, vaguely in order of importance:
-
-- Does not return nested attributes correctly for `UpdateItem`
-- Does not calculate size limits accurately for `BatchGetItem`/`Query`/`Scan` result sets
-- Does deal with `ALL_ATTRIBUTES` correctly for global index on `Query`/`Scan`
-- Does not prevent primary keys in `QueryFilter` and `FilterExpression` for `Query`
-- Does not detect duplicate values in `AttributesToGet`
-- Does not return `LastEvaluatedKey` when size just over limit for `Query`/`Scan`
-- Does not return `ConsistentRead` property in `UnprocessedKeys` in `BatchGetItem` even if requested
-- Doesn't return `ConsumedCapacity` (documented - but makes it very hard to calculate expected usage)
-- Often returns 500 instead of 400 (or similarly appropriate status)
-- Different serialization and validation error messages from live instances (makes it hard to debug)
-- Does not return `application/json` if `application/json` is requested
-- Does not return `Query`/`Scan` items in same order when using hash key or hash `GlobalSecondaryIndex` (shouldn't rely on this anyway)