pixl-server-storage 3.1.18 → 3.2.0

package/docs/Hashes.md

@@ -8,8 +8,8 @@ All hash operations will automatically lock the hash using [Advisory Locking](..
 
 The code examples all assume you have your preloaded `Storage` component instance in a local variable named `storage`.  The component instance can be retrieved from a running server like this:
 
-```javascript
-var storage = server.Storage;
+```js
+let storage = server.Storage;
 ```
 
 ## Table of Contents
@@ -37,7 +37,7 @@ Care should be taken when calculating your hash page sizes.  It all depends on h
 
 To create a hash, call [hashCreate()](API.md#hashcreate).  Specify the desired storage path, options, and a callback function.  You can optionally pass in a custom page size via the second argument (otherwise it'll use the default size):
 
-```javascript
+```js
 storage.hashCreate( 'hash1', { page_size: 100 }, function(err) {
 	if (err) throw err;
 } );
@@ -53,7 +53,7 @@ To store a key/value pair, call [hashPut](API.md#hashput), and to fetch a value
 
 Here is an example of storing and fetching a hash record.  The hash itself is located at the storage path `users`, and we are storing and fetching the hash key `bsanders` within that hash.
 
-```javascript
+```js
 // Store a key/value pair
 storage.hashPut( 'users', 'bsanders', { name: 'Bernie', age: 75 }, function(err) {
 	if (err) throw err;
@@ -73,7 +73,7 @@ Note that you do not need to explicitly create the hash via [hashCreate()](API.m
 In addition to storing single records, you can specify multiple at a time using the [hashPutMulti()](API.md#hashputmulti) method.  Instead of key and value arguments, pass in an object containing as many as you want:
 
 ```js
-var records = {
+let records = {
 	"bsanders": { name: "Bernie", age: 75 },
 	"hclinton": { name: "Hillary", age: 68 },
 	"dtrump": { name: "Donald", age: 70 }
@@ -86,7 +86,7 @@ storage.hashPutMulti( 'users', records, function(err) {
 
 Similarly, to fetch multiple records, use [hashGetMulti()](API.md#hashgetmulti).  Specify your desired keys in an array, and you'll get an array of values with numerical indexes that match up to your keys:
 
-```javascript
+```js
 storage.hashGetMulti( 'users', ['bsanders', 'hclinton', 'dtrump'], function(err, values) {
 	if (err) throw err;
 	// values[0] will be the bsanders record.
@@ -97,13 +97,13 @@ storage.hashGetMulti( 'users', ['bsanders', 'hclinton', 'dtrump'], function(err,
 
 Finally, if you simply want to fetch *all* the records in a hash in one fell swoop, and you aren't concerned with memory usage, call [hashGetAll()](API.md#hashgetall).
 
-```javascript
+```js
 storage.hashGetAll( 'users', function(err, items) {
 	if (err) throw err;
 	
 	// do something with all items
-	for (var key in items) {
-		var value = items[key];
+	for (let key in items) {
+		let value = items[key];
 		// do something with key/value pair
 	}
 } );
@@ -126,7 +126,7 @@ function(err) {
 
 Alternatively, you can use [hashEachSync()](API.md#hasheachsync) in which the iterator is invoked in a *synchronous* manner, i.e. continuing as soon as it returns (similar to [Array.forEach()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach)).  However, please note that the full loop operation isn't synchronous, and you need to provide a callback to be fired when every key has been iterated over.  Example:
 
-```javascript
+```js
 storage.hashEachSync( 'users', function(key, value) {
 	// do something with key/value
 	// no callback here
@@ -139,11 +139,11 @@ function(err) {
 
 Finally, you can use [hashEachPage()](API.md#hasheachpage), which iterates over the internal hash pages, and only fires your iterator function once per page, instead of once per key.  This is typically faster as it requires fewer function calls.  Your iterator is invoked in an *asynchronous* manner, i.e. it must fire a callback to continue (similar to [async eachSeries()](http://caolan.github.io/async/docs.html#.eachSeries)).  Example:
 
-```javascript
+```js
 storage.hashEachPage( 'users', function(items, callback) {
 	// do something with page of items
-	for (var key in items) {
-		var value = items[key];
+	for (let key in items) {
+		let value = items[key];
 		// do something with each key/value pair
 	}
 	
@@ -160,7 +160,7 @@ function(err) {
 
 To duplicate a hash and all of its items at a new storage path, call [hashCopy()](API.md#hashcopy), specifying the old and new paths.  Example:
 
-```javascript
+```js
 storage.hashCopy( 'hash1', 'hash2', function(err) {
 	if (err) throw err;
 } );
@@ -168,7 +168,7 @@ storage.hashCopy( 'hash1', 'hash2', function(err) {
 
 To rename a hash, call [hashRename()](API.md#hashrename).  This is basically just a [hashCopy()](API.md#hashcopy) followed by a [hashDeleteAll()](API.md#hashdeleteall).  Example:
 
-```javascript
+```js
 storage.hashRename( 'hash1', 'hash2', function(err) {
 	if (err) throw err;
 } );
@@ -180,7 +180,7 @@ With both of these functions, it is highly recommended you make sure the destina
 
 To delete a single hash key, call [hashDelete()](API.md#hashdelete).  Example:
 
-```javascript
+```js
 storage.hashDelete( 'users', 'dtrump', function(err) {
 	if (err) throw err;
 } );
@@ -188,7 +188,7 @@ storage.hashDelete( 'users', 'dtrump', function(err) {
 
 If you delete the last key from a hash, an "empty" hash will remain in storage (this includes metadata such as the options, page size, etc).  If you want to delete the *entire* hash when the last key is removed, pass `true` as the 3rd argument before the callback:
 
-```javascript
+```js
 storage.hashDelete( 'users', 'dtrump', true, function(err) {
 	if (err) throw err;
 } );
@@ -196,7 +196,7 @@ storage.hashDelete( 'users', 'dtrump', true, function(err) {
 
 To delete multiple hash keys at once, use [hashDeleteMulti()](API.md#hashdeletemulti).  Specify your desired keys in an array:
 
-```javascript
+```js
 storage.hashDeleteMulti( 'users', ['bsanders', 'hclinton', 'dtrump'], function(err) {
 	if (err) throw err;
 } );
@@ -204,7 +204,7 @@ storage.hashDeleteMulti( 'users', ['bsanders', 'hclinton', 'dtrump'], function(e
 
 Finally, to delete an *entire* hash including all its keys, call [hashDeleteAll()](API.md#hashdeleteall):
 
-```javascript
+```js
 storage.hashDeleteAll( 'users', function(err) {
 	if (err) throw err;
 } );
@@ -212,7 +212,7 @@ storage.hashDeleteAll( 'users', function(err) {
 
 As with `hashDelete()`, by default this will only empty a hash, leaving behind an empty header record (with options, page size, etc).  To delete that as well, pass `true` as the 2nd argument before the callback:
 
-```javascript
+```js
 storage.hashDeleteAll( 'users', true, function(err) {
 	if (err) throw err;
 } );

package/docs/Indexer.md

@@ -10,14 +10,14 @@ Before using the indexer, please keep the following in mind:
 - You are expected to store your record data yourself.
 	- The indexer **only** indexes fields for searching purposes -- it does not store raw records for retrieval.
 - When performing a search, you **only** get your record IDs back.  
-	- You are expected to paginate and fetch your own record data (i.e. via [getMulti()](API.md#getMulti) or other).
+	- You are expected to paginate and fetch your own record data (i.e. via [getMulti()](API.md#getmulti) or other).
 
 The indexer works with any storage engine, but it is optimized for the local filesystem.  Transactions are automatically used for indexing and unindexing records, if they are enabled (this is highly recommended).
 
 The code examples all assume you have your preloaded `Storage` component instance in a local variable named `storage`.  The component instance can be retrieved from a running server like this:
 
-```javascript
-var storage = server.Storage;
+```js
+let storage = server.Storage;
 ```
 
 ## Table of Contents
@@ -63,11 +63,9 @@ var storage = server.Storage;
 
 The indexer only processes words that contain standard U.S. ASCII alphanumeric characters, e.g. A-Z, 0-9, and underscore.  All other characters are skipped, and serve as word separators.  International (Unicode) characters are converted to ASCII at index and search time (see [Unicode Characters](#unicode-characters) below for more on this).
 
-The indexer is **very slow**.  All index operations involve reading and writing JSON storage records *at the word level* (i.e. a hash for each unique word!), and the system is designed to eat as little memory as possible.  Expect hundreds or even thousands of storage operations for indexing a single record.  Searching is fairly quick by comparison, because typically you're only searching on a small number of words.  This also assumes your storage back-end is fast (preferably local SSD filesystem), and your search queries are simple and straightforward.
-
-This system is not designed for large datasets.  Thousands of records is probably fine, and maybe even tens of thousands depending on the index types and data size.  *Hundreds of thousands* of records would likely end in tears.  Also, keep an eye on your [inodes](https://en.wikipedia.org/wiki/Inode), because this thing is hungry for them.
+The indexer can be slow, depending on the storage engine.  All index operations involve reading and writing JSON storage records *at the word level* (i.e. a hash for each unique word!), and the system is designed to eat as little memory as possible.  Expect hundreds or even thousands of storage operations for indexing a single record.  Searching is fairly quick by comparison, because typically you're only searching on a small number of words.  This also assumes your storage back-end is fast (preferably local SSD filesystem, or you are using a very fast key/value store like Couchbase or SQLite), and your search queries are simple and straightforward.
 
-Remember, this is just a silly hobby project.  You should not use this for any production applications.
+This system is not designed for large query results.  Thousands of records returned is probably fine, and maybe even tens of thousands depending on the index types and data size.  *Hundreds of thousands* of records would likely end in tears.  Also, if you are using the Filesystem storage engine, keep an eye on your [inodes](https://en.wikipedia.org/wiki/Inode), because this thing is hungry for them.
 
 ## Configuration
 
@@ -325,7 +323,7 @@ Here is a simple example:
 
 ```js
 // Index configuration
-var config = {
+let config = {
 	"base_path": "index/myapp",
 	"fields": [
 		{
@@ -353,7 +351,7 @@ var config = {
 };
 
 // Record object
-var record = {
+let record = {
 	"BodyText": "This is the body text of my ticket, which <b>may contain HTML</b> and \nmultiple\nlines.\n",
 	"ModifyDate": "2018/01/07",
 	"Tags": "bug, assigned, open"
@@ -804,7 +802,7 @@ If you want to make changes to your index configuration, i.e. add or remove fiel
 To add a new field to your index, you simply have to apply the change to your index configuration, then call [indexRecord()](API.md#indexrecord) on all your records again.  The indexer is smart enough to know that all your existing field values haven't changed, but you have added a new one which needs to be indexed.  Example:
 
 ```js
-var async = require('async');
+const async = require('async');
 
 // fetch all record ids
 storage.searchRecords( '*', config, function(err, results) {
@@ -834,7 +832,7 @@ storage.searchRecords( '*', config, function(err, results) {
 To delete a field, the process is similar to adding one.  You will have to iterate over all your records, and call [indexRecord()](API.md#indexrecord) on each one, except this time we'll add a special `delete` property to the index you want to delete.  This tells the library to force a delete on reindex.  Here is an example:
 
 ```js
-var async = require('async');
+const async = require('async');
 
 // mark the field you want to delete with a `delete` property
 config.fields[2].delete = true;
@@ -880,8 +878,7 @@ Make sure you leave the index field settings set to their old values when you ad
 - Make use of the [Stemmer](#stemming) for your full text fields.
 - Only enable `master_list` on fields with a small number of unique words.
 - Sorting is slow, consider using alphabetically sortable IDs, and sorting the records that way.
-- Searching by date range and number range is very slow, try to avoid.
-- Everything is slow, don't use this stupid library, LOL :)
+- Searching by date range and number range can be very slow.
 
 ## Indexer Internals
 
@@ -963,7 +960,7 @@ The first thing to notice is that everything is under a base path of `index/myap
 So in our example configuration, we have three indexed fields: `body`, `modified` and `tags`.  As you can see in the data layout, each one occupies its own "namespace" in storage, and contains hashes for each unique value, and in some cases a [summary](#master-list) record as well.  For reference, here was our sample record ("TICKET0001") was was used to populate the indexes:
 
 ```js
-var record = {
+let record = {
 	"BodyText": "This is the body text of my ticket, which <b>may contain HTML</b> and \nmultiple\nlines.\n",
 	"ModifyDate": "2018/01/07",
 	"Tags": "bug, assigned, open"

package/docs/Lists.md

@@ -6,8 +6,8 @@ All list operations will automatically lock the list using [Advisory Locking](..
 
 The code examples all assume you have your preloaded `Storage` component instance in a local variable named `storage`.  The component instance can be retrieved from a running server like this:
 
-```javascript
-var storage = server.Storage;
+```js
+let storage = server.Storage;
 ```
 
 ## Table of Contents
@@ -40,7 +40,7 @@ Care should be taken when calculating your list page sizes.  It all depends on h
 
 To create a list, call [listCreate()](API.md#listcreate).  Specify the desired key, options, and a callback function.  You can optionally pass in a custom page size via the second argument (otherwise it'll use the default size):
 
-```javascript
+```js
 storage.listCreate( 'list1', { page_size: 100 }, function(err) {
 	if (err) throw err;
 } );
@@ -54,7 +54,7 @@ Lists can be treated as arrays to a certain extent.  Methods are provided to [pu
 
 Examples:
 
-```javascript
+```js
 // push onto the end
 storage.listPush( 'list1', { username: 'tsmith', age: 25 }, function(err) {
 	if (err) throw err;
@@ -82,7 +82,7 @@ Furthermore, the [listPush()](API.md#listpush) and [listUnshift()](API.md#listun
 
 Items can be fetched from lists by calling [listGet()](API.md#listget), and specifying an index offset starting from zero.  You can fetch any number of items at a time, and the storage engine will figure out which pages need to be loaded.  To fetch items from the end of a list, use a negative index.  Example use:
 
-```javascript
+```js
 storage.listGet( 'list1', 40, 5, function(err, items) {
 	if (err) throw err;
 } );
@@ -90,7 +90,7 @@ storage.listGet( 'list1', 40, 5, function(err, items) {
 
 This would fetch 5 items starting at item index 40 (zero-based).  To fetch the entire list, set the index and length to zero:
 
-```javascript
+```js
 storage.listGet( 'list1', 0, 0, function(err, items) {
 	if (err) throw err;
 } );
@@ -102,8 +102,8 @@ You can "splice" a list just like you would an array.  That is, cut a chunk out
 
 Here is an example which removes 2 items at index 40, and replaces with 2 new items:
 
-```javascript
-var new_items = [
+```js
+let new_items = [
 	{ username: 'jhuckaby', age: 38, gender: 'male' },
 	{ username: 'sfields', age: 34, gender: 'female' }
 ];
@@ -121,8 +121,8 @@ As with [listGet()](API.md#listget) you can specify a negative index number to t
 
 While it is possible to manually sort your list by fetching all the items as an array, sorting it in memory, then rewriting the entire list, this can be quite time consuming.  Instead, you can perform a [listInsertSorted()](API.md#listinsertsorted) when adding items to a list.  This will find the correct location for a single item based on sorting criteria, and then splice it into place, keeping the list sorted as you go.  Example:
 
-```javascript
-var new_user = {
+```js
+let new_user = {
 	username: 'jhuckaby', 
 	age: 38, 
 	gender: 'male' 
@@ -136,14 +136,14 @@ storage.listInsertSorted( 'users', new_user, ['username', 1], function(err) {
 
 That third argument is an array of sort criteria, consisting of the property name to sort by (e.g. `username`) and a sort direction (`1` for ascending, `-1` for descending).  You can alternately specify a comparator function here, which is called with the item you are inserting, and the item to compare it to.  This is similar to the built-in [Array.sort()](), which should return `1` or `-1` depending on if your item should come after, or before, the second item.  Example:
 
-```javascript
-var new_user = {
+```js
+let new_user = {
 	username: 'jhuckaby', 
 	age: 38, 
 	gender: 'male' 
 };
 
-var comparator = function(a, b) {
+let comparator = function(a, b) {
 	return( (a.username < b.username) ? -1 : 1 );
 };
 
@@ -159,7 +159,7 @@ For large lists, this can still take considerable time, as it is iterating over
 
 Need to iterate over the items in your list, but don't want to load the entire thing into memory?  Use the [listEach()](API.md#listeach) method.  Example:
 
-```javascript
+```js
 storage.listEach( 'list1', function(item, idx, callback) {
 	// do something with item, then fire callback
 	callback();
@@ -174,7 +174,7 @@ Your iterator function is passed the item and a special callback function, which
 
 Alternatively, you can use [listEachPage()](API.md#listeachpage), which iterates over the internal list [pages](#list-page-size), and only fires your iterator function once per page, instead of once per item.  This is typically faster as it requires fewer function calls.  Example:
 
-```javascript
+```js
 storage.listEachPage( 'list1', function(items, callback) {
 	// do something with items, then fire callback
 	callback();
@@ -189,7 +189,7 @@ function(err) {
 
 To iterate over and possibly update items, you can use the [listEachUpdate()](API.md#listeachupdate) method.  Your iterator callback accepts a second boolean argument which can indicate that you made changes.  Example:
 
-```javascript
+```js
 storage.listEachUpdate( 'list1', function(item, idx, callback) {
 	// do something with item, then fire callback
 	item.something = "something new!";
@@ -205,7 +205,7 @@ As you can see, the iterator callback accepts two arguments, an error (or someth
 
 For a speed optimization, you can optionally iterate over entire list [pages](#list-page-size) rather than individual items.  To do this, use the [listEachPageUpdate()](API.md#listeachpageupdate) method.  In this case your iterator callback is passed an array of items on each page.  Example:
 
-```javascript
+```js
 storage.listEachPageUpdate( 'list1', function(items, callback) {
 	// do something with items, then fire callback
 	items.forEach( function(item) {
@@ -225,7 +225,7 @@ Several methods are provided for searching through lists for items matching a se
 
 All of these methods accept a "criteria" object, which may have one or more key/value pairs.  These must *all* match a list item for it to be selected.  For example, if you have a list of users, and you want to find a male with blue eyes, you would pass a criteria object similar to this:
 
-```javascript
+```js
 {
 	gender: "male",
 	eyes: "blue"
@@ -234,7 +234,7 @@ All of these methods accept a "criteria" object, which may have one or more key/
 
 Alternatively, you can use regular expression objects for the criteria values, for more complex matching.  Example:
 
-```javascript
+```js
 {
 	gender: /^MALE$/i,
 	eyes: /blu/
@@ -243,7 +243,7 @@ Alternatively, you can use regular expression objects for the criteria values, f
 
 Example of finding a single object with [listFind()](API.md#listfind):
 
-```javascript
+```js
 storage.listFind( 'list1', { username: 'jhuckaby' }, function(err, item, idx) {
 	if (err) throw err;
 } );
@@ -251,7 +251,7 @@ storage.listFind( 'list1', { username: 'jhuckaby' }, function(err, item, idx) {
 
 Example of finding and deleting a single object with [listFindCut()](API.md#listfindcut):
 
-```javascript
+```js
 storage.listFindCut( 'list1', { username: 'jhuckaby' }, function(err, item) {
 	if (err) throw err;
 } );
@@ -259,9 +259,9 @@ storage.listFindCut( 'list1', { username: 'jhuckaby' }, function(err, item) {
 
 Example of finding and replacing a single object with [listFindReplace()](API.md#listfindreplace):
 
-```javascript
-var criteria = { username: 'jhuckaby' };
-var new_item = { username: 'huckabyj', foo: 'bar' };
+```js
+let criteria = { username: 'jhuckaby' };
+let new_item = { username: 'huckabyj', foo: 'bar' };
 
 storage.listFindReplace( 'list1', criteria, new_item, function(err) {
 	if (err) throw err;
@@ -270,9 +270,9 @@ storage.listFindReplace( 'list1', criteria, new_item, function(err) {
 
 Example of finding and updating a single object with [listFindUpdate()](API.md#listfindupdate):
 
-```javascript
-var criteria = { username: 'jhuckaby' };
-var updates = { gender: 'male', age: 38 };
+```js
+let criteria = { username: 'jhuckaby' };
+let updates = { gender: 'male', age: 38 };
 
 storage.listFindUpdate( 'list1', criteria, updates, function(err, item) {
 	if (err) throw err;
@@ -281,9 +281,9 @@ storage.listFindUpdate( 'list1', criteria, updates, function(err, item) {
 
 You can also increment or decrement numerical properties with [listFindUpdate()](API.md#listfindupdate).  If an item key exists and is a number, you can set any update key to a string prefixed with `+` (increment) or `-` (decrement), followed by the delta number (int or float), e.g. `+1`.  So for example, imagine a list of users, and an item property such as `number_of_logins`.  When a user logs in again, you could increment this counter like this:
 
-```javascript
-var criteria = { username: 'jhuckaby' };
-var updates = { number_of_logins: "+1" };
+```js
+let criteria = { username: 'jhuckaby' };
+let updates = { number_of_logins: "+1" };
 
 storage.listFindUpdate( 'list1', criteria, updates, function(err, item) {
 	if (err) throw err;
@@ -292,7 +292,7 @@ storage.listFindUpdate( 'list1', criteria, updates, function(err, item) {
 
 And finally, here is an example of finding *all* items that match our criteria using [listFindEach()](API.md#listfindeach), and iterating over them:
 
-```javascript
+```js
 storage.listFindEach( 'list1', { gender: 'male' }, function(item, idx, callback) {
 	// do something with item, then fire callback
 	callback();
@@ -307,7 +307,7 @@ function(err) {
 
 To duplicate a list and all of its items, call [listCopy()](API.md#listcopy), specifying the old and new key.  Example:
 
-```javascript
+```js
 storage.listCopy( 'list1', 'list2', function(err) {
 	if (err) throw err;
 } );
@@ -315,7 +315,7 @@ storage.listCopy( 'list1', 'list2', function(err) {
 
 To rename a list, call [listRename()](API.md#listrename).  This is basically just a [listCopy()](API.md#listcopy) followed by a [listDelete()](API.md#listdelete).  Example:
 
-```javascript
+```js
 storage.listRename( 'list1', 'list2', function(err) {
 	if (err) throw err;
 } );
@@ -327,7 +327,7 @@ With both of these functions, it is highly recommended you make sure the destina
 
 To delete a list and all of its items, call [listDelete()](API.md#listdelete).  The second argument should be a boolean set to `true` if you want the list *entirely* deleted including the header (options, page size, etc.), or `false` if you only want the list *cleared* (delete the items only, leaving an empty list behind).  Example:
 
-```javascript
+```js
 storage.listDelete( 'list1', true, function(err) {
 	if (err) throw err;
 	// list is entirely deleted
@@ -338,7 +338,7 @@ storage.listDelete( 'list1', true, function(err) {
 
 Lists consist of a header record, plus additional records for each page.  The header is literally just a simple JSON record, stored at the exact key specified for the list.  So if you created an empty list with key `mylist`, and then you fetched the `mylist` record using a simple [get()](API.md#get), you'd see this:
 
-```javascript
+```js
 {
 	type: 'list',
 	length: 0,
@@ -360,7 +360,7 @@ This is the list header record, which defines the list and its pages.  Here are
 
 The list pages are stored as records "under" the main key, by adding a slash, followed by the page number.  So if you pushed one item onto the list, the updated header record would look like this:
 
-```javascript
+```js
 {
 	type: 'list',
 	length: 1,
@@ -374,7 +374,7 @@ Notice that the `first_page` and `last_page` are both still set to `0`, even tho
 
 So then if you then fetched the key `mylist/0` you'd actually get the raw page data, which is a JSON record with an `items` array:
 
-```javascript
+```js
 {
 	items: [
 		{ username: "jhuckaby", gender: "male" }

package/docs/Transactions.md

@@ -6,8 +6,8 @@ The transaction system works with any storage engine, but it is optimized for th
 
 The code examples all assume you have your preloaded `Storage` component instance in a local variable named `storage`.  The component instance can be retrieved from a running server like this:
 
-```javascript
-var storage = server.Storage;
+```js
+let storage = server.Storage;
 ```
 
 ## Table of Contents
@@ -34,9 +34,9 @@ Transaction locking is advisory.  Meaning, transactions will all play nice with
 
 The transaction system is designed for JSON records only.  Binary records are not included as part of a transaction, and operations are silently passed straight through.  Meaning, any calls accessing binary records inside of a transaction will result in the original record being changed.  This behavior may be changed in a future version.
 
-Please note that transactions aren't 100% [ACID compliant](https://en.wikipedia.org/wiki/ACID), but they do follow *most* of the rules.  When using the local filesystem engine, the real question is durability, as in what happens in the event of a sudden power loss.  When a transaction is committed, by design it could involve changing a huge amount of files.  While this operation is "effectively atomic" by way of advisory locking, the filesystem may still end up in an unknown state after sudden reboot, for example in the middle of a very large commit.  Now, the system does have automatic recovery using a rollback log, and *should* be able to restore the filesystem to the state right before the commit.  But really, when we're talking about yanking power cords, lightning strikes and brown-outs, who the hell knows.  The rollback log may be incomplete or corrupted (yes, we call [fsync](https://nodejs.org/api/fs.html#fs_fs_fsync_fd_callback) on it before ever starting the commit, but even then, things can happen -- fsync isn't a 100% guarantee, especially with SSDs).
+Please note that transactions aren't 100% [ACID compliant](https://en.wikipedia.org/wiki/ACID), but they do follow *most* of the rules.  When using the local filesystem engine, the real question is durability, as in what happens in the event of a sudden power loss.  When a transaction is committed, by design it could involve changing a huge amount of files.  While this operation is "effectively atomic" by way of advisory locking, the filesystem may still end up in an unknown state after sudden reboot, for example in the middle of a very large commit.  Now, the system does have automatic recovery using a rollback log, and *should* be able to restore the filesystem to the state right before the commit.  But really, when we're talking about yanking power cords, lightning strikes and brown-outs, who the hell knows.  The rollback log may be incomplete or corrupted (yes, we call [fsync](https://nodejs.org/api/fs.html#fsfsyncfd-callback) on it before ever starting the commit, but even then, things can happen -- fsync isn't a 100% guarantee, especially with SSDs).
 
-I guess the bottom line is, always keep backups of your data, and don't use this for anything mission critical.  It is really just a hobby project anyway.  The authors of this software are not responsible for any data loss!
+I guess the bottom line is, always keep backups of your data!
 
 ## Configuration
 
@@ -58,7 +58,7 @@ Choose your `trans_dir` carefully.  This directory is used to store temporary fi
 
 So basically, if you plan to use the [Filesystem](../README.md#local-filesystem) engine with a local (i.e. non-network) disk, you don't need to make any adjustments.  The default setting for `trans_dir` is a subdirectory just inside your `base_dir` engine property.  But if you are going with a networked (i.e. NFS) filesystem, or you're going to use [S3](../README.md#amazon-s3) or [Couchbase](../README.md#couchbase), then you should set `trans_dir` to a local filesystem path on a fast disk (ideally SSD).
 
-**Pro-Tip:** When using transactions with the Amazon S3 engine, consider setting the `maxRetries` property in your `S3` configuration object, so the AWS client library makes multiple attempts before failing an operation.  Network hiccups can happen.
+**Pro-Tip:** When using transactions with the Amazon S3 engine, consider setting the `maxAttempts` property in your `S3` configuration object, so the AWS client library makes multiple attempts before failing an operation.  Network hiccups can happen.
 
 ## Basic Use
 
@@ -86,7 +86,7 @@ The [begin()](API.md#begin) method is asynchronous because obtaining a lock may
 Here is a more comprehensive example, which deposits a sum of money into a fictional bank account.  We are using the [async](https://www.npmjs.com/package/async) module for better flow control.
 
 ```js
-var async = require('async');
+const async = require('async');
 
 storage.begin( 'accounts', function(err, trans) {
 	// transaction has begun, now use 'trans' as storage proxy
@@ -248,7 +248,7 @@ Database recovery is complete.  Please see logs/recovery.log for full details.
 
 You can then start your application normally, i.e. without the `--recover` flag.  Alternatively, if you would prefer that the database automatically recovers and starts up on its own, just add the following property in your `Storage` configuration:
 
-```js
+```json
 {
 	"trans_auto_recover": true
 }
@@ -279,7 +279,7 @@ Inside the temp directory, two subdirectories are created: `data` and `logs`.  T
 
 When a transaction is first started, the only thing that happens is a unique ID is assigned, and a lock is obtained.  Both are based on the path that is passed into [begin()](API.md#begin).  Nothing is written to disk at this point -- that is deferred until actual operations are performed on the transaction object.
 
-Each record that is mutated (created, updated or deleted) inside a transaction is written to a temporary file, and also a ledger is kept in memory to keep track of which records are changed.  The in-memory ledger only contains keys and a "state" character, representing a created, updated or deleted record.  Only records created or updated have an associated temp file on disk.  Deleted records are marked in memory only (no need for a temp file).
+Each record that is mutated (created, updated or deleted) inside a transaction is written to a temporary file, and also a ledger is kept in memory to keep track of which records are changed.  The in-memory ledger only contains keys and a "state", representing a created, updated or deleted record.  Only records created or updated have an associated temp file on disk.  Deleted records are marked in memory only (no need for a temp file).
 
 For example, consider a transaction that begins with path `test1`...
 
@@ -289,7 +289,7 @@ storage.begin( 'test1', function(err, trans) {
 } );
 ```
 
-The transaction ID will be `5a105e8b9d40e1329780d62ea2265d8a` (which is just an MD5 of `test1`).  Now, let's say our `trans_dir` was set to `/var/tmp/db`, and inside our transaction we store a record with key `test1/record1`...
+The transaction ID will be `5a105e8b9d40e1329780d62ea2265d8a` (which is just an MD5 of `test1`).  Now, let's say our `trans_dir` was set to `/let/tmp/db`, and inside our transaction we store a record with key `test1/record1`...
 
 ```js
 trans.put( 'test1/record1', { foo: 12345 }, function(err) {
@@ -300,7 +300,7 @@ trans.put( 'test1/record1', { foo: 12345 }, function(err) {
 So at this point we wrote the `test1/record1` record using our `trans` object, but nothing has happened in the outer storage system (i.e. nothing was written to the primary storage engine).  Instead, the following temp file was written to disk, containing `{"foo":12345}`:
 
 ```
-/var/tmp/db/data/5a105e8b9d40e1329780d62ea2265d8a-0d1454fd1bcdc024acedcbe5cfff4ffd.json
+/tmp/db/data/5a105e8b9d40e1329780d62ea2265d8a-0d1454fd1bcdc024acedcbe5cfff4ffd.json
 ```
 
 The temp filename is made up of the transaction ID (`5a105e8b9d40e1329780d62ea2265d8a`) and the MD5 hash of the record key (`0d1454fd1bcdc024acedcbe5cfff4ffd`).  This is to insure it will not collide with any other records in any other concurrent transactions, doesn't require any further subdirectories, and we can easily retrieve it at commit time if we know the plain key.
@@ -378,7 +378,7 @@ The commit process basically replays all the transaction operations on primary s
 The log will contain the original JSON contents of all the records that will be mutated by the transaction.  It is basically a "snapshot" of the previous state, before we start the commit.  The log goes into the `logs` subdirectory under our `trans_dir` temp directory, and is named using the same Transaction ID hash:
 
 ```
-/var/tmp/db/logs/5a105e8b9d40e1329780d62ea2265d8a.log
+/tmp/db/logs/5a105e8b9d40e1329780d62ea2265d8a.log
 ```
 
 The log file format is plain text with line-delimited JSON for the records.  The first line is a header record that describes the transaction.  Here is an example log: