api.md

#class: Fireproof Members

• class: Fireproof
  • new Fireproof(firebaseRef)
  • Fireproof.setNextTick(nextTick)
  • Fireproof.bless(Q)
  • fireproof._wrapAuth(fn)
  • fireproof.child(childPath)
  • fireproof.parent()
  • fireproof.root()
  • fireproof.toFirebase()
  • fireproof.name()
  • fireproof.key()
  • fireproof.toString()
  • fireproof.auth(authToken, [onComplete], [options])
  • fireproof.authWithCustomToken(authToken, [onComplete], [options])
  • fireproof.authAnonymously([onComplete], [options])
  • fireproof.authWithPassword(credentials, [onComplete], [options])
  • fireproof.authWithOAuthPopup(provider, [onComplete], [options])
  • fireproof.authWithOAuthRedirect(provider, [onComplete], [options])
  • fireproof.authWithOAuthPopup(provider, credentials, [onComplete], [options])
  • fireproof.getAuth()
  • fireproof.onAuth(onComplete, [context])
  • fireproof.offAuth(onComplete, [context])
  • fireproof.unauth()
  • fireproof.onDisconnect()
    • onDisconnect.cancel([callback])
    • onDisconnect.remove([callback])
    • onDisconnect.set(value, [callback])
    • onDisconnect.setWithPriority(value, priority, [callback])
    • onDisconnect.update(value, [callback])
  • fireproof.limit(limit)
  • fireproof.limitToFirst(limit)
  • fireproof.limitToLast(limit)
  • fireproof.orderByChild(key)
  • fireproof.orderByKey()
  • fireproof.orderByValue()
  • fireproof.orderByPriority()
  • fireproof.equalTo(value, [key])
  • fireproof.startAt(value, [key])
  • fireproof.endAt(value, [key])
  • fireproof.ref()
  • fireproof.transaction(updateFunction, onComplete, [applyLocally])
  • fireproof.on(eventType, callback, [cancelCallback], [context])
  • fireproof.off(eventType, [callback], [context])
  • fireproof.once(eventType, successCallback, [failureCallback], [context])
  • fireproof.createUser(credentials, [onComplete])
  • fireproof.changeEmail(credentials, [onComplete])
  • fireproof.changePassword(credentials, [onComplete])
  • fireproof.resetPassword(credentials, [onComplete])
  • fireproof.createUser(credentials, [onComplete])
  • fireproof.set(value, [onComplete])
  • fireproof.update(value, [onComplete])
  • fireproof.remove([onComplete])
  • fireproof.push(value, [onComplete])
  • fireproof.setWithPriority(value, priority, [onComplete])
  • fireproof.setPriority(priority, [onComplete])
  • Fireproof.stats
    • stats.reset()
    • stats.getListeners()
    • stats.getListenerCount()
    • stats.getPathCounts()
    • stats.getCounts()
    • stats.on(name, fn)
    • stats.off([name], fn)
  • class: Fireproof.Demux
    • new Fireproof.Demux(refs, [limitToFirst])
    • demux.get(count)
  • class: Fireproof.LiveArray
    • new Fireproof.LiveArray([errorHandler])
    • liveArray.connect([ref], [sortMode], [sortProperty])
    • liveArray.disconnect()
  • class: Fireproof.Pager
    • new Fireproof.Pager(ref, [initialCount])
    • pager.next(count)
    • pager.previous(count)

##new Fireproof(firebaseRef) Fireproofs an existing Firebase reference, giving it magic promise powers.

Params

• firebaseRef Firebase - A Firebase reference object.

Properties

• then - A promise shortcut for .once('value'), except for references created by .push(), where it resolves on success and rejects on failure of the property object.

Example
var fp = new Fireproof(new Firebase('https://test.firebaseio.com/something')); fp.then(function(snap) { console.log(snap.val()); });

##Fireproof.setNextTick(nextTick) Tell Fireproof to use a given function to set timeouts from now on. NB: If you are using AMD/require.js, you MUST call this function!

Params

• nextTick function - a function that takes a function and runs it in the immediate future.

##Fireproof.bless(Q) Tell Fireproof to use a given promise library from now on.

Params

• Q Q - a Q-style promise constructor with mandatory .all() and optional defer().

