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, 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 Datastore 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 Datastore service.

Configuring your Datastore service in your app

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

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

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

Instantiating the Datastore service

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

There are two ways to instantiate your Datastore service object:

In your HTML source

In the HTML source, first incorporate the JS SDK (as described above), and then instantiate the Datastore 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 Datastore 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 Datastore service object, defined by the settings constant (above), using the following code:

const datastore = new Datastore(settings);

Standard methods

This section describes how to use the JS SDK’s methods in your app to interact with documents and collections in your Datastore service.

Be aware that since you create your own document and collection structures, as well as your blueprint’s API endpoints, the methods described in this section have been made generic to provide guidance on how you would create method calls using your own blueprints.

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

Getting a collection

The following code snippet shows the JS SDK call to retrieve a list of collections, where datastore is your instantiated Datastore service:

const getMyCollection = () => {
    datastore.collection('mycollection').get().then( (1)
        (mycollection) => {
            if (mycollection.length === 0) {
                ...
                // Code to handle what happens when there is no collection.
                ...
            } else {
                mycollection.forEach((document) => {
                    printDocument(document); (2)
                });
            }
        }
    );
};
1 The JS SDK call to get a list of documents from your Datastore service.
The datastore.collection() method prepares a collection request on the top-level collection (i.e. mycollection).
These data structures are based on your organisation of your document and collection data structures (defined in your blueprint).
The get() method is then called on this collection() to send a GET request (on the prepared collection request) to retrieve the mycollection collection’s array of individual document objects.
Then, if all goes well …​
2 Outputs a list of each document in the mycollection collection.
Note: The printDocument() function is defined elsewhere, and is a function that would output the values of a document object passed as its parameter.

Getting a document

A document is contained within a collection, each of which is identifiable by a unique ID within a collection. An array of documents identifiable by their IDs can be obtained by getting a collection.

To retrieve a document from your Datastore service, use this syntax (where datastore is your instantiated Datastore service):

datastore.collection('mycollection').doc('document.documentid').get()

where the doc() method called on the collection() method prepares a document request for a specific document object (whose ID is document.documentid) on the top-level collection (mycollection).

The get() method is then called on this doc() to send a GET request (on the prepared document request) to retrieve the document object specified by documentid.

Note: The documentid property of the document object (i.e. document.documentid) assumes that you have the path /mycollection/{documentid} and the parameters for documentid defined as part of your blueprint.

Getting a sub-collection

A sub-collection is a collection nested within a document, as described in Document and collection organisation.

To retrieve a sub-collection from your Datastore service, use this syntax (where datastore is your instantiated Datastore service):

datastore.collection('mycollection').doc('document.documentid').collection('mysubcollection').get()

where the doc() method called on the collection() method sets a specific document (i.e. document, whose ID is document.documentid) as an object, within the top-level collection (mycollection).

The collection() method is then called on this doc() object to prepare a collection request on the sub-collection mysubcollection within the document (specified by document.documentid).

The get() method is then called on this collection() to send a GET request (on the prepared collection request) to retrieve the mysubcollection sub-collection’s array of individual document objects.

Note: The documentid property of the document object (i.e. document.documentid) assumes that you have the path /mycollection/{documentid} and the parameters for documentid defined as part of your blueprint.

Adding a document

The following code snippet shows the JS SDK call to add a new document to an existing collection (where datastore is your instantiated Datastore service):

const addDocument = () => {
    const data = { (1)
        name: // Code to temporarily hold and/or retrieve a name value.
        description: // Code to temporarily hold and/or retrieve a description value.
        ...
    };

    datastore.collection('mycollection').add(data).then((document) => { (2)
        printDocument(document); (3)
        ...
    });
};
1 Contains JavaScript code to temporarily hold and/or retrieve the data to be added to the data constant object.
2 The JS SDK call to add the data values to the mycollection collection in your Datastore service.
The datastore.collection() method prepares a collection request on the top-level collection (mycollection).
The add() method is then called on this collection() to send a POST request (on the prepared collection request) to add the properties' values in the data object, as a new document of this mycollection collection.
Then, if all goes well …​
3 Outputs the document data that was added to the mycollection collection.
Note: The printDocument() function is defined elsewhere, and is a function that would output the values of a document object passed as its parameter.

Handling failure when adding a document

The following code snippet shows the JS SDK call to handle failure when an attempt to add a new document to an existing collection does not succeed. Following on from the code snippet above:

const addDocument = () => {
    const data = {
        ...
        // Code to temporarily hold and/or retrieve the required data values.
        ...
    };

    datastore.collection('mycollection').add(data).then((document) => {
        printDocument(document);
        ...
    }).catch((error) => { (1)
        printError(error); (2)
    });
};
1 The JS SDK call to handle the error response from the Datastore service in the event that the add() method does not return an HTTP status value of 201. The error response from the Datastore service is temporarily held by error.
2 Outputs the error data.
Note: The printError() function is defined elsewhere, and is a function that would output the error values from the Datastore service’s response when the add() function does not succeed.

Updating a document’s data

The following code snippet shows the JS SDK call to update an existing document in an existing collection (where datastore is your instantiated Datastore service):

const updateDocument = () => {
    const data = { (1)
        name: // Code to temporarily hold and/or retrieve a name value.
        description: // Code to temporarily hold and/or retrieve a description value.
        ...
    };

    datastore.collection('mycollection').doc(document.documentid).update(data).then((document) => { (2)
        ...
    }).catch((error) => { (3)
        ...
    });
};
1 Contains JavaScript code to temporarily hold and/or retrieve the data to be added to the data constant object.
2 The JS SDK call to update an existing document (whose ID is document.documentid) in your Datastore service, with the values defined in the data object.
The datastore.collection() method sets the top-level collection (mycollection) as an object.
The doc() method is then called on this collection() object to prepare a document request object for the existing document (specified by its ID document.documentid).
The update() method is then called on the prepared document request object to update the properties in the specific document (whose ID is document.documentid), with those held temporarily in the data object.
Note: The documentid property call on the document object (i.e. document.documentid) assumes that you have the path /mycollection/{documentid}, and its parameters, as well as patch method, defined in your blueprint’s API specification.
Then, if all goes well …​
3 The JS SDK call to handle the error response from the Datastore service in the event that the update() method does not return an HTTP status value of 200. The error response from the Datastore service is temporarily held by error.

Deleting a document

The following code snippet shows the JS SDK call to delete a document in an existing collection (where datastore is your instantiated Datastore service):

const deleteEvent = () => {

    datastore.collection('mycollection').doc(document.documentid).delete().then(() => { (1)
        ...
    }).catch((error) => { (2)
        ...
    });

};
1 The JS SDK call to delete an existing document (whose ID is document.documentid) from your Datastore service.
The datastore.collection() sets the top-level collection (mycollection) as an object.
The doc() method is then called on this collection() object to prepare a document request object for the existing document (specified by its ID document.documentid). The delete() method is then called on the prepared document request object to delete this specific document.
Note: document.documentid is a document ID, whose value is set elsewhere in main.js.
2 The JS SDK call to handle the error response from the Datastore service in the event that the delete() method does not return an HTTP status value of 204. The error response from the Datastore service is temporarily held by error, which the app then outputs.

© 2015- Squiz Pty Ltd