JavaScript SDK reference guide

The Datastore JavaScript Software Development Kit (JS SDK) provides the methods through which your JavaScript app (app) interacts with your Datastore blueprint and service.

This JS SDK reference guide documents how to configure your app to work with the JS SDK and your blueprint, as well as all methods available in the Datastore JS SDK.

Configuring the JS SDK and Datastore service in your app’s HTML files

Your JavaScript app’s HTML files need to incorporate the JS SDK (either for the Datastore local simulator or production service), as well as the main functionality of your app (e.g. main.js), which also configures the Datastore service (also known as data service), within either the <head/> or <body/> elements of these HTML files.

For a local simulation

The following code snippet demonstrates how to incorporate the simulation JS SDK and your app in an HTML file:

<html>
    ....
    <script src="https://sdk.datastore.squiz.cloud/js/sdk-simulator.js"></script> (1)
    <script src="./main.js"></script> (2)
    ....
</html>
1 Incorporates the JS SDK class that interacts with your Datastore local simulator, into your app’s HTML page/s.
2 Incorporates the functionality of your app (main.js) into its HTML page/s. Your app’s JavaScript code also needs to configure the data service.

For your production service

The following code snippet demonstrates how to incorporate the production JS SDK and your app in an HTML file:

<html>
    ....
    <script src="https://sdk.datastore.squiz.cloud/js/sdk.js"></script> (1)
    <script src="./main.js"></script> (2)
    ....
</html>
1 Incorporates the JS SDK class that interacts with your Datastore production service, into your app’s HTML page/s.
2 Incorporates the functionality of your app (main.js) into its HTML page/s. Your app’s JavaScript code also needs to configure the data service.

Configuring your data service in your app

To use Datastore, your app must be configured with the URL of your data service.

Assuming that your app (main.js) contains the configuration for your data service, configure your data service based on the following JavaScript declaration:

const settings = {
    serviceURL: '<Your data service URL here>'
};

Instantiating the data service

Your JavaScript app interacts with Datastore via an instance of your data service.

There are two ways to instantiate your data service object:

In your HTML source

In the HTML source, first incorporate the JS SDK (as described above), and then instantiate the data service object:

<html>
    ....
    <script src="https://sdk.datastore.squiz.cloud/js/sdk-simulator.js"></script> (1)
    <script>
        const datastore = new Datastore(settings); (2)
    </script>
    ...
</html>
1 Incorporates the JS SDK class for your Datastore local simulator into your app’s HTML pages. Refer to the procedure above for details on how to configure the production JS SDK class into these pages.
2 JavaScript code to instantiate the data service object, defined by the settings constant (above) in your JavaScript app (main.js).

In your app

In the JavaScript app (main.js), instantiate the data service object, defined by the settings constant (above), using the following code:

const datastore = new Datastore(settings);

Classes and methods reference

This section describes all the JS SDK classes and methods that interact with collections, documents and their properties in your data service, which you can use in your JS app.

The methods listed in each of the classes below interact with collections, documents and properties according to the data structures defined by your blueprint.

Unless otherwise specified, all classes and their methods operate the same way between the local simulator and production versions of the JS SDK class.

Datastore

The main Datastore class through which all methods are called to:

  • instantiate all other classes in this JS SDK, as well as

  • perform actions directly through the specified Datastore service (data service).

Constructor

new Datastore(settings)

Instantiates the Datastore service (data service) object, defined by the settings object whose serviceURL property contains the URL (string value) of your data service.

This object is used to interact with all collections, documents and their properties configured within this data service’s blueprint.

Parameters

settings

The settings object whose serviceURL property contains a string value of the URL to your simulated or production data service.

Returns

Datastore

A Datastore instance configured for a simulated or production data service.

Methods

collection


collection('collectionname')

Gets a DatastoreCollection instance, representing (i.e. referencing) the root-level collection of the data service’s (Datastore) blueprint (e.g. 'collectionname') on which further actions can be performed.

Parameters
'collectionname'

The 'collectionname' string, representing the name of the root-level collection, defined by the collections named and organized according to the data service’s blueprint.

Returns
DatastoreCollection

A DatastoreCollection instance representing the root-level collection of the data service’s (Datastore) blueprint.

getJWTPayload


getJWTPayload()

Gets the JWT payload for the currently authenticated user. The JWT payload is obtained either:

  • From the simulated data service, or

  • In production, from the authentication service.

Parameters

This method takes no parameters.

Returns
object

An object containing the JWT payload for the currently authenticated user.

DatastoreCollection

The DatastoreCollection class through which all methods that perform actions on a collection are called.

