update JSDoc, readme, remove jquery and jsdoc from dependencies, remove sources from jsdoc.conf.js which conflicts with --files from jsdoc2md, implement dropDatabase & tests
<p>Sort results of the query for the given Cursor.</p>
**Kind**: instance method of [<code>Cursor</code>](#Cursor)
**Returns**: [<code>Cursor</code>](#Cursor) - <p>the same instance of Cursor, (useful for chaining).</p>
**Params**
- sortQuery <code>Object.<string, number></code> - <p>sortQuery is { field: order }, field can use the dot-notation, order is 1 for ascending and -1 for descending</p>
@ -191,9 +188,10 @@ The <code>beforeDeserialization</code> should revert what <code>afterDeserializa
<p>Add the use of a projection to the given Cursor.</p>
**Kind**: instance method of [<code>Cursor</code>](#Cursor)
**Returns**: [<code>Cursor</code>](#Cursor) - <p>the same instance of Cursor, (useful for chaining).</p>
**Params**
- projection <code>Object.<string, number></code> - <p>MongoDB-style projection. {} means take all fields. Then it's { key1: 1, key2: 1 } to take only key1 and key2
@ -202,10 +200,10 @@ The <code>beforeDeserialization</code> should revert what <code>afterDeserializa
<aname="Cursor+exec"></a>
### cursor.exec(_callback)
<p>Get all matching elements
Will return pointers to matched elements (shallow copies), returning full copies is the role of find or findOne</p>
<p>Callback version of [exec](#Cursor+exec).</p>
**Kind**: instance method of [<code>Cursor</code>](#Cursor)
Will return pointers to matched elements (shallow copies), returning full copies is the role of [findAsync](#Datastore+findAsync) or [findOneAsync](#Datastore+findOneAsync).</p>
**Kind**: instance method of [<code>Cursor</code>](#Cursor)
@ -234,7 +232,7 @@ Will return pointers to matched elements (shallow copies), returning full copies
**Params**
- err <code>Error</code>
- res [<code>Array.<document></code>](#document) | <code>\*</code> - <p>If an mapFn was given to the Cursor, then the type of this parameter is the one returned by the mapFn.</p>
- res [<code>Array.<document></code>](#document) | <code>\*</code> - <p>If a mapFn was given to the Cursor, then the type of this parameter is the one returned by the mapFn.</p>
<aname="Datastore"></a>
@ -258,12 +256,18 @@ Will return pointers to matched elements (shallow copies), returning full copies
<p>The <code>Executor</code> instance for this <code>Datastore</code>. It is used in all methods exposed by the <code>Datastore</code>, any <code>Cursor</code>
produced by the <code>Datastore</code> and by <code>this.persistence.compactDataFile</code>&<code>this.persistence.compactDataFileAsync</code>
to ensure operations are performed sequentially in the database.</p>
<p>The <code>Executor</code> instance for this <code>Datastore</code>. It is used in all methods exposed by the [Datastore](#Datastore),
any [Cursor](#Cursor) produced by the <code>Datastore</code> and by [compactDatafileAsync](#Datastore+compactDatafileAsync) to ensure operations
are performed sequentially in the database.</p>
**Kind**: instance property of [<code>Datastore</code>](#Datastore)
**Access**: protected
@ -407,6 +411,41 @@ letters. Native <code>localCompare</code> will most of the time be the right cho
**Kind**: instance method of [<code>Datastore</code>](#Datastore)
**Access**: protected
<aname="Datastore+compactDatafileAsync"></a>
### neDB.compactDatafileAsync()
<p>Queue a compaction/rewrite of the datafile.
It works by rewriting the database file, and compacts it since the cache always contains only the number of
documents in the collection while the data file is append-only so it may grow larger.</p>
**Kind**: instance method of [<code>Datastore</code>](#Datastore)
<aname="Datastore+compactDatafile"></a>
### neDB.compactDatafile([callback])
<p>Callback version of [compactDatafileAsync](#Datastore+compactDatafileAsync).</p>
**Kind**: instance method of [<code>Datastore</code>](#Datastore)
<p>Callback version of [updateAsync](#Datastore+updateAsync).</p>
**Kind**: instance method of [<code>Datastore</code>](#Datastore)
**See**: Datastore#updateAsync
**Params**
- query [<code>query</code>](#query) - <p>is the same kind of finding query you use with <code>find</code> and <code>findOne</code></p>
- update [<code>document</code>](#document) | <code>\*</code> - <p>specifies how the documents should be modified. It is either a new document or a
set of modifiers (you cannot use both together, it doesn't make sense!). Using a new document will replace the
matched docs. Using a set of modifiers will create the fields they need to modify if they don't exist, and you can
apply them to subdocs. Available field modifiers are <code>$set</code> to change a field's value, <code>$unset</code> to delete a field,
<code>$inc</code> to increment a field's value and <code>$min</code>/<code>$max</code> to change field's value, only if provided value is
less/greater than current value. To work on arrays, you have <code>$push</code>, <code>$pop</code>, <code>$addToSet</code>, <code>$pull</code>, and the special
<li><code>upsert</code> is <code>true</code> if and only if the update did insert a document, <strong>cannot be true if <code>options.upsert !== true</code></strong>.</li>
<li><code>numAffected</code> is the number of documents affected by the update or insertion (if <code>options.multi</code> is <code>false</code> or <code>options.upsert</code> is <code>true</code>, cannot exceed <code>1</code>);</li>
<li><code>affectedDocuments</code> can be one of the following:
<ul>
<li>If <code>upsert</code> is <code>true</code>, the inserted document;</li>
<li>If <code>options.returnUpdatedDocs</code> is <code>false</code>, <code>null</code>;</li>
<li>If <code>options.returnUpdatedDocs</code> is <code>true</code>:
<ul>
<li>If <code>options.multi</code> is <code>false</code>, the updated document;</li>
<li>If <code>options.multi</code> is <code>false</code>, the array of updated documents.</li>
</ul>
</li>
</ul>
</li>
</ul>
**Params**
- query [<code>query</code>](#query) - <p>is the same kind of finding query you use with <code>find</code> and <code>findOne</code></p>
- query [<code>query</code>](#query) - <p>is the same kind of finding query you use with <code>find</code> and <code>findOne</code>.</p>
- update [<code>document</code>](#document) | <code>\*</code> - <p>specifies how the documents should be modified. It is either a new document or a
set of modifiers (you cannot use both together, it doesn't make sense!). Using a new document will replace the
matched docs. Using a set of modifiers will create the fields they need to modify if they don't exist, and you can
@ -646,27 +708,27 @@ if the update did not actually modify them.</p>
<aname="Datastore+remove"></a>
### neDB.remove(query, [options], [cb])
<p>Remove all docs matching the query.</p>
<p>Callback version of [removeAsync](#Datastore+removeAsync).</p>
**Kind**: instance method of [<code>Datastore</code>](#Datastore)
<p>If update was an upsert, <code>upsert</code> flag is set to true, <code>affectedDocuments</code> can be one of the following:</p>
<ul>
<li>For an upsert, the upserted document</li>
<li>For an update with returnUpdatedDocs option false, null</li>
<li>For an update with returnUpdatedDocs true and multi false, the updated document</li>
<li>For an update with returnUpdatedDocs true and multi true, the array of updated documents</li>
</ul>
<p><strong>WARNING:</strong> The API was changed between v1.7.4 and v1.8, for consistency and readability reasons. Prior and
including to v1.7.4, the callback signature was (err, numAffected, updated) where updated was the updated document
in case of an upsert or the array of updated documents for an update if the returnUpdatedDocs option was true. That
meant that the type of affectedDocuments in a non multi update depended on whether there was an upsert or not,
leaving only two ways for the user to check whether an upsert had occured: checking the type of affectedDocuments
or running another find query on the whole dataset to check its size. Both options being ugly, the breaking change
was necessary.</p>
<p>See [updateAsync](#Datastore+updateAsync) return type for the definition of the callback parameters.</p>
<p><strong>WARNING:</strong> Prior to 3.0.0, <code>upsert</code> was either <code>true</code> of falsy (but not <code>false</code>), it is now always a boolean.
<code>affectedDocuments</code> could be <code>undefined</code> when <code>returnUpdatedDocs</code> was <code>false</code>, it is now <code>null</code> in these cases.</p>
<p><strong>WARNING:</strong> Prior to 1.8.0, the <code>upsert</code> argument was not given, it was impossible for the developer to determine
during a <code>{ multi: false, returnUpdatedDocs: true, upsert: true }</code> update if it inserted a document or just updated
it.</p>
**Kind**: inner typedef of [<code>Datastore</code>](#Datastore)
**See**: {Datastore#updateAsync}
**Params**
- err <code>Error</code>
@ -739,16 +796,10 @@ 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.</p>
<p>You can manually call the compaction function
with <code>yourDatabase.persistence.compactDatafile</code> 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 <code>compaction.done</code> event
once compaction is finished.</p>
<p>You can also set automatic compaction at regular intervals
with <code>yourDatabase.persistence.setAutocompactionInterval(interval)</code>, <code>interval</code>
in milliseconds (a minimum of 5s is enforced), and stop automatic compaction
with <code>yourDatabase.persistence.stopAutocompaction()</code>.</p>
<p>Keep in mind that compaction takes a bit of time (not too much: 130ms for 50k
<p>Persistence handles the compaction exposed in the Datastore [compactDatafileAsync](#Datastore+compactDatafileAsync),
@ -794,127 +835,35 @@ with <code>appendfsync</code> option set to <code>no</code>.</p>
- [.beforeDeserialization] [<code>serializationHook</code>](#serializationHook) - <p>Hook you can use to transform data after it was serialized and before it is written to disk.</p>
- [.afterSerialization] [<code>serializationHook</code>](#serializationHook) - <p>Inverse of <code>afterSerialization</code>.</p>
@ -8,18 +8,51 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [3.0.0] - Unreleased
### Added
- Added an async interface for all functions
- The JSDoc is now much more exhaustive
- Added markdown documentation generated from the JSDoc
- Added a `Promise`-based interface.
- The JSDoc is now much more exhaustive.
- An auto-generated JSDoc file is generated: [API.md](./API.md).
- Added `Datastore#dropDatabaseAsync` and its callback equivalent.
### Changed
- All the functions are now async at the core, and a fully retro-compatible callback-ified version is exposed for the exposed functions.
- The executor is now much simpler and Promise-based. A mostly retro-compatible shim is still exposed, with the exception that it no longer handles [`arguments`](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Functions/arguments) as the arguments Array. If you use the executor directly, you'll need to convert it to a proper Array beforehand. However [follicle@1.x](https://github.com/seald/follicle) is not compatible, please update to v2.
- As a result, the `async` dependency has been removed completely. To avoid rewriting the tests, shims of some functions of `async` are defined in an utilities file used exclusively in the tests.
- The `Datastore#update`'s callback has its signature slightly changed. The `upsert` flag is always defined either at `true` or `false` but not `null` nor `undefined`, and `affectedDocuments` is `null` when none is given rather than `undefined` (except when there is an error of course).
-
### Deprecated
- Formally deprecate giving a string as argument to the `Datastore` constructor
- The `Datastore#update`'s callback has its signature slightly changed. The
`upsert` flag is always defined either at `true` or `false` but not `null` nor
`undefined`, and `affectedDocuments` is `null` when none is given rather than
`undefined` (except when there is an error of course).
- In order to expose a `Promise`-based interface and to remove `async` from the dependencies, many internals have been either rewritten or removed:
- Datastore:
- `Datastore#getCandidates` replaced with `Datastore#_getCandidatesAsync`;
- `Datastore#resetIndexes` replaced with `Datastore#_resetIndexes`;
- `Datastore#addToIndexes` replaced with `Datastore#_addToIndexes`;
- `Datastore#removeFromIndexes` replaced with `Datastore#_removeFromIndexes`;
- `Datastore#updateIndexes` replaced with `Datastore#_updateIndexes`;
- `Datastore#_insert` replaced with `Datastore#_insertAsync`;
- `Datastore#_update` replaced with `Datastore#_updateAsync`;
- `Datastore#_remove` replaced with `Datastore#_removeAsync`;
- Persistence:
- `Persistence#loadDatabase` replaced with `Persistence#loadDatabaseAsync`;
- `Persistence#persistCachedDatabase` replaced with `Persistence#persistCachedDatabaseAsync`;
- `Persistence#persistNewState` replaced with `Persistence#persistNewStateAsync`;
- `Persistence#treatRawStream` replaced with `Persistence#treatRawStreamAsync`;
- `Persistence.ensureDirectoryExists` replaced with `Persistence#ensureDirectoryExistsAsync`;
- Cursor:
- `Cursor#_exec` replaced with `Cursor#_execAsync`;
- `Cursor#project` replaced with `Cursor#_project`;
- `Cursor#execFn` has been renamed to `Cursor#mapFn` and no longer supports a callback in its signature, it must be a synchronous function.
- Executor: it has been rewritten entirely without the `async`library.
- `Executor#buffer`&`Executor#queue` do not have the same signatures as before;
- `Executor#push` replaced with `Executor#pushAsync` which is substantially different;
- Storage modules : callback-based functions have been replaced with promise-based functions.
- Model module: it has been slightly re-written for clarity, but no changes in its interface was made.
## Deprecated
- Using a `string` in the constructor of NeDB is now deprecated.
- Using `Datastore#persistence#compactDatafile` is now deprecated, please use `Datastore#compactDatafile` instead.
- Using `Datastore#persistence#setAutocompactionInterval` is now deprecated, please use `Datastore#setAutocompactionInterval` instead.
- Using `Datastore#persistence#stopAutocompaction` is now deprecated, please use `Datastore#stopAutocompaction` instead.
## Removed
- The option for passing `options.nodeWebkitAppName` to the Datastore and the Persistence constructors has been removed.
deprecate(callback=>this.db.compactDatafile(callback),'@seald-io/nedb: calling Datastore#persistence#compactDatafile is deprecated, please use Datastore#compactDatafile, it will be removed in the next major version.')(callback)
deprecate(interval=>this.db.setAutocompactionInterval(interval),'@seald-io/nedb: calling Datastore#persistence#setAutocompactionInterval is deprecated, please use Datastore#setAutocompactionInterval, it will be removed in the next major version.')(interval)
deprecate(()=>this.db.stopAutocompaction(),'@seald-io/nedb: calling Datastore#persistence#stopAutocompaction is deprecated, please use Datastore#stopAutocompaction, it will be removed in the next major version.')()
Timothée Rebours
3 years ago