- removeById(id: string): Promise
- remove(item: T): Promise

- upsert(item: T, deltaFunc?: (existing: T) => T): Promise

- bulkUpsert(items: T[]): Promise<(Response|Error)[]>
- bulkRemove(items: T[]): Promise<(Response|Error)[]>

Class Validation

The validation uses the class-validator library, and should work anywhere that PouchDB works. This can
be turned on at the global PouchORM level using PouchORM.VALIDATE or at the collection level when creating
a new instance of PouchCollection.

By default, upsert calls PouchORM.getClassValidator() when validation is turned on. This dynamically
imports to PouchORM.ClassValidator with the full instance of the required library. The method can also be
called at any time so that class validation methods, decorators, and so on may used your application without
the need to statically import the library. However, if class-validator has not been installed to
node_modules, this will crash PouchORM when PouchORM.getClassValidator() is called and/or you attempt
to use PouchORM.ClassValidator.

For complete details and advanced usage of class-validator, see their documentation.

PouchORM metadata

PouchORM adds some metadata fields to each documents to make certain features possible.
Key of which are $timestamp and $collectionType.

$3

This gets updated with a unix timestamp upon upserting a document. This is also auto-indexed for time-sensitive ordering
(i.e so items don't show up in random locations in results each time, which can be disconcerting)

$3

There is no concept of tables or collections in PouchDB. Only databases. This field helps us differentiate what
collection each document belongs to. This is also auto-indexed for your convenience.

$3

PouchORM can help you append a userId to each originating change to specify who changed a document last.
Simply use PouchORM.setUserId(...) to specify who the local/active user is, and PouchORM will put that id here.
If this is not set, this field will be ...

If you need more stringent audit log capabilities, that's something you should implement for your application.

Custom ID generation

You can control the way IDs are generated for new items. Just define the idGenerator function property in a
collection object. This can be a normal or async function that returns a string.

`typescript
import {personCollection} from '...'


personCollection.idGenerator = (item) => {
return 'randomIdString';
};

const p = await personCollection.upsert({...})
p._id === 'randomIdString' // true

`

You can also do:

`typescript
personCollection.idGenerator = async (item) => {
const anotherString = await someAsyncIDStringBuilder()
return anotherString;
};

// or better yet, cleanly override the property in the class for consistency

export class PersonCollection extends PouchCollection {

// override
async idGenerator(){
return 'randomIdString';
}
}

`

Installing PouchDB plugins

You can access the base PouchDB module used by PouchORM with PouchORM.PouchDB. You can install plugins you need with
that e.g PouchORM.PouchDB.plugin(...). PouchORM already comes with the plugin pouchdb-find which is essential for
any useful querying of the database.

Accessing the raw pouchdb database

Every instance has a reference to the internally instantiated db collectionInstance.db that you can use to reference
other methods of the raw pouch db instance e.g personCollection.db.putAttachment(...).

You can use this for anything that does not directly involve accessing documents e.g adding an attachment is fine.
But caution must be followed when you want to use this to manipulate a document directly, as pouch orm marks documents with
helpful metadata it uses to enhance your development experience, particularly $timestamp and $collectionType.

It is generally better to rely on the exposed functions in your collection instance.

If you want more pouchdb feature support, feel free to open an issue. This library is also very simple
to grok, so feel free to send in a PR!

Deleting the Database

`
import {PouchORM} from 'pouchorm'
...
PouchORM.deleteDatabase(dbName: string)
`
It goes without saying that this cannot be undone, so be careful with this!
Also, any loaded PouchCollection instances you still have will now throw the error "database is destroyed" if you try to run any DB access operations on them.

Realtime Sync!

Last but not least, PouchDB is all about sync.
You could always access the native Pouch DB object and run sync operations.

But as of v1.5, some sugar has been added to make this a simplified PouchORM experience as well.

Introducing PouchORM.startSync(fromPath, toPath, opts) where either paths could
be local paths/names or a remote db url path. Within opts, you can specify callbacks that trigger upon specific events
during the realtime sync e.g onChange, onError,onStart, etc. Have a look at the reference.

You can also cancel real-time sync by PouchORM.stopSync(fromPath, toPath?)`. If the second parameter is null, it will stop all sync ops for that db regardless of destination.

Supporting the Project

Contributors

- Iyobo Eki
- Aaron Huggins