Learn more about collections in Data organization within collections and documents.

Constructor

new DatastoreCollection(id, parent, request optional)

Instantiates the DatastoreCollection object, representing (i.e. referencing) the collection of the data service’s (Datastore) blueprint (e.g. 'collectionname') on which further actions can be performed.

There is no need to call this constructor directly as it is returned by calling the collection method from either a Datastore or DatastoreDocument object.

Parameters

id

(integer | string) The id or name (e.g. 'collectionname') of the collection, representing either the ID or name of the collection organized according to the data service’s blueprint.

parent

(Datastore | DatastoreCollection) The 'parent' object from which this DatastoreCollection object was instantiated:

  • For root-level collections, the parent is the main Datastore instance.

  • For collections nested within documents, the parent is the DatastoreCollection instance representing the parent collection.

request (optional)

(request) The Request instance. Used for internal purposes only.

Returns

DatastoreCollection

A DatastoreCollection instance representing the collection (id) of the data service’s (Datastore) blueprint.

Methods

add


add(documentdata, docid optional)

Adds a new document whose data is contained in this method’s argument (e.g. documentdata) to this collection (referenced by DatastoreCollection) of the data service (Datastore).

Parameters
documentdata

(object) A JSON object, consisting of property and value pairs, matching the JSON schema defined for the data service’s (Datastore) blueprint.

docid (optional)

An optional ID for the document. If this parameter is omitted, Datastore automatically generates the ID for you. If you do specify your own document IDs, then each document’s ID within a given collection must be unique.

Once a document’s ID is set, it cannot be changed.
Returns
Promise

The data service’s promise to return either a DatastoreDocument, or null when no other appropriate response type is defined in the blueprint.

count


count(property optional)

Counts the total number of documents within this collection (referenced by DatastoreCollection) of the data service (Datastore), or the number of unique values for a given property across all these documents:

  • Without the property parameter, this method counts the total number of documents in this collection.

  • With the property parameter (matching any property’s name within the documents of this collection), each unique value of this property across all of the collection’s documents is listed, along with the number of times each unique value occurs throughout all these documents.

Parameters
property (optional)

An optional property parameter (matching any property’s name within the documents of this collection, referenced by DatastoreCollection) lists each unique value of this property across all of the collection’s documents, along with the number of times each unique value occurs throughout all these documents.

Returns
DatastoreCollection

A DatastoreCollection instance whose internal parameters have been configured to retrieve counts of either the total number of documents in this collection, or unique values of the specified property.

doc


doc('documentid')

Gets a DatastoreDocument instance, representing (i.e. referencing) a document within this collection (DatastoreCollection) of the data service’s (Datastore) blueprint (e.g. 'documentname') on which further actions can be performed.

Parameters
'documentid'

The 'documentid' string, representing the ID or unique name of the document, within this collection organized of the data service’s blueprint.

Returns
DatastoreDocument

A DatastoreDocument instance representing the document within this collection (DatastoreCollection) of the data service’s (Datastore) blueprint.

get


get()

Gets the contents of this collection (referenced by DatastoreCollection) of the data service’s (Datastore) blueprint.

The contents of the collection is either:

  • A list of all documents in the collection, or

  • A list of all documents in a page of the collection (once pagination has been set with a call to the limit method),

where the list of documents is a list of document IDs.

This method uses the current state of the DatastoreCollection object’s internal parameters to submit a request to the data service, which in turn retrieves the response containing the contents of this collection.

The collection’s content may be customized/modified based on the DatastoreCollection object’s internal parameters, which have been modified by other methods of this object.

If pagination had been set (by calling the limit method), then the collection’s content also includes references (specified by additional links property values) to the first documents in the next and previous pages.

Data can then be retrieved from one of these documents via the doc method, and its returned DatastoreDocument object.

Parameters

This method takes no parameters.

Returns
Promise

The data service’s promise to return the contents of the DatastoreCollection object, based on its internal parameters.

getNextPage


getNextPage()

Gets a list of documents from the next page in this collection (referenced by DatastoreCollection) of the data service’s (Datastore) blueprint.

This method can only be called once the limit method has first been called and pagination set.

Upon calling the getNextPage() method, the JS SDK retrieves references (specified by additional links property values in the paginated list of documents) to both:

  • the previous page (e.g. the page retrieved by the initial get call, after limit has been called and set), and

  • the next page (after the new current page retrieved by calling getNextPage()).

If you call this method again and links is null for the next page, the JS SDK throws an error without making a request to the data service (Datastore).

Parameters

This method takes no parameters.

Returns
Promise

The data service’s promise to return the next page of contents of the DatastoreCollection object.