##fireproof._wrapAuth(fn) Wraps auth methods so they execute in order.

Params

• fn function - Auth function that generates a promise once it's done.

##fireproof.child(childPath) Delegates Firebase#child, wrapping the child in fireproofing.

Params

• childPath string - The subpath to refer to.

Returns: Fireproof - A reference to the child path.
##fireproof.parent() Delegates Firebase#parent, wrapping the child in fireproofing.

Returns: Fireproof - A ref to the parent path, or null if there is none.
##fireproof.root() Delegates Firebase#root, wrapping the root in fireproofing.

Returns: Fireproof - A ref to the root.
##fireproof.toFirebase() Hands back the original Firebase reference.

Returns: Firebase - The proxied Firebase reference.
##fireproof.name() Delegates Firebase#name.

Returns: string - The last component of this reference object's path.
##fireproof.key() Delegates Firebase#key.

Returns: string - The last component of this reference object's path.
##fireproof.toString() Delegates Firebase#toString.

Returns: string - The full URL of this reference object.
##fireproof.auth(authToken, [onComplete], [options]) Delegates Firebase#auth.

Params

• authToken String
• [onComplete] function
• [options] Object

Returns: Promise - that resolves on auth success and rejects on auth failure.
##fireproof.authWithCustomToken(authToken, [onComplete], [options]) Delegates Firebase#authWithCustomToken.

Params

• authToken String
• [onComplete] function
• [options] Object

Returns: Promise - that resolves on auth success and rejects on auth failure.
##fireproof.authAnonymously([onComplete], [options]) Delegates Firebase#authAnonymously.

Params

• [onComplete] function
• [options] Object

Returns: Promise - that resolves on auth success and rejects on auth failure.
##fireproof.authWithPassword(credentials, [onComplete], [options]) Delegates Firebase#authWithPassword.

Params

• credentials Object - Should include email and password.
• [onComplete] function
• [options] Object

Returns: Promise - that resolves on auth success and rejects on auth failure.
##fireproof.authWithOAuthPopup(provider, [onComplete], [options]) Delegates Firebase#authWithOAuthPopup.

Params

• provider String
• [onComplete] function
• [options] Object

Returns: Promise - that resolves on auth success and rejects on auth failure.
##fireproof.authWithOAuthRedirect(provider, [onComplete], [options]) Delegates Firebase#authWithOAuthRedirect.

Params

• provider String
• [onComplete] function
• [options] Object

Returns: Promise - that resolves on auth success and rejects on auth failure.
##fireproof.authWithOAuthPopup(provider, credentials, [onComplete], [options]) Delegates Firebase#authWithOAuthPopup.

Params

• provider String
• credentials Object
• [onComplete] function
• [options] Object

Returns: Promise - that resolves on auth success and rejects on auth failure.
##fireproof.getAuth() Delegates Firebase#getAuth.

Returns: Object - user info object, or null otherwise.
##fireproof.onAuth(onComplete, [context]) Delegates Firebase#onAuth.

Params

• onComplete function - Gets called on auth change.
• [context] Object

##fireproof.offAuth(onComplete, [context]) Delegates Firebase#offAuth.

Params

• onComplete function - The function previously passed to onAuth.
• [context] Object

##fireproof.unauth() Delegates Firebase#unauth.

##fireproof.onDisconnect() Delegates Fireproof#onDisconnect.

Returns: Fireproof.OnDisconnect
##fireproof.limit(limit) Delegates Firebase#limit.

Params

• limit Number

Returns: Fireproof
##fireproof.limitToFirst(limit) Delegates Firebase#limitToFirst.

Params

• limit Number

Returns: Fireproof
##fireproof.limitToLast(limit) Delegates Firebase#limitToLast.

Params

• limit Number

Returns: Fireproof
##fireproof.orderByChild(key) Delegates Firebase#orderByChild.

Params

• key string

Returns: Fireproof
##fireproof.orderByKey() Delegates Firebase#orderByKey.

Returns: Fireproof
##fireproof.orderByValue() Delegates Firebase#orderByValue.

Returns: Fireproof
##fireproof.orderByPriority() Delegates Firebase#orderByPriority.

