Skip to content

Latest commit

 

History

History
872 lines (675 loc) · 34.9 KB

api.md

File metadata and controls

872 lines (675 loc) · 34.9 KB

Fireproof

Kind: global class
Properties

Name Description
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.

new Fireproof(firebaseRef)

Fireproofs an existing Firebase reference, giving it magic promise powers.

Param Type Description
firebaseRef Firebase A Firebase reference object.

Example

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

fireproof.child(childPath) ⇒ Fireproof

Delegates Firebase#child, wrapping the child in fireproofing.

Kind: instance method of Fireproof
Returns: Fireproof - A reference to the child path.

Param Type Description
childPath string The subpath to refer to.

fireproof.parent() ⇒ Fireproof

Delegates Firebase#parent, wrapping the child in fireproofing.

Kind: instance method of Fireproof
Returns: Fireproof - A ref to the parent path, or null if there is none.

fireproof.root() ⇒ Fireproof

Delegates Firebase#root, wrapping the root in fireproofing.

Kind: instance method of Fireproof
Returns: Fireproof - A ref to the root.

fireproof.toFirebase() ⇒ Firebase

Hands back the original Firebase reference.

Kind: instance method of Fireproof
Returns: Firebase - The proxied Firebase reference.

fireproof.name() ⇒ string

Delegates Firebase#name.

Kind: instance method of Fireproof
Returns: string - The last component of this reference object's path.

fireproof.key() ⇒ string

Delegates Firebase#key.

Kind: instance method of Fireproof
Returns: string - The last component of this reference object's path.

fireproof.toString() ⇒ string

Delegates Firebase#toString.

Kind: instance method of Fireproof
Returns: string - The full URL of this reference object.

fireproof._wrapAuth(fn)

Wraps auth methods so they execute in order.

Kind: instance method of Fireproof

Param Type Description
fn function Auth function that generates a promise once it's done.

fireproof.auth(authToken, [onComplete], [options]) ⇒ Promise

Delegates Firebase#auth.

Kind: instance method of Fireproof
Returns: Promise - that resolves on auth success and rejects on auth failure.

Param Type
authToken String
[onComplete] function
[options] Object

fireproof.authWithCustomToken(authToken, [onComplete], [options]) ⇒ Promise

Delegates Firebase#authWithCustomToken.

Kind: instance method of Fireproof
Returns: Promise - that resolves on auth success and rejects on auth failure.

Param Type
authToken String
[onComplete] function
[options] Object

fireproof.authAnonymously([onComplete], [options]) ⇒ Promise

Delegates Firebase#authAnonymously.

Kind: instance method of Fireproof
Returns: Promise - that resolves on auth success and rejects on auth failure.

Param Type
[onComplete] function
[options] Object

fireproof.authWithPassword(credentials, [onComplete], [options]) ⇒ Promise

Delegates Firebase#authWithPassword.

Kind: instance method of Fireproof
Returns: Promise - that resolves on auth success and rejects on auth failure.

Param Type Description
credentials Object Should include email and password.
[onComplete] function
[options] Object

fireproof.authWithOAuthPopup(provider, [onComplete], [options]) ⇒ Promise

Delegates Firebase#authWithOAuthPopup.

Kind: instance method of Fireproof
Returns: Promise - that resolves on auth success and rejects on auth failure.

Param Type
provider String
[onComplete] function
[options] Object

fireproof.authWithOAuthRedirect(provider, [onComplete], [options]) ⇒ Promise

Delegates Firebase#authWithOAuthRedirect.

Kind: instance method of Fireproof
Returns: Promise - that resolves on auth success and rejects on auth failure.

Param Type
provider String
[onComplete] function
[options] Object

fireproof.authWithOAuthPopup(provider, credentials, [onComplete], [options]) ⇒ Promise

Delegates Firebase#authWithOAuthPopup.

Kind: instance method of Fireproof
Returns: Promise - that resolves on auth success and rejects on auth failure.

Param Type
provider String
credentials Object
[onComplete] function
[options] Object

fireproof.getAuth() ⇒ Object

Delegates Firebase#getAuth.

Kind: instance method of Fireproof
Returns: Object - user info object, or null otherwise.

fireproof.onAuth(onComplete, [context])

Delegates Firebase#onAuth.

Kind: instance method of Fireproof

Param Type Description
onComplete function Gets called on auth change.
[context] Object

fireproof.offAuth(onComplete, [context])

Delegates Firebase#offAuth.

Kind: instance method of Fireproof

Param Type Description
onComplete function The function previously passed to onAuth.
[context] Object

fireproof.unauth()

Delegates Firebase#unauth.

Kind: instance method of Fireproof

fireproof.onDisconnect() ⇒ Fireproof.OnDisconnect