getPrevPage


getPrevPage()

Gets a list of documents from the previous page in this collection (referenced by DatastoreCollection) of the data service’s (Datastore) blueprint.

This method can only be called once the limit method has first been called and pagination set.

Upon calling the getPrevPage() method, the JS SDK retrieves references (specified by additional links property values in the paginated list of documents) to both:

  • the previous page (prior to the new current page retrieved by calling getPrevPage()), and

  • the next page (e.g. the page retrieved by the initial get call, after limit has been called and set).

If you call this method again and links is null for the previous page, the JS SDK throws an error without making a request to the data service (Datastore).

Parameters

This method takes no parameters.

Returns
Promise

The data service’s promise to return the previous page of contents of the DatastoreCollection object.

groupBy


groupBy(property)

Groups each unique value of this property (matching any property’s name within the documents of this collection, referenced by DatastoreCollection) across all documents in this collection of the data service (Datastore).

This method must then be used in conjunction with the count method (without a parameter), which counts the number of times each of these unique values occurs throughout all these documents.

The groupBy(property) method can be chained to additional groupBy(property) method calls to handle nested groupings. In such scenarios, the the count method only needs to be called once.

Parameters
property

(string) The property parameter (matching any property’s name within the documents of this collection, DatastoreCollection) used to group each unique value of this property across all documents in this collection of the data service (Datastore).

Returns
DatastoreCollection

A DatastoreCollection instance whose internal parameters have been configured to retrieve groups of unique values of the specified property.

hasNextPage


hasNextPage()

Checks if the current page of documents in this collection (referenced by DatastoreCollection) of the data service (Datastore) has a subsequent page. The check is performed on the links property values in the current page of documents.

  • The value of this method is only meaningful once the limit method has first been called and set.

  • This method provides an easy way for your app to check the presence of a subsequent page before calling getNextPage, which would throw an error if there is no subsequent page.

Parameters

This method takes no parameters.

Returns
boolean

This method returns a boolean value, which is:

  • true - if links contains the document ID for the next page, or

  • false - if links contains null for the next page.

hasPrevPage


hasNextPage()

Checks if this collection (referenced by DatastoreCollection) of the data service (Datastore) has a previous page. The check is performed on the links property values in a paginated list of documents.

  • The value of this method is only meaningful once the limit method has first been called and set.

  • This method provides an easy way for your app to check the presence of a previous page before calling getPrevPage, which would throw an error if there is no previous page.

Parameters

This method takes no parameters.

Returns
boolean

This method returns a boolean value, which is:

  • true - if links contains the document ID for the previous page, or

  • false - if links contains null for the previous page.

limit


limit(totaldocuments)

Sets the total number of documents (totaldocuments) to be retrieved in a page (a 'sub-list' of documents in this collection referenced by DatastoreCollection) for pagination purposes, when any of the following 'get' methods are called on this collection of the data service (Datastore):

This setting persists throughout subsequent execution of your app, until this method is called with a different totaldocuments value.

Parameters
totaldocuments

(integer) The total number of documents to be retrieved in a page of documents in this collection (referenced by DatastoreCollection), of the data service (Datastore).

Returns
DatastoreCollection

A DatastoreCollection instance whose internal parameters have been configured for pagination to retrieve pages of documents limited by the value totaldocuments.

where


where(property, comparison, value)

Filters all documents in this collection (referenced by DatastoreCollection of the data service Datastore) by a property (matching any property’s name within the documents of this collection), where the values (value) of property are true for the comparison criteria/operator (comparison).

Parameters
property

(string) The property parameter (matching any property’s name within the documents of this collection, DatastoreCollection) used to filter all documents in this collection where the value/s (below) is/are true for the comparison operator (below).

comparison

(string) One of the following comparison operators used to filter all documents in this collection whose values (below) of the property (above) are true:

  • === - equals,

  • !== - is not equal to,

  • > - greater than,

  • >= - greater than or equal to,

  • < - less than,

  • <= - less than or equal to,

  • contains - contains all the value/s (below),

  • not-contains - does not contain all of the value/s (below),

  • contains-any - contains any of the value/s (below), and

  • not-contains-any - does not contain any of the value/s (below).

value

(string|array of strings) Either the string or array of string value/s of the property (above) used to filter all documents in this collection when the comparison (above) is true.

Returns
DatastoreCollection

A DatastoreCollection instance whose internal parameters have been configured to filter documents whose property's values (value) are true for the comparison criteria/operator (comparison).

and

and(property, comparison, value)