Returns: Fireproof
##fireproof.equalTo(value, [key]) Delegates Firebase#equalTo.

Params

• value String | Number | null
• [key] String

Returns: Fireproof
##fireproof.startAt(value, [key]) Delegates Firebase#startAt.

Params

• value object
• [key] string

Returns: Fireproof
##fireproof.endAt(value, [key]) Delegates Firebase#endAt.

Params

• value object
• [key] string

Returns: Fireproof
##fireproof.ref() Delegates Firebase#ref.

Returns: Fireproof
##fireproof.transaction(updateFunction, onComplete, [applyLocally]) Delegates Firebase#transaction.

Params

• updateFunction function
• onComplete function
• [applyLocally] boolean

Returns: Promise - an Object with two properties: 'committed' and 'snapshot'.
##fireproof.on(eventType, callback, [cancelCallback], [context]) Delegates Firebase#on.

Params

• eventType string - 'value', 'child_added', 'child_changed', 'child_moved', or 'child_removed'
• callback function
• [cancelCallback] function
• [context] object

Returns: function - Your callback parameter wrapped in fireproofing. Use this return value, not your own copy of callback, to call .off(). It also functions as a promise that resolves with a {FireproofSnapshot}.
##fireproof.off(eventType, [callback], [context]) Delegates Firebase#off.

Params

• eventType string
• [callback] function
• [context] object

##fireproof.once(eventType, successCallback, [failureCallback], [context]) Delegates Firebase#once.

Params

• eventType object - 'value', 'child_added', 'child_changed', 'child_moved', or 'child_removed'
• successCallback function
• [failureCallback] function
• [context] object

Returns: Promise - Resolves with {FireproofSnapshot}.
##fireproof.createUser(credentials, [onComplete]) Delegates Firebase#createUser.

Params

• credentials Object
• [onComplete] function

Returns: Promise
##fireproof.changeEmail(credentials, [onComplete]) Delegates Firebase#changeEmail.

Params

• credentials Object
• [onComplete] function

Returns: Promise
##fireproof.changePassword(credentials, [onComplete]) Delegates Firebase#changePassword.

Params

• credentials Object
• [onComplete] function

Returns: Promise
##fireproof.resetPassword(credentials, [onComplete]) Delegates Firebase#resetPassword.

Params

• credentials Object
• [onComplete] function

Returns: Promise
##fireproof.createUser(credentials, [onComplete]) Delegates Firebase#removeUser.

Params

• credentials Object
• [onComplete] function

Returns: Promise
##fireproof.set(value, [onComplete]) Delegates Firebase#set.

Params

• value object - The value to set this path to.
• [onComplete] function - Callback when the operation is done.

Returns: Promise
Example

fireproofRef.set('something')
.then(function()) {
  console.log('set was successful!');
}, function(err) {
  console.error('error while setting:', err);
});

##fireproof.update(value, [onComplete]) Delegates Firebase#update.

Params

• value object - An object with keys and values to update.
• [onComplete] function - Callback when the operation is done.

Returns: Promise
##fireproof.remove([onComplete]) Delegates Firebase#remove.

Params

• [onComplete] function - Callback when the operation is done.

Returns: Promise
##fireproof.push(value, [onComplete]) Delegates Firebase#push.

Params

• value object - An object with keys and values to update.
• [onComplete] function - Callback when the operation is done.

Returns: Promise
##fireproof.setWithPriority(value, priority, [onComplete]) Delegates Firebase#setWithPriority.

Params

• value object - The value to set this path to.
• priority object - The priority to set this path to.
• [onComplete] function - Callback when the operation is done.

Returns: Promise
##fireproof.setPriority(priority, [onComplete]) Delegates Firebase#setPriority.

Params

• priority object - The priority to set this path to.
• [onComplete] function - Callback when the operation is done.

Returns: Promise
##Fireproof.stats Statistics about Firebase usage.

Properties

• operationLog Object
• runningOperationCount Number
• operationCount Number
• listenCount Number

Members

• Fireproof.stats
  • stats.reset()
  • stats.getListeners()
  • stats.getListenerCount()
  • stats.getPathCounts()
  • stats.getCounts()
  • stats.on(name, fn)
  • stats.off([name], fn)

###stats.reset() Resets the count of Firebase operations back to 0.

