Configuring the Javascript SDK (JS SDK)

Your JavaScript app’s HTML files must incorporate the JS SDK (either for the Datastore local simulator or production service). They must also include the main functionality of your app (for example/main.js), which also configures the Data Service within either the <head/> or <body/> elements of these HTML files.

For a local simulation

<script src="https://sdk.datastore.squiz.cloud/js/sdk-simulator.js"></script>

For your production service

<script src="https://sdk.datastore.squiz.cloud/js/sdk.js"></script>

Configuring your data service in your app

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

const datastore = new Datastore(settings);

The settings available for the Datastore JS SDK are:

Setting

Required

Simulator only

Description

Type

=== Example

serviceURL

Yes

The Data Service or Simulators URL.

String

https://my-data-service.datastore.squiz.cloud

jwtURL

The URL to the JWT generator being used.

String

https://my-jwt.example.com

jwtCallback

A custom callback function to get a JWT token. Must return a promise.

Function

(payload) => {
    return Promise.resolve();
}

jwtPayload

Yes

Optional JWT Payload. Required when using the Simulator’s built-in JWT generator.

Object

{
    “isAdmin”: true
}

detailedResponse

Yes

A flag to return the detailed response of a request, for example, headers, status code, and more.

Boolean

true

interceptRequest

Yes

An object to flag to return the request information (params, headers) for specified paths before sending the request.

Object

{
    “isAdmin”: true
}

failRequests

Yes

Fail requests for specific paths with the given error object.

Object

Function List

Function	Description
collection(collectionName)	Gets a DatastoreCollectionObject reference to perform actions on the collection in the Data Service.
doc(documentID)	Gets a DatastoreDocumentObject reference to perform actions on the document in the Data Service.
setSettings(settings)	Set the settings on the Datastore JS SDK object.
setSetting(setting/value)	Set a setting on the Datastore JS SDK object.
getSetting(setting)	Gets a setting value from the Datastore JS SDK object.
getJWTPayload()	Gets the JWT Payload for the token that’s been requested.
add(data/docid)	Adds a new document to a collection in a Data Service.
get() - collection	Gets all the documents in a collection of a Data Service.
get() - document	Gets a document from a collection in a Data Service.
update(data)	Updates a document from a collection in a Data Service.
delete()	Deletes a document from a collection in a Data Service.
limit(limit)	Sets a page limit for how many documents will be returned in a get collection request.
hasNextPage()	Checks if there is a next page when making pagination requests.
hasPrevPage()	Checks if there is a previous page when making pagination requests.
getNextPage()	Gets the next page in a pagination request.
getPrevPage()	Gets the previous page in a pagination request.
sortBy(property/direction)	Sorts the documents in a collection request.
where(property/comparison/value)	Starts the filtering settings for a collection request.
and(property/comparison/value)	Specifies an and statement in the filtering settings for a collection request.
or(property/comparison/value)	Specifies an or statement in the filtering settings for a collection request.
whereGroup(property/comparison/value)	Allows you to define a group of where/and/or conditions to be grouped into a filter in a collection request. Allowing for a more complex grouping of filter conditions. For example (A \|\| B) && C.
count(property)	Specifies a count of documents with the property specified on a collection request.
groupBy(property)	Specifies a property to be used by which to group the aggregation result.
segment(segmentName)	Gets a segment for a collection.

Function

Description

collection(collectionName)

Gets a DatastoreCollectionObject reference to perform actions on the collection in the Data Service.

doc(documentID)

Gets a DatastoreDocumentObject reference to perform actions on the document in the Data Service.

setSettings(settings)

Set the settings on the Datastore JS SDK object.

setSetting(setting/value)

Set a setting on the Datastore JS SDK object.

getSetting(setting)

Gets a setting value from the Datastore JS SDK object.

getJWTPayload()

Gets the JWT Payload for the token that’s been requested.

add(data/docid)

Adds a new document to a collection in a Data Service.

get() - collection

Gets all the documents in a collection of a Data Service.

get() - document

Gets a document from a collection in a Data Service.

update(data)

Updates a document from a collection in a Data Service.

delete()

Deletes a document from a collection in a Data Service.

limit(limit)

Sets a page limit for how many documents will be returned in a get collection request.

hasNextPage()

Checks if there is a next page when making pagination requests.

hasPrevPage()

Checks if there is a previous page when making pagination requests.

getNextPage()

Gets the next page in a pagination request.

getPrevPage()

Gets the previous page in a pagination request.

sortBy(property/direction)

Sorts the documents in a collection request.