The and method is used:

  • when the where method has first been used to filter documents in this collection (referenced by DatastoreCollection of the data service Datastore), and

  • you then need to further filter this sub-set of documents (in a logical 'and' relationship) by the property (matching any other property’s name within the documents of this collection), where the values (value) of this property are true for its comparison criteria/operator (comparison).

Parameters

The parameters of this method are the equivalent to those for where (above).

Returns
DatastoreCollection

A DatastoreCollection instance whose internal parameters have been configured to further filter documents whose property's values (value) are true for the comparison criteria/operator (comparison).

or

or(property, comparison, value)

The or method is used:

  • when the where method has first been used to filter documents in this collection (referenced by DatastoreCollection of the data service Datastore), and

  • you additionally need to filter the collection’s documents (in a logical 'inclusive or' relationship) by the property (matching any other property’s name within the documents of this collection), where the values (value) of this property are true for its comparison criteria/operator (comparison).

Parameters

The parameters of this method are the equivalent to those for where (above).

Returns
DatastoreCollection

A DatastoreCollection instance whose internal parameters have been configured to additionally filter documents whose property's values (value) are true for the comparison criteria/operator (comparison).

sortBy


sortBy(property, order optional)

Sorts the documents within this collection (referenced by DatastoreCollection of the data service Datastore) according to the values of the property (matching any property’s name within the documents of this collection). The order parameter is used to sort the documents in either ascending or descending order.

If pagination has been set with limit, the entire collection is sorted and re-paginated according to the order.
Parameters
property

(string) The property parameter (matching any property’s name within the documents of this collection, DatastoreCollection) used to sort the documents within this collection.

order (optional)

(string) The order in which the documents in this collection are sorted. Specify the value:

  • asc (default and therefore optional) for ascending, or

  • desc for descending.

Returns
DatastoreCollection

A DatastoreCollection instance whose internal parameters have been configured to sort documents according to the order of values of the specified property.

DatastoreDocument

The DatastoreDocument class through which methods that perform actions on a document are called.

Constructor

new DatastoreDocument(id, parent, request)

Instantiates the DatastoreDocument object, representing (i.e. referencing) the document in the collection (DatastoreCollection) of the data service’s (Datastore) blueprint (e.g. 'documentid') on which further actions can be performed.

There is no need to call this constructor directly as it is returned by calling the doc method.

Parameters

id

(integer | string) The id or name (e.g. 'documentid') of the document, representing either the ID or unique name of a document organized within a collection of the data service’s blueprint.

parent

(DatastoreCollection) The DatastoreCollection object from which this DatastoreDocument object was instantiated.

request

(request) The Request instance. Used for internal purposes only.

Returns

DatastoreDocument

A DatastoreDocument instance representing the document (id) in the collection (DatastoreCollection) of the data service’s (Datastore) blueprint.

Methods

collection


collection('collectionname')

Gets a DatastoreCollection instance, representing (i.e. referencing) the collection within this document (referenced by DatastoreDocument) of the data service’s (Datastore) blueprint (e.g. 'collectionname') on which further actions can be performed.

Parameters
'collectionname'

The 'collectionname' string, representing the name of the collection within this document, defined by the collections named and organized according to the data service’s blueprint.

Returns
DatastoreCollection

A DatastoreCollection instance representing the collection within the document of the data service’s (Datastore) blueprint.

delete


delete()

Deletes this document (referenced by DatastoreDocument) within the collection (referenced by DatastoreCollection) of the data service’s (Datastore) blueprint.

Parameters

This method takes no parameters.

Returns
Promise

The data service’s promise to return the value null.

get


get()

Gets the contents of this document (referenced by DatastoreDocument) within a collection (referenced by DatastoreCollection) of the data service’s (Datastore) blueprint.

The contents of the document is a list of property and value pairs, as described in Data organization within collections and documents.

Parameters

This method takes no parameters.

Returns
Promise

The data service’s promise to return either the contents of the DatastoreDocument (according to the 200 response type defined in the blueprint), or null when no other appropriate response type is defined in the blueprint.
A response of 404 is returned if the document is not found.

update


update(documentdata)

Updates this document (referenced by DatastoreDocument) within the collection (referenced by DatastoreCollection) of the data service’s (Datastore) blueprint, with the data contained in this method’s argument (e.g. documentdata).

Parameters
documentdata

(object) A JSON object, consisting of property and value pairs, matching the JSON schema defined for the data service’s (Datastore) blueprint.

Returns
Promise

The data service’s promise to return either the contents of the DatastoreDocument (according to the 200 response type defined in the blueprint), or null when no other appropriate response type is defined in the blueprint.
A response of 404 is returned if the document is not found.