141 lines
5.4 KiB
Markdown
141 lines
5.4 KiB
Markdown
# PouchORM
|
||
|
||
An ORM for PouchDB inspired by [Hood.ie](https://hood.ie/) and [Django](https://djangoproject.com)
|
||
|
||
## Usage
|
||
|
||
### Type Definition
|
||
|
||
In a type definition class, specify a static `getUniqueID` method and optionally a static `validate`
|
||
method.
|
||
|
||
```js
|
||
import { PouchDB } from 'pouchdb';
|
||
import { TypeSpec } from 'PouchORM';
|
||
|
||
class FileSpec extends TypeSpec {
|
||
static getUniqueID(doc) {
|
||
return doc.digest.substr(0, 16);
|
||
}
|
||
|
||
static validate(doc) {
|
||
const REQUIRED_PROPS = ['filename', 'size', 'digest'];
|
||
const missing_props = REQUIRED_PROPS.filter(prop => !doc.hasOwnProperty(prop));
|
||
if (missing_props) {
|
||
throw new ValidationError('FileType missing required props: ', missing_props);
|
||
}
|
||
}
|
||
}
|
||
|
||
export const FileType = PouchDB.registerType('File', FileSpec);
|
||
```
|
||
|
||
Document properties of a type are not directly defined but the type definition. Specific properties
|
||
can be enforced by the `validate` method. The following properties are illegal:
|
||
|
||
* starting with an underscore (\_) - these are used by PouchDB internally
|
||
* starting with a double dollar-sign ($$) - these are reserved for future use by PouchORM. (Single
|
||
dollar-sign properties may be used for your implementation’s meta-data.)
|
||
|
||
### Type Functions
|
||
|
||
* `FileType.getOrCreate(obj)` - Try to save the passed object as a document. If it fails with a /409
|
||
Conflict/, look up the existing one and return it (ignoring differences between passed object and
|
||
the found object)
|
||
|
||
* /obj/ - an object containing a partial document including an `id` property
|
||
* _Returns_ a FileType instance
|
||
|
||
* `FileType.find(idOrSelector, options)` - Find one or many records. Optionally return a
|
||
subscribeable that will fire events when the selection changes.
|
||
|
||
* /idOrSelector/
|
||
* if a string or number is passed, `find` will attempt to lookup the document with this as the
|
||
id.
|
||
* if an object is passed, it will be treated as a selector for a find query
|
||
* /options/ can have the following optional properties
|
||
* /index/ - specify a specific index to use with the passed selector
|
||
* /live/ - boolean (default /false/) return a subscribeable that will fire when the results of
|
||
the selector are updated.
|
||
* /…/ - other options will be passed to `db.changes()` when `live: true`
|
||
* _Returns_
|
||
* if `options.live` is /false/, an array of FileType instances will be returned
|
||
* if `options.live` is /true/, a subscribeable will be returned. Subscription callbacks will be
|
||
called when the results of /idOrSelector/ changes
|
||
|
||
* `FileType.index(index, fields)` - Create a PouchDB
|
||
[Index](https://pouchdb.com/api.html#create_index) that can be used by `FileType.find` to sort on
|
||
non-ID fields
|
||
|
||
* /index/ - a string value that can optionally be provided to the options object of
|
||
`FileType.find`
|
||
* /fields/ - an array of field names for PouchDB to index on.
|
||
* _Returns_ void
|
||
|
||
* `FileType.delete(id)` - Remove a document from the db
|
||
|
||
* /id/ - the id string of the document to be removed
|
||
* _Returns_ void
|
||
|
||
* `FileType.subscribe(callback)` - subscribe to all FileType changes
|
||
* _Returns_ - a function that unsubscribes the passed callback when called.
|
||
|
||
### Type Properties
|
||
|
||
* `FileType.db` - the PouchDB database used by `FileType`
|
||
* `FileType.name` - the type name passed to the `registerType` function
|
||
* `FileType.prefix` - the prefix used on all document ids stored in PouchDB
|
||
* `FileType.selector` - the PouchDB selector definition used by ‘subscribe’ and ‘find’
|
||
|
||
### Instance Methods
|
||
|
||
Creating a new instance is standard Javascript for any new instance:
|
||
|
||
```js
|
||
let note = new FileType({
|
||
filename: 'note.txt',
|
||
type: 'text/plain'
|
||
});
|
||
```
|
||
|
||
* _static_ `note.getUniqueID(doc)` - You _must override_ this function in your type definition to
|
||
provide the id to be used for this document.
|
||
|
||
* /doc/ - an object representing the document. This could be an instance of the type or a bare
|
||
object with properties for this type.
|
||
* _Returns_ - a unique string value to be used as a document id
|
||
|
||
* _static_ `note.validate()` - By default this does nothing. Optionally override it with a method
|
||
that throws exceptions when a document is invalid to block writing invalid data to the database.
|
||
|
||
* `note.save()` - Calls `validate()` and then writes the document to the database.
|
||
|
||
* _Returns_ - a self-reference to the instance
|
||
|
||
* `note.update(props, save=true)` - Update this instance
|
||
|
||
* /props/ - a deeply nested object that will be applied to this instance
|
||
* /save/ - a boolean to save this document after updating.
|
||
* _Returns_ - a self-reference to the instance
|
||
|
||
* `note.addAttachment(name, blob)` - Add a named attachment to this instance.
|
||
|
||
* /name/ - the name used to reference the attachment
|
||
* /blob/ - a blob instance of the actual data
|
||
* _Returns_ - a self-reference to the instance
|
||
|
||
* `note.getAttachment(name)` - Retrieve a named attachment from this instance.
|
||
|
||
* /name/ - the name of the attachment specified in `addAttachment`
|
||
* _Returns_ - a Blob instance of the attachment data
|
||
|
||
* `note.removeAttachment(name)` - Remove a named attachment from this instance.
|
||
|
||
* /name/ - the name of the attachment specified in `addAttachment`
|
||
* _Returns_ -
|
||
|
||
* `note.delete()` - Flag this document as `_deleted` == `true`. This will cause it to not show up in
|
||
`find` results. (_Note_: documents are left in the database in this state to allow for deletion to
|
||
be synced to other nodes. To truly remove documents,
|
||
[compact your database](https://pouchdb.com/api.html#compaction).)
|