API Preview tool | The Dojo Toolkit

dojo/store/api/Store.js

Provides:
- dojo.store.api.Store

dojo.store.api.Store

type
```
Function
```

summary

This is an abstract API that data provider implementations conform to.
This file defines methods signatures and intentionally leaves all the
methods unimplemented.  For more information on the dojo.store APIs,
please visit: http://dojotoolkit.org/reference-guide/dojo/store.html
Every method and property is optional, and is only needed if the functionality
it provides is required.
Every method may return a promise for the specified return value if the
execution of the operation is asynchronous (except
for query() which already defines an async return value).

dojo.store.api.Store.idProperty

type
```
String
```

summary

If the store has a single primary key, this tndicates the property to use as the
identity property. The values of this property should be unique.

dojo.store.api.Store.queryEngine

type
```
Function
```

summary

If the store can be queried locally (on the client side in JS), this defines
the query engine to use for querying the data store.
This takes a query and query options and returns a function that can execute
the provided query on a JavaScript array. The queryEngine may be replace to
provide more sophisticated querying capabilities. For example:
 var query = store.queryEngine({foo:&quot;bar&quot;}, {count:10});
 query(someArray) -&gt; filtered array
The returned query function may have a &quot;matches&quot; property that can be
used to determine if an object matches the query. For example:
 query.matches({id:&quot;some-object&quot;, foo:&quot;bar&quot;}) -&gt; true
 query.matches({id:&quot;some-object&quot;, foo:&quot;something else&quot;}) -&gt; false

dojo.store.api.Store.get

parameters:

id: (typeof Number)

The identity to use to lookup the object

summary
```
Retrieves an object by its identity
```

return_summary

Object
The object in the store that matches the given id.

type
```
Function
```

dojo.store.api.Store.getIdentity
- parameters:
  - object: (typeof Object)
```
The object to get the identity from
```
- summary
```
Returns an object's identity
```
- return_summary
```
String|Number
```
- type
```
Function
```
dojo.store.api.Store.put
- parameters:
  - object: (typeof Object)
```
The object to store.
```
  - directives: (typeof dojo.store.api.Store.PutDirectives)
```
Additional directives for storing objects.
```
- summary
```
Stores an object
```
- return_summary
```
Number|String
```
- type
```
Function
```

dojo.store.api.Store.add

parameters:
- object: (typeof Object)
```
The object to store.
```
- directives: (typeof dojo.store.api.Store.PutDirectives)
```
Additional directives for creating objects.
```

summary

Creates an object, throws an error if the object already exists

return_summary
```
Number|String
```
type
```
Function
```

dojo.store.api.Store.remove

parameters:

id: (typeof Number)

The identity to use to delete the object

summary
```
Deletes an object by its identity
```
type
```
Function
```

dojo.store.api.Store.data
dojo.store.api.Store.data.length

dojo.store.api.Store.query

parameters:

query: (typeof String|Object|Function)

The query to use for retrieving objects from the store.

options: (typeof dojo.store.api.Store.QueryOptions)
```
The optional arguments to apply to the resultset.
```

summary

Queries the store for objects. This does not alter the store, but returns a
set of data from the store.

return_summary

dojo.store.api.Store.QueryResults
The results of the query, extended with iterative methods.

example

Given the following store:

...find all items where "prime" is true:

	store.query({ prime: true }).forEach(function(object){
		// handle each object
	});

type
```
Function
```

dojo.store.api.Store.transaction

summary

Starts a new transaction.
Note that a store user might not call transaction() prior to using put,
delete, etc. in which case these operations effectively could be thought of
as &quot;auto-commit&quot; style actions.

return_summary

dojo.store.api.Store.Transaction
This represents the new current transaction.

type
```
Function
```

dojo.store.api.Store.getChildren

parameters:

parent: (typeof Object)
```
The object to find the children of.
```

options: (typeof dojo.store.api.Store.QueryOptions)

Additional options to apply to the retrieval of the children.

summary
```
Retrieves the children of an object.
```

return_summary

dojo.store.api.Store.QueryResults
A result set of the children of the parent object.

type
```
Function
```

dojo.store.api.Store.getMetadata

parameters:
- object: (typeof Object)
```
The object to return metadata for.
```

summary

Returns any metadata about the object. This may include attribution,
cache directives, history, or version information.

return_summary
```
Object
An object containing metadata.
```
type
```
Function
```

dojo.store.api.Store.QueryResults

type
```
Function
```

