sorla-db 1.1.0 → 1.3.0

package/README.md

@@ -3,24 +3,34 @@ A simple and temporary database focused to use in browser environment that will
 
 This idea is from our founder #andmarruda that give this idea and alot of this idea are developed by him.
 
-To create a minify file run
+## Installation
+
 ```
-node index.js
+npm install sorla-db
 ```
 
-To test the environment using jest run...
-Don`t forget to install the dev dependecies before, using:
-
+```js
+// Node / bundlers
+const sorla = require('sorla-db');
+// or
+import sorla from 'sorla-db';
 ```
-npm install --only=dev
+
+```html
+<!-- browser, 9.5 kB: registers window.sorla -->
+<script src="https://cdn.jsdelivr.net/npm/sorla-db@1/dist/sorla.min.js"></script>
 ```
 
+TypeScript declarations are included.
+
+## Development
+
 ```
-npm test
+npm install
+npm test          # jest
+npm run build     # dist/sorla.min.js
 ```
 
-Soon some documentations....
-
 Prohibited characters $ and .,
 $ because is used to call operators and . because uses to search key inside a object's object
 
@@ -42,6 +52,123 @@ window.sorla.db.updatedTags.insertMany([
 ]);
 ```
 
+## Inserting documents
+
+`insertOne` stores a **copy** of the document and returns its `_id` (a uuid v4 when the document
+has none). `insertMany` validates the whole array first, so an invalid document never leaves the
+collection with half of the batch, and returns the ids.
+
+```
+const id = window.sorla.db.updatedTags.insertOne({ name: 'Ana', nickname: null });
+const ids = window.sorla.db.updatedTags.insertMany([{ name: 'Bia' }, { _id: 'custom', name: 'Caio' }]);
+```
+
+- `null` values are allowed, at any depth
+- a duplicated `_id` throws
+- keys with `$` or `.` throw, at any depth
+- values must be cloneable (no functions or DOM nodes)
+
+Documents returned by the collection are read-only: assigning a field throws.
+
+## Reading results
+
+`find()` returns a cursor:
+
+```
+const cursor = window.sorla.db.updatedTags.find({ age: { $gte: 18 } });
+cursor.length;              // number of documents
+cursor.first();             // data of the first one, null when empty
+cursor.last();              // data of the last one, null when empty
+cursor.toArray();           // plain copies
+while(cursor.hasNext()) cursor.next();
+```
+
+`findOne()` returns the data of the first matching document, or `null`.
+
+## Sorting
+
+```
+window.sorla.db.updatedTags.find({}).sort({ age: -1, name: 1 }).toArray();
+```
+
+`1` is ascending and `-1` descending, and `"a.b"` paths work. `sort()` returns the cursor. Values of
+different types follow MongoDB's order: missing and null, numbers, strings, objects, arrays,
+booleans, dates. Strings compare by code point. Pass a collation to compare by language rules,
+using the `Intl.Collator` options:
+
+```
+cursor.sort({ name: 1 }, { collation: { locale: 'pt-BR', sensitivity: 'base', numeric: true } });
+```
+
+## Paging and projection
+
+```
+collection.find({}).sort({ age: 1 }).skip(20).limit(10).toArray();
+collection.find({}, { name: 1, age: 1 });   // only name, age and _id
+collection.find({}, { name: 1, _id: 0 });   // only name
+collection.find({}, { password: 0 });       // everything except password
+```
+
+`limit(0)` means no limit. Inclusion and exclusion cannot be mixed (except `_id`), and projection
+works on top level fields.
+
+## Updating documents
+
+```
+collection.updateOne({ _id: id }, { $set: { 'address.city': 'Recife' }, $inc: { visits: 1 } });
+collection.updateMany({ active: false }, { $unset: { token: '' } });
+collection.updateOne({ email: 'a@b.c' }, { $set: { name: 'Ana' } }, { upsert: true });
+```
+
+| Operator | Effect |
+|---|---|
+| `$set` | sets fields, creating missing objects of `"a.b"` paths |
+| `$unset` | removes fields |
+| `$inc` | adds a number (missing fields start at 0) |
+| `$push` | appends to an array, `{ $push: { tags: { $each: ['a', 'b'] } } }` appends several |
+| `$pull` | removes array items equal to a value, matching a condition (`{ $in: [...] }`) or a sub document (`{ ok: false }`) |
+
+They return `{ matchedCount, modifiedCount, upsertedId }`. Updates are applied to a copy first: if an
+operator fails (for example `$inc` on a text field) no document changes. `_id` cannot change. With
+`{ upsert: true }`, a document is inserted from the equality conditions of the filter when nothing matches.
+
+`replaceOne(filter, document)` replaces the whole document and keeps its `_id`.
+
+## Deleting and counting
+
+```
+collection.deleteOne({ _id: id });         // { deletedCount: 1 }
+collection.deleteMany({ age: { $lt: 18 } });
+collection.deleteMany({});                 // empties the collection
+collection.count();                        // every document
+collection.count({ active: true });        // matching documents, without copying them
+```
+
+## Change events
+
+```
+const off = collection.on('change', event => {
+  // event.type: 'insert' | 'update' | 'replace' | 'delete'
+  // event.ids, event.documents (copies), event.previous (before update / replace)
+});
+collection.on('delete', event => console.log(event.ids));
+off();
+```
+
+`insertMany` and `updateMany` emit one event for the whole operation, and nothing is emitted when nothing
+changed. A listener that throws does not undo or interrupt the write.
+
+## Databases and collections
+
+```
+sorla.listDatabases();            // ['tags', ...]
+sorla.dropDb('tags');
+sorla.db.listCollections();       // ['updatedTags', ...]
+sorla.db.getCollection('stats');  // any collection, also when its name shadows a method
+sorla.db.dropCollection('updatedTags');
+sorla.db.getStats();              // { name, documents, collections: [{ name, documents }] }
+```
+
 ## Find Operators
 
 ### $and
@@ -138,6 +265,22 @@ A document without the queried field does not match `$eq`, `$gt`, `$in`... but d
 
 Unknown operators and logical operators that do not receive an array throw an error.
 
+### $regex
+Matches strings with a regular expression. `$options` takes the flags `i` (case insensitive), `m` and `s`.
+A RegExp can be used directly as the value. Array fields match when one of their strings does.
+
+```
+const results = window.sorla.db.updatedTags.find({ name: { $regex: '^an', $options: 'i' } });
+const same = window.sorla.db.updatedTags.find({ name: /^an/i });
+```
+
+### $exists
+`{ field: { $exists: true } }` matches documents that have the field, even when it is `null`;
+`false` matches documents without it.
+
+### Arrays
+Equality is strict: `{ tags: 'dev' }` does not match `tags: ['dev']`. Use `{ tags: { $in: ['dev'] } }`.
+
 ## Comparison operators
 
 ### $eq