where(property/comparison/value)

Starts the filtering settings for a collection request.

and(property/comparison/value)

Specifies an and statement in the filtering settings for a collection request.

or(property/comparison/value)

Specifies an or statement in the filtering settings for a collection request.

whereGroup(property/comparison/value)

Allows you to define a group of where/and/or conditions to be grouped into a filter in a collection request. Allowing for a more complex grouping of filter conditions. For example (A || B) && C.

count(property)

Specifies a count of documents with the property specified on a collection request.

groupBy(property)

Specifies a property to be used by which to group the aggregation result.

segment(segmentName)

Gets a segment for a collection.

collection()

Gets a DatastoreCollectionObject reference to perform actions on the collection in the Data Service.

Signature

collection(collectionName: string): DatastoreCollectionObject

Parameters

collectionName (string): The collection name as defined in the Blueprint.

Returns

DatastoreCollectionObject: A DatastoreCollectionObject to perform collection requests on.

Example

Do the following to use the JS SDK to get the 'students' collection on which to perform actions:

const students = await datastore.collection(`students`);

doc()

Gets a DatastoreDocumentObject reference to perform actions on the document in the Data Service.

Signature

doc(documentID: string): DatastoreDocumentObject

Parameters

collectionName (string): The collection name as defined in the Blueprint.

Returns

DatastoreDocumentObject: A DatastoreDocumentObject on which to perform document requests.

Example

Do the following to use the JS SDK to get a document from our 'students' collection on which to perform actions:

const students = await datastore.collection(`students`).doc(`student-123`);

setSettings()

Set the settings on the Datastore JS SDK object.

Signature

setSettings(settings: object): void

Parameters

settings (object): The settings for the Datastore JS SDK object to use.

Returns

Void

Example

Do the following to use the JS SDK to change the settings to use a different Data Service:

const newSettings = {
    serviceURL: 'https://my-second-data-service.datastore.squiz.cloud'
}
datastore.setSettings(newSettings);

setSetting()

Set a setting on the Datastore JS SDK object.

Signature

setSetting(setting: string, value: any): void

Parameters

setting (string): The setting to be updated for the Datastore JS SDK object to use.
value (any): The new value for the setting that is being set.

Returns

Void

Example

Do the following to use the JS SDK to change the JWT URL setting to use a different JWT generator:

datastore.setSetting(`jwtURL`, `https://my-new-jwt.generator.com`);

getSetting()

Gets a setting value from the Datastore JS SDK object.

Signature

getSetting(setting: string): any

Parameters

setting (string): The setting name to be retrieved.

Returns

Any: The value of the setting is returned.

Example

Do the following to use the JS SDK to change the JWT URL setting to use a different JWT generator:

datastore.setSetting(`jwtURL`, `https://my-new-jwt.generator.com`);

getJWTPayload()

Gets the JWT Payload for the token that’s been requested.

Signature

getJWTPayload(): Object

Parameters

This method takes no parameters.

Returns

Object: An Object of the JWT key values is returned.

Example

Do the following to use the JS SDK to see what is in our JWT:

const jwtPayload = datastore.getJWTPayload();

add()

Adds a new document to a collection in a Data Service.

Signature

add(data: object, docid: string | undefined): Promise<object | null>

Parameters

data (object)

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

docid (string or null)

An optional ID for the document. If this parameter is omitted, the Data Service 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<object | null>: A Promise resolved with a Document Object as defined in the Blueprint or null when no content is specified to be returned.

Example

Do the following to use the JS SDK to add a new student to the 'students' collection with a document ID generated by the Data Service:

const studentData = {
    “name”: “John Smith”,
    “gpa”:  2.5,
    “campus”: “Sydney”
};

const newStudent = await datastore.collection(`students`).add(studentData);

Do the following to use the JS SDK to create the same document with a specific ID:

const studentData = {
    “name”: “John Smith”,
    “gpa”:  2.5,
    “campus”: “Sydney”
};

const newStudent = await datastore.collection(`students`).add(studentData, `student-123`);

get() - collection

Gets all the documents in a collection of a Data Service.

Signature

get(): Promise<object | Array<objects>>

Parameters

This method takes no parameters.

Returns

Promise<object | Array<object>>: A Promise resolved with an object of data and pagination details or an array of Document Objects as defined in the Blueprint.

Example

Do the following to use the JS SDK to get all the students from the 'students' collection:

const students = await datastore.collection(`students`).get();

get() - document

Gets a document from a collection in a Data Service.

Signature

get(): Promise<object | null>

Parameters

