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)
**Kind**: instance method of [<code>Cursor</code>](#Cursor)
**Returns**: [<code>Cursor</code>](#Cursor) - <p>the same instance of Cursor, (useful for chaining).</p>
**Params**
**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>
- 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)
**Kind**: instance method of [<code>Cursor</code>](#Cursor)
**Returns**: [<code>Cursor</code>](#Cursor) - <p>the same instance of Cursor, (useful for chaining).</p>
**Params**
**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
- 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>
<aname="Cursor+exec"></a>
### cursor.exec(_callback)
### cursor.exec(_callback)
<p>Get all matching elements
<p>Callback version of [exec](#Cursor+exec).</p>
Will return pointers to matched elements (shallow copies), returning full copies is the role of find or findOne</p>
**Kind**: instance method of [<code>Cursor</code>](#Cursor)
**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)
**Kind**: instance method of [<code>Cursor</code>](#Cursor)
@ -234,7 +232,7 @@ Will return pointers to matched elements (shallow copies), returning full copies
**Params**
**Params**
- err <code>Error</code>
- 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>
<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>
<p>The <code>Executor</code> instance for this <code>Datastore</code>. It is used in all methods exposed by the [Datastore](#Datastore),
produced by the <code>Datastore</code> and by <code>this.persistence.compactDataFile</code>&<code>this.persistence.compactDataFileAsync</code>
any [Cursor](#Cursor) produced by the <code>Datastore</code> and by [compactDatafileAsync](#Datastore+compactDatafileAsync) to ensure operations
to ensure operations are performed sequentially in the database.</p>
are performed sequentially in the database.</p>
**Kind**: instance property of [<code>Datastore</code>](#Datastore)
**Kind**: instance property of [<code>Datastore</code>](#Datastore)
**Access**: protected
**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)
**Kind**: instance method of [<code>Datastore</code>](#Datastore)
**Access**: protected
**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)
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**
**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
- 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
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
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>
<aname="Datastore+remove"></a>
### neDB.remove(query, [options], [cb])
### 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)
**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>
<p>See [updateAsync](#Datastore+updateAsync) return type for the definition of the callback parameters.</p>
<ul>
<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.
<li>For an upsert, the upserted document</li>
<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>
<li>For an update with returnUpdatedDocs option false, null</li>
<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
<li>For an update with returnUpdatedDocs true and multi false, the updated document</li>
during a <code>{ multi: false, returnUpdatedDocs: true, upsert: true }</code> update if it inserted a document or just updated
<li>For an update with returnUpdatedDocs true and multi true, the array of updated documents</li>
it.</p>
</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>
**Kind**: inner typedef of [<code>Datastore</code>](#Datastore)
**Kind**: inner typedef of [<code>Datastore</code>](#Datastore)
**See**: {Datastore#updateAsync}
**Params**
**Params**
- err <code>Error</code>
- 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
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
in the one-line-per-document format) every time you load each database within
your application.</p>
your application.</p>
<p>You can manually call the compaction function
<p>Persistence handles the compaction exposed in the Datastore [compactDatafileAsync](#Datastore+compactDatafileAsync),
with <code>yourDatabase.persistence.compactDatafile</code> which takes no argument. It
@ -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>
- [.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>
- [.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
## [3.0.0] - Unreleased
### Added
### Added
- Added an async interface for all functions
- Added a `Promise`-based interface.
- The JSDoc is now much more exhaustive
- The JSDoc is now much more exhaustive.
- Added markdown documentation generated from the JSDoc
- An auto-generated JSDoc file is generated: [API.md](./API.md).
- Added `Datastore#dropDatabaseAsync` and its callback equivalent.
### Changed
### 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 `Datastore#update`'s callback has its signature slightly changed. The
- 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.
`upsert` flag is always defined either at `true` or `false` but not `null` nor
- 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.
`undefined`, and `affectedDocuments` is `null` when none is given rather than
- 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).
`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:
### Deprecated
- Datastore:
- Formally deprecate giving a string as argument to the `Datastore` constructor
- `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