Delegates Fireproof#onDisconnect.

Kind: instance method of Fireproof

onDisconnect.cancel([callback]) ⇒ Promise

Delegates onDisconnect()#cancel.

Kind: instance method of onDisconnect

Param Type Description
[callback] function Firebase callback.

onDisconnect.remove([callback]) ⇒ Promise

Delegates onDisconnect()#remove.

Kind: instance method of onDisconnect

Param Type Description
[callback] function Firebase callback.

onDisconnect.set(value, [callback]) ⇒ Promise

Delegates onDisconnect()#set.

Kind: instance method of onDisconnect

Param Type Description
value * Value to set on the ref on disconnect.
[callback] function Firebase callback.

onDisconnect.setWithPriority(value, priority, [callback]) ⇒ Promise

Delegates onDisconnect()#setWithPriority.

Kind: instance method of onDisconnect

Param Type Description
value * Value to set on the ref on disconnect.
priority * Priority to set on the ref on disconnect.
[callback] function Firebase callback.

onDisconnect.update(value, [callback]) ⇒ Promise

Delegates onDisconnect()#update.

Kind: instance method of onDisconnect

Param Type Description
value * Value to update on the ref on disconnect.
[callback] function Firebase callback.

fireproof.limit(limit) ⇒ Fireproof

Delegates Firebase#limit.

Kind: instance method of Fireproof

Param Type
limit Number

fireproof.limitToFirst(limit) ⇒ Fireproof

Delegates Firebase#limitToFirst.

Kind: instance method of Fireproof

Param Type
limit Number

fireproof.limitToLast(limit) ⇒ Fireproof

Delegates Firebase#limitToLast.

Kind: instance method of Fireproof

Param Type
limit Number

fireproof.orderByChild(key) ⇒ Fireproof

Delegates Firebase#orderByChild.

Kind: instance method of Fireproof

Param Type
key string

fireproof.orderByKey() ⇒ Fireproof

Delegates Firebase#orderByKey.

Kind: instance method of Fireproof

fireproof.orderByValue() ⇒ Fireproof

Delegates Firebase#orderByValue.

Kind: instance method of Fireproof

fireproof.orderByPriority() ⇒ Fireproof

Delegates Firebase#orderByPriority.

Kind: instance method of Fireproof

fireproof.equalTo(value, [key]) ⇒ Fireproof

Delegates Firebase#equalTo.

Kind: instance method of Fireproof

Param Type
value String | Number | null
[key] String

fireproof.startAt(value, [key]) ⇒ Fireproof

Delegates Firebase#startAt.

Kind: instance method of Fireproof

Param Type
value object
[key] string

fireproof.endAt(value, [key]) ⇒ Fireproof

Delegates Firebase#endAt.

Kind: instance method of Fireproof

Param Type
value object
[key] string

fireproof.ref() ⇒ Fireproof

Delegates Firebase#ref.

Kind: instance method of Fireproof

fireproof.transaction(updateFunction, onComplete, [applyLocally]) ⇒ Promise

Delegates Firebase#transaction.

Kind: instance method of Fireproof
Returns: Promise - an Object with two properties: 'committed' and 'snapshot'.

Param Type
updateFunction function
onComplete function
[applyLocally] boolean

fireproof.on(eventType, callback, [cancelCallback], [context]) ⇒ function

Delegates Firebase#on.

Kind: instance method of Fireproof
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}.

Param Type Description
eventType string 'value', 'child_added', 'child_changed', 'child_moved', or 'child_removed'
callback function
[cancelCallback] function
[context] object

fireproof.off(eventType, [callback], [context])

Delegates Firebase#off.

Kind: instance method of Fireproof

Param Type
eventType string
[callback] function
[context] object

fireproof.once(eventType, successCallback, [failureCallback], [context]) ⇒ Promise

Delegates Firebase#once.

Kind: instance method of Fireproof
Returns: Promise - Resolves with {FireproofSnapshot}.

Param Type Description
eventType object 'value', 'child_added', 'child_changed', 'child_moved', or 'child_removed'
successCallback function
[failureCallback] function
[context] object

fireproof.createUser(credentials, [onComplete]) ⇒ Promise

Delegates Firebase#createUser.

Kind: instance method of Fireproof

Param Type
credentials Object
[onComplete] function

fireproof.changeEmail(credentials, [onComplete]) ⇒ Promise

Delegates Firebase#changeEmail.

Kind: instance method of Fireproof

Param Type
credentials Object
[onComplete] function

fireproof.changePassword(credentials, [onComplete]) ⇒ Promise

Delegates Firebase#changePassword.

Kind: instance method of Fireproof

Param Type
credentials Object
[onComplete] function