This method takes no parameters.

Returns

Promise<object | null>: A Promise resolved with a Document Object as defined in the Blueprint or null when not found.

Example

Do the following to get a student document from the 'students' collection using the JS SDK:

const student = await datastore.collection(`students`).doc(`student-123`).get();

update()

Updates a document from a collection in a Data Service.

Signature

update(data): Promise<object>

Parameters

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

Returns

Promise<object | null>: A Promise resolved with a Document Object as defined in the Blueprint or null when no content is specified.

Example

Do the following to use the JS SDK to update a student’s GPA in their document:

const student = await datastore.collection(`students`).doc(`student-123`).update({“gpa”: 3.0});

delete()

Deletes a document from a collection in a Data Service.

Signature

delete(): Promise<null>

Parameters

This method takes no parameters.

Returns

Promise<null>: A Promise resolved with null.

Example

Do the following to use the JS SDK to delete a student from the 'students' collection:

const student = await datastore.collection(`students`).doc(`student-123`).delete();

limit()

Sets a page limit for how many documents will be returned in a get collection request.

Signature

limit(limit: integer): DatastoreCollectionObject

Parameters

limit (integer): The number of documents to be returned in the get collection request.

Returns

DatastoreCollectionObject: A DatastoreCollectionObject allows for the limit() method to be chained to a collection request to the Data Service.

Example

Do the following to use the JS SDK to get students from the 'students' collection grouped 10 per page:

const student = await datastore.collection(`students`).limit(10).get();

hasNextPage()

Checks if there is a next page when making pagination requests.

Signature

hasNextPage(): boolean

Parameters

This method takes no parameters.

Returns

Boolean: A Boolean to signify if there is a 'next' page.

Example

Do the following to use the JS SDK to check if there is a 'next' page when making a paginated request to the 'students' collection:

const nextPage = await datastore.collection(`students`).hasNextPage();

hasPrevPage()

Checks if there is a previous page when making pagination requests.

Signature

hasPrevPage(): boolean

Parameters

This method takes no parameters.

Returns

Boolean: A Boolean to signify if there is a 'previous' page or not.

Example

Do the following to use the JS SDK to check if there is a 'previous' page when making a paginated request to the 'students' collection:

const prevPage = await datastore.collection(`students`).hasPrevPage();

getNextPage()

Gets the next page in a pagination request.

Signature

getNextPage(): Promise<object>

Parameters

This method takes no parameters.

Returns

Promise<object>: A Promise resolved with an object of data and pagination details.

Example

Do the following to use the JS SDK to get the 'next' page when making a paginated request to the 'students' collection:

const nextPage = await datastore.collection(`students`).getNextPage();

getPrevPage()

Gets the previous page in a pagination request.

Signature

getPrevPage(): Promise<object>

Parameters

This method takes no parameters.

Returns

Promise<object>: A Promise resolved with an object of data and pagination details.

Example

Do the following to use the JS SDK to get the previous page when making a paginated request to the 'students' collection:

const prevPage = await datastore.collection(`students`).getPrevPage();

sortBy()

Sorts the documents in a collection request.

Signature

sortBy(property: string, direction: string | undefined): DatastoreCollectionObject

Parameters

property (string): The property id we are sorting by as defined in the Blueprint.
direction (string | undefined): Optional direction we are sorting, valid directions as asc or desc. The default is asc.

Returns

DatastoreCollectionObject: A DatastoreCollectionObject allows for the sortBy() method to be chained to a collection request to the Data Service.

Example

Do the following to use the JS SDK to sort student documents by their GPA property from the 'students' collection:

// Students by GPA ascending.
const students = await datastore.collection(`students`).sortBy(`gpa`).get();

// Students by GPA descending.
const students = await datastore.collection(`students`).sortBy(`gpa`, `desc`).get();

where()

Starts the filtering settings for a collection request.

Signature

where(property: string | DatastoreFilter, comparison: string, value: any): DatastoreCollectionObject

Parameters

property (string | DatastoreFilter): The property ID by which to filter as defined in the Blueprint or a DatastoreFilter object returned from the whereGroup() method.
comparison (string): The filter comparison operator to use.
value (any): The value to which the document property values are compared.

Returns

DatastoreCollectionObject: A DatastoreCollectionObject allows for the where() method to be chained to a collection request to the Data Service.

Example

Do the following to use the JS SDK to filter student documents where their GPA property value is greater than 2 from the 'students' collection:

const students = await datastore.collection(`students`).where(`gpa`, `>`, 2).get();

and()

