Bucket API

CloudWall provides access to buckets, listed in profile. Bucket constructor is ready after cw.start() Promise was successfully resolved. Calling cw.db('bucketId') returns object, which is basically augmented PouchDB instance, extended with several CloudWall-specific methods.

Methods that return Promise are marked with ⚑ (black flag).
Methods that return EventEmitter are marked with ⚐ (white flag). 

CloudWall extensions

Invocation of cw.db returns shallow copy of particular bucket object prototype. It means each bucket object instance is safely expandable and may be changed independently.

db.acl( appid, type, action )

Returns access-control related lists. By default access control policies are hard-coded in the .config.acl property of a build design doc. 

Depending on arguments number, method returns object, array or boolean:

db.actions( type )

Returns object, that represents doctype → doc action → app mapping. Called without arguments returns entire mapping tree.

db.app( appName )

Finds application manifest by app name. Searches first in DB appcache, then in appcache of system DB, then in system cache.

db.att( docid )

Return Att object if doc was already cached. Att object has 5 members:

The action function name is 'data''image', 'url' or  'blob'. Result is _attachment object, augmented with data in appropriate format, and data itself.

Filename can be array of names, name as string or null — then all attaches are read in format requested.

Format of object returned depends on function name. In general, object returned is very same to doc’s _attachments doc branch, but every file object has additional property.
 .data returns base64 data ⚑,
 .image — base64 with prefix data:mime/type;base64,... attached ⚑,
 .url — dataURL, temporary session string reference to resource ⚑.
 .blob returns native DB format — binary Blob object ⚑.

db.del( docid ) ⚑

Deletes doc by docid.

db.find( filter ) ⚑

Iterates filter function over each doc in DB. If filter returns true or any sorting key casting to true, doc is pushed to resulting collection. All docs found are immediately cached. Promise is resolved with an array of docs, sorted by sorting key, if function provided one, or by _id.

Example code fetches all ToDo-s that were saved more than 5 times.

Method is very slow in Chrome and Opera, 50-100 times slower than in FF or Safari.

db.form( manId )

Returns manifest by qualified component id like cw.Post.Editor.Cropper. This method is just proxy to cw.form().

db.hide( docId )

Marks doc as hidden. It means doc won’t be deleted from DB, but become nearly invisible for apps — excluded from queries results, doc lists and so on.

db.load( args ) ⚑

Loads and caches doc or docs. All necessery events are raised and watchers notified. There are several possible combinations of arguments and their types:

Promise is rejected on error with (errorMessage, errorObj).

Docs loaded has several extensions over standard CouchDB doc format.

db.markread( docId )

Marks cached document as read in current revision. State if doc was read and in what revision is stored in system DB of each user. When doc is loaded, this state mounted as _read property of doc. 

It’s useful for indication that doc, that received new revision, was not read. System doc list shows such updates with blue highlight.

Attributing doc as read raises doc update events, however doc itself does not change.

db.isread( docId )

Checks if cached doc was read (opened) in current revision. See db.markread and db.hide.

db.name

String, DB id.

db.ram( arg )

Queries RAM cache, not a promise. Argument can be _id, array of _ids or filter function. Method is not a promise and returns array of results immediately.

db.inram( docId )

Checks if doc is cached in RAM. Returns true if doc was loaded. 

db.save( doc, silent ) ⚑

Saves (creates) doc. If silent is true, no info message is shown on finish. To create doc just save it without _rev, and, possibly, _id properties.

If conflict occurs during save and silent is false, modal for user intervention is shown. If conflict occured and silent is true, promise is rejected with error.

Promise is resolved with new doc, which is immediately reloaded after save and cached. 

If doc to save has no name or type fields, or is pre-encrypted (has CRYPTO  property) promise is rejected. 

If doc to save has field crypto with valid keyId, doc is encrypted with the key before save. Promise is resolved with encrypted doc this case — unlike this.app.save(), which decrypts doc saved.

System settings doc can not be saved using db.save method.

db.settings( settings ) ⚑

Updates settings for the bucket, returns Promise resolved with success text message.

db.settings( stringKey )

Returns stringKey member of bucket settings object. If no key provided, entire bucket settings object is returned.

If replication URLs have credentials, they are returned with passwords sealed.

db.sync( arg )

If no arg provided, returns current status of bucket replications, which is object where keys are sync id-s, and values are stamps when next sync (re)start is scheduled. 

If boolean provided as arg, starts or stops bucket replication.

db.uuid()

Returns stamp-based new doc uuid.

db.watch( docType ) ⚐

Returns EventEmitter instance, which raises progress event when doc(s) of docType were just changed. If no docType provided, watcher called on any doc change.

Event listeners receive a list of changed docs.

Unlike native Pouch db.on('evt', fn), listeners mounted using watch().progress() are called with a little debounce, and receive an array to avoid jitter. 

PouchDB native methods

Bucket object inherits most of documented PouchDB methods nearly as is. Destructive methods like db.close and db.destroy are however removed. Also db.sync method is augmented and has another meaning.

Write methods are restricted to respect bucket .readOnly property, although _local/...  docs are always writable.

db.info() ⚑

Returns Promise, resolved with CouchDB-style bucket low-level info object.

db.compact() ⚑

Compacts DB, returns Promise resolved on compaction finish.

db.allDocs( {opts} ) ⚑

Returns Promise resolved with list of all bucket docs. Exact amount of info provided, as well as particular ranges or _ids may be defined by opts. By default only list of pairs _id/_rev for entire bucket is returned. 

db.bulkDocs ( [docs], opts) ⚑

Creates or updates multiple documents of docs array.

db.get ( _id, {opts} ) ⚑

Returns Promise, resolved with requested doc with additional fields according to options:

db.put( doc ) ⚑

Saves doc to bucket.

db.post( doc ) ⚑

Creates new document with auto-generated doc _id.

db.query( func ) ⚑

PouchDB internal method of querying DB. 

db.getAttachment ( _id, fname ) ⚑

PouchDB methods, raw DB read. Results are never placed in cache, no events raised and no app watchers notified. Not recommended in most cases.

db.putAttachment( _id, fname, data, mime ) ⚑

PouchDB methods, raw DB write. Not recommended in most cases, but can be useful while resolving update conflicts.

db.replicate.to( target, opts )

Starts replication to target, which may be local bucket or remote CouchDB endpoint. Returns event emitter.

db.replicate.from( source, opts )

Starts replication to target, which may be local bucket or remote CouchDB endpoint. Returns event emitter.