rewrite Readme

CHANGELOG.md

@@ -10,6 +10,7 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ### Added
 - Added an async interface for all functions
 - The JSDoc is now much more exhaustive
+- Added markdown documentation generated from the JSDoc
 
 ### Changed
 - All the functions are now async at the core, and a fully retro-compatible callback-ified version is exposed.

docs/byline.md

@@ -0,0 +1,10 @@
+<a name="module_byline"></a>
+
+## byline
+<a name="module_byline.LineStream"></a>
+
+### byline.LineStream
+<p>Fork from [https://github.com/jahewson/node-byline](https://github.com/jahewson/node-byline).</p>
+
+**Kind**: static class of [<code>byline</code>](#module_byline)  
+**See**: https://github.com/jahewson/node-byline  

jsdoc2md.js

@@ -29,6 +29,7 @@ const templateData = jsdoc2md.getTemplateDataSync(getJsdocDataOptions)
 const classNames = templateData
   .filter(({ kind, access }) => kind === 'class' && access !== 'private')
   .map(({ name }) => name)
+  .filter(name => name !== 'LineStream') // it is a module that exports a class, dirty hack to hardcode this, but it works
 
 const moduleNames = templateData
   .filter(({ kind, access }) => kind === 'module' && access !== 'private')

lib/byline.js

@@ -19,7 +19,9 @@
 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 // IN THE SOFTWARE.
-
+/**
+ * @module byline
+ */
 const stream = require('stream')
 const timers = require('timers')
 
@@ -31,6 +33,11 @@ const createLineStream = (readStream, options) => {
   return ls
 }
 
+/**
+ * Fork from {@link https://github.com/jahewson/node-byline}.
+ * @see https://github.com/jahewson/node-byline
+ * @alias module:byline.LineStream
+ */
 class LineStream extends stream.Transform {
   constructor (options) {
     super(options)

lib/datastore.js

@@ -132,10 +132,13 @@ class Datastore extends EventEmitter {
   /**
    * Create a new collection, either persistent or in-memory.
    *
-   * If you use a persistent datastore without the `autoload` option, you need to call `loadDatabase` manually. This
-   * function fetches the data from datafile and prepares the database. **Don't forget it!** If you use a persistent
-   * datastore, no command (insert, find, update, remove) will be executed before `loadDatabase` is called, so make sure
-   * to call it yourself or use the `autoload` option.
+   * If you use a persistent datastore without the `autoload` option, you need to call {@link Datastore#loadDatabase} or
+   * {@link Datastore#loadDatabaseAsync} manually. This function fetches the data from datafile and prepares the database.
+   * **Don't forget it!** If you use a persistent datastore, no command (insert, find, update, remove) will be executed
+   * before it is called, so make sure to call it yourself or use the `autoload` option.
+   *
+   * Also, if loading fails, all commands registered to the {@link Datastore#executor} afterwards will not be executed.
+   * They will be registered and executed, in sequence, only after a successful loading.
    *
    * @param {object|string} options Can be an object or a string. If options is a string, the behavior is the same as in
    * v0.6: it will be interpreted as `options.filename`. **Giving a string is deprecated, and will be removed in the

lib/persistence.js

@@ -7,7 +7,40 @@ const model = require('./model.js')
 const storage = require('./storage.js')
 
 /**
- * Handle every persistence-related task
+ * Under the hood, NeDB's persistence uses an append-only format, meaning that all
+ * updates and deletes actually result in lines added at the end of the datafile,
+ * for performance reasons. The database is automatically compacted (i.e. put back
+ * in the one-line-per-document format) every time you load each database within
+ * your application.
+ *
+ * You can manually call the compaction function
+ * with `yourDatabase.persistence.compactDatafile` which takes no argument. It
+ * queues a compaction of the datafile in the executor, to be executed sequentially
+ * after all pending operations. The datastore will fire a `compaction.done` event
+ * once compaction is finished.
+ *
+ * You can also set automatic compaction at regular intervals
+ * with `yourDatabase.persistence.setAutocompactionInterval(interval)`, `interval`
+ * in milliseconds (a minimum of 5s is enforced), and stop automatic compaction
+ * with `yourDatabase.persistence.stopAutocompaction()`.
+ *
+ * Keep in mind that compaction takes a bit of time (not too much: 130ms for 50k
+ * records on a typical development machine) and no other operation can happen when
+ * it does, so most projects actually don't need to use it.
+ *
+ * Compaction will also immediately remove any documents whose data line has become
+ * corrupted, assuming that the total percentage of all corrupted documents in that
+ * database still falls below the specified `corruptAlertThreshold` option's value.
+ *
+ * Durability works similarly to major databases: compaction forces the OS to
+ * physically flush data to disk, while appends to the data file do not (the OS is
+ * responsible for flushing the data). That guarantees that a server crash can
+ * never cause complete data loss, while preserving performance. The worst that can
+ * happen is a crash between two syncs, causing a loss of all data between the two
+ * syncs. Usually syncs are 30 seconds appart so that's at most 30 seconds of
+ * data. [This post by Antirez on Redis persistence](http://oldblog.antirez.com/post/redis-persistence-demystified.html)
+ * explains this in more details, NeDB being very close to Redis AOF persistence
+ * with `appendfsync` option set to `no`.
  */
 class Persistence {
   /**

test/db.test.js

@@ -2253,6 +2253,7 @@ describe('Database', function () {
 
         fs.writeFile(testDb, rawData, 'utf8', function () {
           d.loadDatabase(function (err) {
+            err.should.not.equal(null)
             err.errorType.should.equal('uniqueViolated')
             err.key.should.equal('1')
             d.getAllData().length.should.equal(0)