Specifies an 'and' statement in the filtering settings for a collection request.

Signature

and(property: string | DatastoreFilter, comparison: string, value: any): DatastoreCollectionObject

Parameters

property (string | DatastoreFilter): The property ID by which to filter as defined in the Blueprint or a DatastoreFilter object returned from the whereGroup() method.
comparison (string): The filter comparison operator to use.
value (any): The value we are comparing the document property values to.

Returns

DatastoreCollectionObject: A DatastoreCollectionObject allows for the and() method to be chained to a collection request to the Data Service.

Example

Do the following to use the JS SDK to filter student documents where their GPA property value is greater than 2 and the campus is Sydney from the 'students' collection:

const students = await datastore.collection(`students`).where(`gpa`, `>`, 2).and(`campus`, `===`, `Sydney`).get();

or()

Specifies an or statement in the filtering settings for a collection request.

Signature

or(property: string | DatastoreFilter, comparison: string, value: any): DatastoreCollectionObject

Parameters

property (string | DatastoreFilter): The property ID by which to filter as defined in the Blueprint or a DatastoreFilter object returned from the whereGroup() method.
comparison (string): The filter comparison operator to use.
value (any): The value we are comparing the document property values to.

Returns

DatastoreCollectionObject: A DatastoreCollectionObject allows for the or() method to be chained to a collection request to the Data Service.

Example

Do the following to use the JS SDK to filter student documents where their age is less than or equal to 21 or their age is greater than or equal to 30 from the 'students' collection:

const students = await datastore.collection(`students`).where(`age`, `<=`, 21).or(`age`, `>=`, 30).get();

whereGroup()

Allows you to define a group of where/and/or conditions to be grouped into a filter in a collection request. Allowing for a more complex grouping of filter conditions. For example (A || B) && C.

Signature

whereGroup(property: string | DatastoreFilter, comparison: string, value: any): DatastoreFilter

Parameters

property (string | DatastoreFilter): The property ID by which to filter as defined in the Blueprint or a DatastoreFilter object returned from the whereGroup() method.
comparison (string): The filter comparison operator to use.
value (any): The value we are comparing the document property values to.

Returns

DatastoreFilter: A DatastoreFilter allows for the whereGroup() method to be chained to a collection request to the Data Service.

Example

Do the following to use the JS SDK to filter student documents where their GPA is 2 or 3 range from the 'students' collection:

const gpaRangeFilter = datastore.collection(`students`).whereGroup(`gpa`, `<=`, 3).and(`gpa`, `>=`, 2);
const studentsInGPARange = await datastore.collection(`students`).where(gpaRangeFilter).get();

Do the following to use the JS SDK to filter student documents where their GPA is in the range 2 to 3 and the campus is Sydney from the 'students' collection:

const gpaRangeFilter = datastore.collection(`students`).whereGroup(`gpa`, `<=`, 3).and(`gpa`, `>=`, 2);
const studentsInGPARangeAndCampus = await datastore.collection(`students`).where(gpaRangeFilter).and(`campus`, `===`, `Sydney`).get();

count()

Specifies a count of documents with the property specified on a collection request.

Signature

count(property: string | undefined): DatastoreCollectionObject

Parameters

property (string | undefined): The property ID on which to count as defined in the Blueprint or undefined. Defaults to Document ID.

Returns

DatastoreCollectionObject: A DatastoreCollectionObject allows for the count() method to be chained to a collection request to the Data Service.

Example

Do the following to use the JS SDK to count all the student documents from the 'students' collection:

const students = await datastore.collection(`students`).count().get();

groupBy()

Specifies a property to be used to group the aggregation result by.

Signature

groupBy(property: string): DatastoreCollectionObject

Parameters

property (string): The property ID by which to group as defined in the Blueprint.

Returns

DatastoreCollectionObject: A DatastoreCollectionObject allows for the groupBy() method to be chained to a collection request to the Data Service.

Example

Do the following to use the JS SDK to count all the student documents grouped by campus from the 'students' collection:

const students = await datastore.collection(`students`).count().groupBy(`campus`).get();

segment()

Gets a segment for a collection.

Signature

segment(segmentName: string): Promise<object | Array<objects>>

Parameters

segmentName (string): The name of the segment to be returned.

Returns

Promise<object | Array<object>>: A Promise resolved with an object of data and pagination details or an array of Document Objects as defined in the Blueprint.

Example

Do the following to use the JS SDK to get the at-risk segment for the 'students' collection:

const atRiskStudents = await datastore.collection(`students`).segment(`at-risk`).get();