portfolio/packages/pouchorm

PouchORM

An ORM for PouchDB inspired by Hood.ie and Django

Usage

Type Definition

In a type definition class, specify a static getUniqueID method and optionally a static validate method.

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 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:

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.)