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>
html
Configuring your data service in your app
const settings = {
serviceURL: '<Your data service URL here>'
};
const datastore = new Datastore(settings);
javascript
The settings available for the Datastore JS SDK are:
Setting |
Required |
Simulator only |
Description |
Type |
=== Example |
serviceURL |
Yes |
No |
The Data Service or Simulators URL. |
String |
https://my-data-service.datastore.squiz.cloud |
jwtURL |
No |
No |
The URL to the JWT generator being used. |
String |
https://my-jwt.example.com |
jwtCallback |
No |
No |
A custom callback function to get a JWT token. Must return a promise. |
Function |
|
jwtPayload |
No |
Yes |
Optional JWT Payload. Required when using the Simulator’s built-in JWT generator. |
Object |
|
detailedResponse |
No |
Yes |
A flag to return the detailed response of a request, for example, headers, status code, and more. |
Boolean |
true |
interceptRequest |
No |
Yes |
An object to flag to return the request information (params, headers) for specified paths before sending the request. |
Object |
|
failRequests |
No |
Yes |
Fail requests for specific paths with the given error object. |
Object |
Function List
Function | Description |
---|---|
Gets a DatastoreCollectionObject reference to perform actions on the collection in the Data Service. |
|
Gets a DatastoreDocumentObject reference to perform actions on the document in the Data Service. |
|
Set the settings on the Datastore JS SDK object. |
|
Set a setting on the Datastore JS SDK object. |
|
Gets a setting value from the Datastore JS SDK object. |
|
Gets the JWT Payload for the token that’s been requested. |
|
Adds a new document to a collection in a Data Service. |
|
Gets all the documents in a collection of a Data Service. |
|
Gets a document from a collection in a Data Service. |
|
Updates a document from a collection in a Data Service. |
|
Deletes a document from a collection in a Data Service. |
|
Sets a page limit for how many documents will be returned in a get collection request. |
|
Checks if there is a next page when making pagination requests. |
|
Checks if there is a previous page when making pagination requests. |
|
Gets the next page in a pagination request. |
|
Gets the previous page in a pagination request. |
|
Sorts the documents in a collection request. |
|
Starts the filtering settings for a collection request. |
|
Specifies an and statement in the filtering settings for a collection request. |
|
Specifies an or statement in the filtering settings for a collection request. |
|
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. |
|
Specifies a count of documents with the property specified on a collection request. |
|
Specifies a property to be used by which to group the aggregation result. |
|
Gets a segment for a collection. |
collection()
Gets a DatastoreCollectionObject reference to perform actions on the collection in the Data Service.
doc()
Gets a DatastoreDocumentObject reference to perform actions on the document in the Data Service.
setSettings()
Set the settings on the Datastore JS SDK object.
Parameters
- settings (object)
-
The settings for the Datastore JS SDK object to use.
setSetting()
Set a setting on the Datastore JS SDK object.
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.
getSetting()
Gets a setting value from the Datastore JS SDK object.
Parameters
- setting (string)
-
The setting name to be retrieved.
add()
Adds a new document to a collection in a Data Service.
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);
javascript
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`);
javascript
get() - collection
get() - document
update()
Updates a document from a collection in a Data Service.
Parameters
- data (object)
-
A JSON object consisting of property and value pairs, matching the JSON schema defined for the data service’s (Datastore) blueprint.
limit()
sortBy()
Sorts the documents in a collection request.
Signature
sortBy(property: string, direction: string | undefined): DatastoreCollectionObject
javascript
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
ordesc
. The default isasc
.
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();
javascript
where()
Starts the filtering settings for a collection request.
Signature
where(property: string | DatastoreFilter, comparison: string, value: any): DatastoreCollectionObject
javascript
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.
and()
Specifies an 'and' statement in the filtering settings for a collection request.
Signature
and(property: string | DatastoreFilter, comparison: string, value: any): DatastoreCollectionObject
javascript
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();
javascript
or()
Specifies an or statement in the filtering settings for a collection request.
Signature
or(property: string | DatastoreFilter, comparison: string, value: any): DatastoreCollectionObject
javascript
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();
javascript
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
javascript
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();
javascript
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();
javascript
count()
Specifies a count of documents with the property specified on a collection request.
Parameters
- property (string | undefined)
-
The property ID on which to count as defined in the Blueprint or undefined. Defaults to Document ID.