summary

This is an object returned from query() calls that provides access to the results
of a query. Queries may be executed asynchronously.

dojo.store.api.Store.QueryResults.forEach

parameters:

callback: (typeof Function)

that is called for each object in the query results

thisObject: (typeof The)

object to use as |this| in the callback.

summary

Iterates over the query results, based on
https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/forEach.
Note that this may executed asynchronously. The callback may be called
after this function returns.

type
```
Function
```

dojo.store.api.Store.QueryResults.filter

parameters:

callback: (typeof Function)

that is called for each object in the query results

thisObject: (typeof The)

object to use as |this| in the callback.

summary

Filters the query results, based on
https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/filter.
Note that this may executed asynchronously. The callback may be called
after this function returns.

return_summary
```
dojo.store.api.Store.QueryResults
```
type
```
Function
```

dojo.store.api.Store.QueryResults.map

parameters:

callback: (typeof Function)

that is called for each object in the query results

thisObject: (typeof The)

object to use as |this| in the callback.

summary

Maps the query results, based on
https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/map.
Note that this may executed asynchronously. The callback may be called
after this function returns.

return_summary
```
dojo.store.api.Store.QueryResults
```
type
```
Function
```

dojo.store.api.Store.QueryResults.then

parameters:

callback: (typeof This)

is called when the query is completed successfully, and is passed a single argument
that is an array representing the query results.

errorHandler: (typeof This)

is called if the query failed, and is passed a single argument that is the error
for the failure.

summary

This registers a callback for when the query is complete, if the query is asynchronous.
This is an optional method, and may not be present for synchronous queries.

type
```
Function
```

dojo.store.api.Store.QueryResults.observe

parameters:

listener: (typeof Function)

The listener function is called when objects in the query results are modified
to affect the query result. The listener function is called with the following
arguments:
 listener(object, removedFrom, insertedInto);
* The object parameter indicates the object that was create, modified, or deleted.
* The removedFrom parameter indicates the index in the result array where
the object used to be. If the value is -1, then the object is an addition to
this result set (due to a new object being created, or changed such that it
is a part of the result set).
* The insertedInto parameter indicates the index in the result array where
the object should be now. If the value is -1, then the object is a removal
from this result set (due to an object being deleted, or changed such that it
is not a part of the result set).

includeAllUpdates: (typeof This)

indicates whether or not to include object updates that do not affect
the inclusion or order of the object in the query results. By default this is false,
which means that if any object is updated in such a way that it remains
in the result set and it's position in result sets is not affected, then the listener
will not be fired.

summary

This registers a callback for notification of when data is modified in the query results.
This is an optional method, and is usually provided by dojo.store.Observable.

type
```
Function
```

dojo.store.api.Store.QueryResults.total

optional
type
```
Number|Promise
```

summary