###stats.getListeners() Gets data about listeners on Firebase locations.

Returns: Object - Listener counts keyed by Firebase path.
###stats.getListenerCount() Gets the total number of listeners on Firebase locations.

Returns: Number - The total number of Firebase listeners presently operating.
###stats.getPathCounts() Gets the per-operation, per-path counts of Firebase operations.

Returns: Object - An object with keys like "listen", "readOnce", "write", and "update". Each key has an object value, of which the keys are Firebase paths and the values are counts.
###stats.getCounts() Gets the per-operation counts of Firebase operations.

Returns: Object - An object with with keys like "read", "write", and "update". The values are the counts of operations under those headings.
###stats.on(name, fn) Listens for Firebase events occurring.

Params

• name String - The name of the event. One of 'start', 'finish', 'error', 'listenStarted', or 'listenEnded.'
• fn function - The function to call when the event happens. Takes a single parameter, the event object.

Returns: function - fn is returned for convenience, to pass to off.
###stats.off([name], fn) Stops sending events to a listener.

Params

• [name] String - The name of the event. One of 'start', 'finish', 'error', 'listenStarted', or 'listenEnded.'
• fn function - The function to stop calling.

##class: Fireproof.Demux Members

• class: Fireproof.Demux
  • new Fireproof.Demux(refs, [limitToFirst])
  • demux.get(count)

###new Fireproof.Demux(refs, [limitToFirst]) A helper object for retrieving sorted Firebase objects from multiple locations.

Params

• refs Array - a list of Fireproof object references to draw from.
• [limitToFirst] boolean - Whether to use "limitToFirst" to restrict the length of queries to Firebase. True by default. Set this to false if you want to control the query more directly by setting it on the objects you pass to refs.

###demux.get(count) Get the next count items from the paths, ordered by priority.

Params

• count Number - The number of items to get from the list.

Returns: Promise - A promise that resolves with the next count items, ordered by priority.
##class: Fireproof.LiveArray Members

• class: Fireproof.LiveArray
  • new Fireproof.LiveArray([errorHandler])
  • liveArray.connect([ref], [sortMode], [sortProperty])
  • liveArray.disconnect()

###new Fireproof.LiveArray([errorHandler]) A live array that keeps its members in sync with a Firebase location's children. The three array references, keys, values, and priorities, are guaranteed to persist for the lifetime of the array. In other words, the arrays themselves are constant; only their contents are mutable. This is highly useful behavior for dirty-checking environments like Angular.js.

Params

• [errorHandler] function - a function to be called if a Firebase error occurs.

Properties

• keys Array - A live array of the keys at the Firebase ref.
• values Array - A live array of the values at the Firebase ref.
• priorities Array - A live array of the priorities at the Firebase ref.

###liveArray.connect([ref], [sortMode], [sortProperty]) Connect this LiveArray to a Firebase reference, instantiating listeners for child events. If an error is received from a Firebase listener, all listeners are disconnected, LiveArray#error is set, and your error handler is called if you supplied one.

Params

• [ref] Fireproof - a Firebase ref whose children you wish to sync to.
• [sortMode] String - "key", "priority", or "child".
• [sortProperty] String - The name of the child property to sort on, if sortMode is "child".

###liveArray.disconnect() Disconnect this LiveArray from a Firebase reference, removing all listeners. Also clears the contents of the live array references.

##class: Fireproof.Pager Members

• class: Fireproof.Pager
  • new Fireproof.Pager(ref, [initialCount])
  • pager.next(count)
  • pager.previous(count)

###new Fireproof.Pager(ref, [initialCount]) A helper object for paging over Firebase objects.

Params

• ref Fireproof - a Firebase ref whose children you wish to page over.
• [initialCount] Number - The number of objects in the first page.

Properties

• hasPrevious Boolean - True if there are more objects before the current page.
• hasNext Boolean - True if there are more objects after the current page.

###pager.next(count) Get the next page of children from the ref.

Params

• count Number - The size of the page.

Returns: Promise - A promise that resolves with an array of the next children.
###pager.previous(count) Get the previous page of children from the ref.

Params

• count Number - The size of the page.

Returns: Promise - A promise that resolves with an array of the next children.