# Mojo.Depot

## Class Detail

Depot is an API that allows you to store JavaScript objects in a database. Today it is implemented as a framework wrapper around HTML5 active record access; but this could change in the future.

You can create a new Depot like this:

>     var db = new Mojo.Depot(options, onSuccess, onFailure);

where `options` is an object whose properties contain a number of options for opening or creating a Depot.

>     Attribute       Type                            Required    Default     Description
>     ---------------------------------------------------------------------------------------------------------------------------------
>     name            String                          Required                Name used for the HTML5 database name.
>     version         Number                          Optional    1           Version number used for the HTML5 database.
>     displayName     String                          Optional    name        Name that would be used in user interface that the user sees.
>                                                                             regarding this database. Not currently used.
>     estimatedSize   Number                          Optional                Estimated size for this database.
>     replace         Boolean                         ?           ?           A truthy value for replace will cause any existing data for this
>                                                                             depot to be discarded and a new, empty depot to be created.
>     filters         Array                           Optional                List of strings that objects in the depot can use as filters.
>     identifiers     {String:(Function|Object), ...} Optional                Hash containing key-value pairs of identifiers with either
>                                                                             constructor functions or objects whose constructor function to use.
>                                                                             Identifier string must be non-falsy.

> Callback functions:

>     {Function} onSuccess  Callback function that is called if the depot is successfully opened or created.
>     {Function} onFailure  Callback function that is called with an error string if an error occurs.

>     The following error codes may be returned to onFailure:
>     Code  Situation
>     0     The transaction failed for reasons unrelated to the database itself and not covered by any other error code.
>     1     The statement failed for database reasons not covered by any other error code.
>     2     The statement failed because the expected version of the database didn't match the actual database version.
>     3     The statement failed because the data returned from the database was too large.
>           The SQL "LIMIT" modifier might be useful to reduce the size of the result set.
>     4     The statement failed because there was not enough remaining storage space,
>           or the storage quota was reached and the user declined to give more space to the database.
>     5     The statement failed because the transaction's first statement was a read-only statement,
>           and a subsequent statement in the same transaction tried to modify the database, but the
>           transaction failed to obtain a write lock before another transaction obtained a write lock
>           and changed a part of the database that the former transaction was depending upon.
>     6     An INSERT, UPDATE, or REPLACE statement failed due to a constraint failure.
>           For example, because a row was being inserted and the value given for the primary key column
>           duplicated the value of an existing row.

## Method Summary

- Mojo.Depot.add(key, value, onSuccess, onFailure)
- Mojo.Depot.discard(key, onSuccess, onFailure)
- Mojo.Depot.get(key, onSuccess, onFailure)
- Mojo.Depot.remove(bucket, key, onSuccess, onFailure)
- Mojo.Depot.removeAll(onSuccess, onFailure)

## Method Detail

### Mojo.Depot.add(key, value, onSuccess, onFailure)

Function to add an object, identified by a key, to the depot. The default bucket is used.

#### Parameters

- {String} key - Key to identify an object to be stored in the depot. If an object with this key already exists in the default bucket, it will be replaced.
- {Object} value - Object to store in the depot.
- {Function} onSuccess - Callback function that is called if the object is successfully stored in the depot.
- {Function} onFailure - Callback function that is called with an error string if an error occurs and the object is not successfully stored in the depot.

### Mojo.Depot.discard(key, onSuccess, onFailure)

Function to remove an object, identified by a key, from the depot. The default bucket is used.

#### Parameters

- {String} key - Key to identify an object to be removed from the depot.
- {Function} onSuccess - Callback function that is called if the object is successfully removed from the depot.
- {Function} onFailure - Callback function that is called with an error string if an error occurs and the object is not successfully removed from the depot.

#### Since

1.2

### Mojo.Depot.get(key, onSuccess, onFailure)

Function to get an object, identified by a key, from the depot. The default bucket specified by `_defaultBucketName` is used.

#### Parameters

- {String} key - Key to identify an object that was stored in the depot.
- {Function} onSuccess - Callback function that is called if the object is successfully retrieved from the depot. This function is passed the retrieved object as its first parameter. If there is no object for this key, null will be passed to the onSuccess callback.
- {Function} onFailure - Callback function that is called if an error occurs, other than there being no object for the specified key. It is called with an error string as the only argument.

### Mojo.Depot.remove(bucket, key, onSuccess, onFailure)

Function to remove an object, identified by a bucket and key, from the depot.

#### Parameters

- {String} bucket - Bucket to identify the namespace of the key; if not specified or null, `_defaultBucketName` is used.
- {String} key - Key to identify an object to be removed from the depot.
- {Function} onSuccess - Callback function that is called if the object is successfully removed from the depot.
- {Function} onFailure - Callback function that is called with an error string if an error occurs and the object is not successfully removed from the depot.

### Mojo.Depot.removeAll(onSuccess, onFailure)

Function to delete the data from the current depot database.

#### Parameters

- {Function} onSuccess - Callback function that is called if the data is successfully deleted.
- {Function} onFailure - Callback function that is called if the data could not be deleted.