This property should be included in if the query options included the &quot;count&quot;
property limiting the result set. This property indicates the total number of objects
matching the query (as if &quot;start&quot; and &quot;count&quot; weren't present). This may be
a promise if the query is asynchronous.

dojo.store.api.Store.Transaction

type
```
Function
```

summary

This is an object returned from transaction() calls that represents the current
transaction.

dojo.store.api.Store.Transaction.commit

summary

Commits the transaction. This may throw an error if it fails. Of if the operation
is asynchronous, it may return a promise that represents the eventual success
or failure of the commit.

type
```
Function
```

dojo.store.api.Store.Transaction.abort

parameters:
- callback
- thisObject

summary

Aborts the transaction. This may throw an error if it fails. Of if the operation
is asynchronous, it may return a promise that represents the eventual success
or failure of the abort.

type
```
Function
```

dojo.store.api.Store.PutDirectives

parameters:

id: (typeof String|Number)

Indicates the identity of the object if a new object is created

before: (typeof Object)

If the collection of objects in the store has a natural ordering,
this indicates that the created or updated object should be placed before the
object specified by the value of this property. A value of null indicates that the
object should be last.

parent: (typeof Object,)

If the store is hierarchical (with single parenting) this property indicates the
new parent of the created or updated object.

overwrite: (typeof Boolean)

If this is provided as a boolean it indicates that the object should or should not
overwrite an existing object. A value of true indicates that a new object
should not be created, the operation should update an existing object. A
value of false indicates that an existing object should not be updated, a new
object should be created (which is the same as an add() operation). When
this property is not provided, either an update or creation is acceptable.

summary

Directives passed to put() and add() handlers for guiding the update and
creation of stored objects.

type
```
Function
```

dojo.store.api.Store.PutDirectives.id

optional
type
```
String|Number
```

summary

Indicates the identity of the object if a new object is created

dojo.store.api.Store.PutDirectives.before

optional
type
```
Object
```

summary

If the collection of objects in the store has a natural ordering,
this indicates that the created or updated object should be placed before the
object specified by the value of this property. A value of null indicates that the
object should be last.

dojo.store.api.Store.PutDirectives.parent

optional
type
```
Object,
```

summary

If the store is hierarchical (with single parenting) this property indicates the
new parent of the created or updated object.

dojo.store.api.Store.PutDirectives.overwrite

optional
type
```
Boolean
```

summary

If this is provided as a boolean it indicates that the object should or should not
overwrite an existing object. A value of true indicates that a new object
should not be created, the operation should update an existing object. A
value of false indicates that an existing object should not be updated, a new
object should be created (which is the same as an add() operation). When
this property is not provided, either an update or creation is acceptable.

dojo.store.api.Store.SortInformation

parameters:

attribute: (typeof String)
```
The name of the attribute to sort on.
```

descending: (typeof Boolean)

The direction of the sort.  Default is false.

summary

An object describing what attribute to sort on, and the direction of the sort.

type
```
Function
```

dojo.store.api.Store.SortInformation.attribute
- type
```
String
```
- summary
```
The name of the attribute to sort on.
```
dojo.store.api.Store.SortInformation.descending
- type
```
Boolean
```
- summary
```
The direction of the sort.  Default is false.
```

dojo.store.api.Store.QueryOptions

parameters:

sort: (typeof dojo.store.api.Store.SortInformation[])

A list of attributes to sort on, as well as direction
For example:
 [{attribute:&quot;price, descending: true}].
If the sort parameter is omitted, then the natural order of the store may be
applied if there is a natural order.

start: (typeof Number)
```
The first result to begin iteration on
```

count: (typeof Number)

The number of how many results should be returned.

summary

Optional object with additional parameters for query results.

type
```
Function
```

dojo.store.api.Store.QueryOptions.sort

optional
type
```
dojo.store.api.Store.SortInformation[]
```

summary

A list of attributes to sort on, as well as direction
For example:
 [{attribute:&quot;price, descending: true}].
If the sort parameter is omitted, then the natural order of the store may be
applied if there is a natural order.

dojo.store.api.Store.QueryOptions.start
- optional
- type
```
Number
```
- summary
```
The first result to begin iteration on
```
dojo.store.api.Store.QueryOptions.count
- optional
- type
```
Number
```
- summary
```
The number of how many results should be returned.
```
dojo.store.api
- type
```
Object
```
dojo.store
- type
```
Object
```
dojo
- type
```
Object
```

dojo/store/api/Store.js

Provides:

dojo.store.api.Store

dojo.store.api.Store.idProperty

dojo.store.api.Store.queryEngine

dojo.store.api.Store.get

dojo.store.api.Store.getIdentity

dojo.store.api.Store.put

dojo.store.api.Store.add

dojo.store.api.Store.remove

dojo.store.api.Store.data

dojo.store.api.Store.data.length

dojo.store.api.Store.query

dojo.store.api.Store.transaction

dojo.store.api.Store.getChildren

dojo.store.api.Store.getMetadata

dojo.store.api.Store.QueryResults

dojo.store.api.Store.QueryResults.forEach

dojo.store.api.Store.QueryResults.filter

dojo.store.api.Store.QueryResults.map

dojo.store.api.Store.QueryResults.then

dojo.store.api.Store.QueryResults.observe

dojo.store.api.Store.QueryResults.total

dojo.store.api.Store.Transaction

dojo.store.api.Store.Transaction.commit

dojo.store.api.Store.Transaction.abort

dojo.store.api.Store.PutDirectives

dojo.store.api.Store.PutDirectives.id

dojo.store.api.Store.PutDirectives.before

dojo.store.api.Store.PutDirectives.parent

dojo.store.api.Store.PutDirectives.overwrite

dojo.store.api.Store.SortInformation

dojo.store.api.Store.SortInformation.attribute

dojo.store.api.Store.SortInformation.descending

dojo.store.api.Store.QueryOptions

dojo.store.api.Store.QueryOptions.sort

dojo.store.api.Store.QueryOptions.start

dojo.store.api.Store.QueryOptions.count

dojo.store.api

dojo.store

dojo