Merge pull request #34 from typicode/0.7.0

Update to lodash 3.0.1

README.md

@@ -1,54 +1,50 @@
-# LowDB [![Build Status](https://travis-ci.org/typicode/lowdb.svg?branch=master)](https://travis-ci.org/typicode/lowdb) [![](https://img.shields.io/npm/v/lowdb.svg?style=flat)](https://www.npmjs.com/package/lowdb)
+# lowdb [![NPM version](https://badge.fury.io/js/lowdb.svg)](http://badge.fury.io/js/lowdb) [![Build Status](https://travis-ci.org/typicode/lowdb.svg?branch=master)](https://travis-ci.org/typicode/lowdb)
 
-> Flat JSON file database for Node
+> Need a quick way to get a local database?
 
-* Serverless
-* Multiple databases
-* In-memory or disk-based
-* 80+ methods from Lo-Dash API
-* Atomic writing
-* Extendable
-
-LowDB uses Lo-Dash functional programming API instead of a MongoDB-like API. This makes it quite unique and different.
-
-_LowDB powers [JSON Server](https://github.com/typicode/json-server) and [JSONPlaceholder](http://jsonplaceholder.typicode.com/). See also [underscore-db](https://github.com/typicode/underscore-db)._
-
-## Usage
+## Example
 
 ```javascript
 var low = require('lowdb')
 var db = low('db.json')
 
-db('songs').push({ title: 'low!'})
+db('posts').push({ title: 'lowdb is awesome'})
 ```
 
-Database is automatically created and saved to `db.json` in a readable format.
+Database is __automatically__ saved to `db.json`
 
 ```javascript
 {
-  "songs": [
-    {
-      "title": "low!"
-    }
+  "posts": [
+    { "title": "lowdb is awesome" }
   ]
 }
 ```
 
-Data can be queried and manipulated using any Lo-Dash method.
+You can query and manipulate it using __any lodash 3.0 method__.
 
 ```javascript
-var song = db('songs').find({ title: 'low!' }).value()
-db('songs').remove({ title: 'low!' })
+db('posts').find({ title: 'lowdb is awesome' })
 ```
 
-You can also use id-based methods by extending LowDB with [Underscore-db](https://github.com/typicode/underscore-db).
-
 ## Install
 
 ```bash
 npm install lowdb --save 
 ````
 
+## Features
+
+* Small
+* Serverless
+* lodash rich API
+* In-memory or disk-based
+* __Hackable__ (mixins, id, encryption, ...)
+
+It's also __very easy to learn and use__ since it has __only 8 methods and properties__.
+
+_lowdb powers [json-server](https://github.com/typicode/json-server) package and [jsonplaceholder](http://jsonplaceholder.typicode.com/) website._
+
 ## API
 
 __low([filename, options])__
@@ -64,24 +60,25 @@ When a filename is provided you can set options.
 
 ```javascript
 var db = low('db.json', {
-  autosave: true, // changes are automatically written to file (true by default)
-  async: true     // changes are written synchronously or asynchronously (true by default)
+  autosave: true, // automatically save database on change (default: true)
+  async: true     // asyncrhonous write (default: true)
 })
 ```
 
 __low.mixin(source)__
 
-Use it to extend Lo-Dash globally with your own utility functions or third-party libraries.
+Use it to extend lodash globally with your own utility functions or third-party libraries.
 
 ```javascript
 // Must be called before calling db('songs') for functions to be available.
 low.mixin({
   second: function(array) {
-    if (array.length >= 2) return array[1]
+    return array[1]
   }
 })
 
-var song = db('songs').second().value()
+var song1 = db('songs').first()
+var song2 = db('songs').second()
 ```
 
 __low.stringify(obj)__ and __low.parse(str)__
@@ -118,18 +115,21 @@ __db.saveSync([filename])__
 
 Synchronous version of `db.save()`
 
-## Documentation
+## Guide
 
 ### Operations
 
-With LowDB you get access to the entire [Lo-Dash API](http://lodash.com/), so there's many, many ways to query and manipulate data. Here are a few examples to get you started.
+With LowDB you get access to the entire [lodash API](http://lodash.com/), so there's many ways to query and manipulate data. Here are a few examples to get you started.
 
-Please note also that data is returned by reference, this means that modifications to returned objects may change the database. To avoid such behaviour, you need to use `.cloneDeep().value()`.
+Please note that data is returned by reference, this means that modifications to returned objects may change the database. To avoid such behaviour, you need to use `.cloneDeep()`.
+
+Also, the execution of chained methods is lazy, that is, execution is deferred until `.value()` is called.
 
 Sort the top five songs.
 
 ```javascript
 db('songs')
+  .chain()
   .where({published: true})
   .sortBy('views')
   .first(5)
@@ -139,9 +139,7 @@ db('songs')
 Retrieve song titles.
 
 ```javascript
-db('songs')
-  .pluck('titles')
-  .value()
+db('songs').pluck('titles')
 ```
 
 Get the number of songs.
@@ -153,13 +151,17 @@ db('songs').size()
 Make a deep clone of songs.
 
 ```javascript
-db('songs').cloneDeep().value()
+db('songs').cloneDeep()
 ```
 
 Update a song.
 
 ```javascript
-db('songs').find({ title: 'low!' }).assign({ title: 'hi!'})
+db('songs')
+  .chain()
+  .find({ title: 'low!' })
+  .assign({ title: 'hi!'})
+  .value()
 ```
 
 Remove songs.
@@ -168,40 +170,48 @@ Remove songs.
 db('songs').remove({ title: 'low!' })
 ```
 
-### Id-based resources support
+### Id support
 
-Being able to retrieve data using an id can be quite useful, particularly in servers. To add id-based resources support to LowDB, you have 2 options.
+Being able to retrieve data using an id can be quite useful, particularly in servers. To add id-based resources support to lowdb, you have 2 options.
 
-[Underscore-db](https://github.com/typicode/underscore-db) provides a set of helpers for creating and manipulating id-based resources.
+[underscore-db](https://github.com/typicode/underscore-db) provides a set of helpers for creating and manipulating id-based resources.
 
 ```javascript
 low.mixin(require('underscore-db'))
 
 var db = low('db.json')
 
-var songId = db('songs').insert({ title: 'low!' }).value().id
-var song   = db('songs').get(songId).value()
+var songId = db('songs').insert({ title: 'low!' }).id
+var song   = db('songs').get(songId)
 ```
 
-Or simply use [uuid](https://github.com/broofa/node-uuid).
+[uuid](https://github.com/broofa/node-uuid) returns a unique id.
 
 ```javascript
 var uuid = require('uuid')
 
-var songId = db('songs').push({ id: uuid(), title: 'low!' }).value().id
-var song   = db('songs').find({ id: songId }).value()
+var songId = db('songs').push({ id: uuid(), title: 'low!' }).id
+var song   = db('songs').find({ id: songId })
 ```
 
-In both cases, your `db.json` will then look like this.
+### Encryption support
+
+In some cases, you may want to make it harder to read database content. By overwriting, `low.stringify` and `low.parse`, you can add custom encryption.
 
 ```javascript
-{
-  "songs": [
-    {
-      "id": "e31aa48c-a9d8-4f79-9fce-ded4c16c3c4c",
-      "title": "low!"
-    }
-  ]
+var crypto = require('crypto')
+
+var cipher = crypto.createCipher('aes256', secretKey)
+var decipher = crypto.createDecipher('aes256', secretKey)
+
+low.stringify = function(obj) {
+  var str = JSON.stringify(obj)
+  return cipher.update(str, 'utf8', 'hex') + cipher.final('hex')
+}
+
+low.parse = function(encrypted) {
+  var str = decipher.update(encrypted, 'hex', 'utf8') + decipher.final('utf8')
+  return JSON.parse(str)
 }
 ```
 
@@ -211,10 +221,10 @@ See details changes for each version in the [release notes](https://github.com/t
 
 ## Limits
 
-LowDB is a convenient method for storing data without setting up a database server. It's fast enough and safe to be used as an embedded database.
+lowdb is a convenient method for storing data without setting up a database server. It's fast enough and safe to be used as an embedded database.
 
 However, if you need high performance and scalability more than simplicity, you should stick to databases like MongoDB.
 
 ## License
 
-LowDB is released under the MIT License.
+MIT - [Typicode](https://github.com/typicode)

package.json

@@ -1,10 +1,11 @@
 {
   "name": "lowdb",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Flat JSON file database",
   "keywords": [
     "flat",
     "file",
+    "local",
     "database",
     "JSON",
     "lo-dash",
@@ -30,13 +31,14 @@
   },
   "homepage": "https://github.com/typicode/lowdb",
   "dependencies": {
-    "lodash": "~2.4.1",
-    "steno": "^0.3.1"
+    "lodash": "^3.0.1",
+    "steno": "^0.3.2"
   },
   "devDependencies": {
     "husky": "^0.6.2",
     "mocha": "^1.21.4",
     "rimraf": "^2.2.8",
+    "sinon": "^1.12.2",
     "underscore-db": "^0.8.0"
   }
 }

src/disk.js

@@ -0,0 +1,34 @@
+var fs = require('fs')
+var path = require('path')
+var _ = require('lodash')
+var steno = require('steno')
+
+function getTempFile(file) {
+  return path.join(
+    path.dirname(file),
+    '.~' + path.basename(file)
+  )
+}
+
+module.exports = {
+  read: function (file) {
+    if (fs.existsSync(file)) return fs.readFileSync(file)
+  },
+
+  write: function(file, data) {
+    steno(getTempFile(file))
+      .setCallback(function(err, data, next) {
+        if (err) throw err
+        fs.rename(getTempFile(file), file, function(err) {
+          if (err) throw err
+          next()
+        })
+      })
+      .write(data)
+  },
+
+  writeSync: function(file, data) {
+    fs.writeFileSync(getTempFile(file), data)
+    fs.renameSync(getTempFile(file), file)
+  }
+}