fireproof.resetPassword(credentials, [onComplete]) ⇒ Promise

Delegates Firebase#resetPassword.

Kind: instance method of Fireproof

Param Type
credentials Object
[onComplete] function

fireproof.createUser(credentials, [onComplete]) ⇒ Promise

Delegates Firebase#removeUser.

Kind: instance method of Fireproof

Param Type
credentials Object
[onComplete] function

fireproof.set(value, [onComplete]) ⇒ Promise

Delegates Firebase#set.

Kind: instance method of Fireproof

Param Type Description
value object The value to set this path to.
[onComplete] function Callback when the operation is done.

Example

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

fireproof.update(value, [onComplete]) ⇒ Promise

Delegates Firebase#update.

Kind: instance method of Fireproof

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

fireproof.remove([onComplete]) ⇒ Promise

Delegates Firebase#remove.

Kind: instance method of Fireproof

Param Type Description
[onComplete] function Callback when the operation is done.

fireproof.push(value, [onComplete]) ⇒ Promise

Delegates Firebase#push.

Kind: instance method of Fireproof

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

fireproof.setWithPriority(value, priority, [onComplete]) ⇒ Promise

Delegates Firebase#setWithPriority.

Kind: instance method of Fireproof

Param Type Description
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.

fireproof.setPriority(priority, [onComplete]) ⇒ Promise

Delegates Firebase#setPriority.

Kind: instance method of Fireproof

Param Type Description
priority object The priority to set this path to.
[onComplete] function Callback when the operation is done.

Fireproof.Demux

Kind: static class of Fireproof

new Demux(refs, [limitToFirst])

A helper object for retrieving sorted Firebase objects from multiple locations.

Param Type Description
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) ⇒ Promise

Get the next count items from the paths, ordered by priority.

Kind: instance method of Demux
Returns: Promise - A promise that resolves with the next count items, ordered by priority.

Param Type Description
count Number The number of items to get from the list.

Fireproof.LiveArray

Kind: static class of Fireproof
Properties

Name Type Description
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.

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

Param Type Description
[errorHandler] function a function to be called if a Firebase error occurs.

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.

Kind: instance method of LiveArray

Param Type Description
[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.

Kind: instance method of LiveArray

Fireproof.Pager

Kind: static class of Fireproof
Properties

Name Type Description
hasPrevious Boolean True if there are more objects before the current page.
hasNext Boolean True if there are more objects after the current page.

new Pager(ref, [initialCount])

A helper object for paging over Firebase objects.

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

pager.next(count) ⇒ Promise

Get the next page of children from the ref.

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

Param Type Description
count Number The size of the page.

pager.previous(count) ⇒ Promise

Get the previous page of children from the ref.

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

Param Type Description
count Number The size of the page.

Fireproof.stats : object

Statistics about Firebase usage.

Kind: static namespace of Fireproof
Properties

Name Type
operationLog Object
runningOperationCount Number
operationCount Number
listenCount Number

stats.reset()

Resets the count of Firebase operations back to 0.

Kind: static method of stats

stats.getListeners() ⇒ Object

Gets data about listeners on Firebase locations.

Kind: static method of stats
Returns: Object - Listener counts keyed by Firebase path.

stats.getListenerCount() ⇒ Number

Gets the total number of listeners on Firebase locations.

Kind: static method of stats
Returns: Number - The total number of Firebase listeners presently operating.

stats.getPathCounts() ⇒ Object

Gets the per-operation, per-path counts of Firebase operations.

Kind: static method of stats
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() ⇒ Object

Gets the per-operation counts of Firebase operations.

Kind: static method of stats
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) ⇒ function

Listens for Firebase events occurring.

Kind: static method of stats
Returns: function - fn is returned for convenience, to pass to off.
Throws:

  • if you don't pass in a function for fn.
Param Type Description
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.

stats.off([name], fn)

Stops sending events to a listener.

Kind: static method of stats
Throws:

  • if you don't pass in a function for fn.
Param Type Description
[name] String The name of the event. One of 'start', 'finish', 'error', 'listenStarted', or 'listenEnded.'
fn function The function to stop calling.

Fireproof.bless(Deferrable)

Deprecated

Tell Fireproof to use a given defer-style promise library from now on. If you have native promises, you don't need to call this; if you want to substitute a different promise constructor, just set it on Fireproof.Promise directly.

Kind: static method of Fireproof
Throws:

  • if you don't provide a valid promise library.
Param Type Description
Deferrable function a deferrable promise constructor with .all().

Fireproof.setNextTick(nextTick)

Tell Fireproof to use a given function to set timeouts from now on.

Kind: static method of Fireproof

Param Type Description
nextTick function a function that takes a function and runs it in the immediate future.