react-native-ibm-mobilefirst-jsonstore/js/JSONStoreCollection.js

React Native SDK for IBM JSONStore. Works with IBM Mobile First

/* Licensed Materials - Property of IBM
 * 5725-I43 (C) Copyright IBM Corp. 2018. All Rights Reserved.
 * US Government Users Restricted Rights - Use, duplication or
 * disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
 */

/* author - Yash Soni | yashsoni21@in.ibm.com */

import {
    NativeModules,
    Platform,
    DeviceEventEmitter
} from 'react-native';

import { _mandatoryParam, _checkParamClassType, _checkParamType, _checkParamArrayType, ParamTypes } from './Utils'
import JSONStoreChangeOptions from './JSONStoreChangeOptions'
import JSONStoreAddOptions from './JSONStoreAddOptions'
import JSONStoreFindOptions from './JSONStoreFindOptions';
import {JSONStoreQueryPart, queryPartMap} from './JSONStoreQueryPart';

var jsonStoreCollection = NativeModules.RNJSONStoreCollection;

DeviceEventEmitter.addListener('syncSuccessEvent', function(event) {
    console.log("Successfully synced collection: '" + event.collectionName + "'.");
});

DeviceEventEmitter.addListener('syncFailureEvent', function(event) {
    console.log("Failed to sync collection: '" + event.collectionName + "'.");
});

const nameMap = new Map();

/**
 * This class represents a single JSONStore collection. Operations on the collection can be done by using the API for this class.
 */
class JSONStoreCollection {
    /**
     * @param {string} name - the name of the JSONStoreCollection.
     */
    constructor(name = _mandatoryParam('name')) {
        _checkParamType(name, ParamTypes.STRING);
        if(name.toString().trim().length == 0) {
            console.log("Collection name cannot be an empty string!");
            return new Error("Collection name cannot be an empty string!");
        }
        nameMap.set(this, name);
        jsonStoreCollection
            .createCollection(name);
    }


     /* Search Field Type Constants */
   static get BOOLEAN(){
        return "boolean";
    }
    static get INTEGER(){
        return "integer";
    }
    static get NUMBER(){
        return "number";
    }
    static get STRING(){
        return "string";
    }


    /**
     * Add data and create a new document in the collection.
     * @param {JSON} data - New JSON data to be added to the collection
     * @param {JSONStoreAddOptions} [options] - Options to be applied while adding the object
     * @return {Promise<string, JSON>} - This function returns an empty string in case of success and it returns a JSON in case of any error
     * @example - If the promise is rejected, an error JSON in the following format is available with more information.
     * {
     *      errorMsg: "Error adding data to collection: favourites",
     *      reason: "Collection is not initialized."
     * }
     */
    async addData(data = _mandatoryParam('data'), options = new JSONStoreAddOptions()) {
        _checkParamClassType(data, Object);
        _checkParamClassType(options, JSONStoreAddOptions);
        if(data instanceof Array) {
            result = await jsonStoreCollection.addDataArray(nameMap.get(this), data, options);
        } else {
            result = await jsonStoreCollection.addDataObject(nameMap.get(this), data, options);
        }
        return result;
    }

    /**
     * Change a list of documents in the collection.
     * @param {Array} dataList - List of JSON documents
     * @param {JSONStoreChangeOptions} [jsonStoreChangeOptions] - Options to be applied while changing the objects
     * @return {Promise<number, JSON>} - This function returns a number indicative of number of documents affected and it returns a JSON in case of any error
     * @example - If the promise is rejected, an error JSON in the following format is available with more information.
     * {
     *      errorMsg: "Error adding data to collection: favourites",
     *      reason: "Collection is not initialized."
     * }
     */
    async changeData(dataList = _mandatoryParam('dataList'), jsonStoreChangeOptions = new JSONStoreChangeOptions()) {
        _checkParamClassType(dataList, Array);
        _checkParamClassType(jsonStoreChangeOptions , JSONStoreChangeOptions);
        result = await jsonStoreCollection.changeData(nameMap.get(this), dataList, jsonStoreChangeOptions);
        return result;
    }

    /**
     * Count the number of documents in the collection.
     * @return {Promise<number, JSON>} - This function returns a number indicative of the count of all documents. In case of any error this function returns a JSON.
     * @example - If the promise is rejected, an error JSON in the following format is available with more information.
     * {
     *      errorMsg: "Error adding data to collection: favourites",
     *      reason: "Collection is not initialized."
     * }
     */
    async countAllDocuments() {
        result = await jsonStoreCollection.countAllDocuments(nameMap.get(this));
        return result;
    }

    /**
     * Count the number of dirty documents in the collection.
     * @return {Promise<number, JSON>} - This function returns a number indicative of the count of all dirty documents. In case of any error this function returns a JSON.
     * @example - If the promise is rejected, an error JSON in the following format is available with more information.
     * {
     *      errorMsg: "Error adding data to collection: favourites",
     *      reason: "Collection is not initialized."
     * }
     */
    async countAllDirtyDocuments() {
        result = await jsonStoreCollection.countAllDirtyDocuments(nameMap.get(this));
        return result;
    }

    /**
     * Count the number of documents in the collection that are based on the given query.
     * @param {Array<JSONStoreQueryPart>} query - An array of JSONStoreQueryPart objects that limits the count scope. Every query part in the arrayare joined by an OR operation.
     * @param {boolean} [includeDeleted] - Additional options to modify the count operation.
     * @return {Promise<number, JSON>} - This function returns a number indicative of the count of documents based on given query and whether to include deleted documents. In case of any error this function returns a JSON.
     * @example - If the promise is rejected, an error JSON in the following format is available with more information.
     * {
     *      errorMsg: "Error adding data to collection: favourites",
     *      reason: "Collection is not initialized."
     * }
     */
    async countDocuments(query = _mandatoryParam('query'), includeDeleted = false) {
        _checkParamArrayType(query, JSONStoreQueryPart);
        _checkParamType(includeDeleted, ParamTypes.BOOLEAN);

        var queryArray = new Array();
        for( var q of query) {
            queryArray.push(queryPartMap.get(q)) ;
        }

        result = await jsonStoreCollection.countDocuments(nameMap.get(this), queryArray, includeDeleted);
        return result;
    }

    /**
     * Removes all documents from a collection, but does not destroy the collection.
     * @return {Promise<string, JSON>} - This function returns an empty string in case of success. In case of any error this function returns a JSON.
     * @example - If the promise is rejected, an error JSON in the following format is available with more information.
     * {
     *      errorMsg: "Error adding data to collection: favourites",
     *      reason: "Collection is not initialized."
     * }
     */
    async clearCollection() {
        result = await jsonStoreCollection.clearCollection(nameMap.get(this));
        return result;
    }

    /**
     * Find all the dirty documents in the collection.
     * @return {Promise<Array, JSON>} - This function returns an array of documents that are found dirty in the collection. In case of any error this function returns a JSON.
     * @example - If the promise is rejected, an error JSON in the following format is available with more information.
     * {
     *      errorMsg: "Error adding data to collection: favourites",
     *      reason: "Collection is not initialized."
     * }
     */
    async findAllDirtyDocuments() {
        result = await jsonStoreCollection.findAllDirtyDocuments(nameMap.get(this));
        return result;
    }

    /**
     * Find all documents in the collection.
     * @param {JSONStoreFindOptions} [options] - The find query that restricts the search.
     * @return {Promise<Array, JSON>} - This function returns an array of documents that are found in the collection with the given Find Options. In case of any error this function returns a JSON.
     * @example - If the promise is rejected, an error JSON in the following format is available with more information.
     * {
     *      errorMsg: "Error adding data to collection: favourites",
     *      reason: "Collection is not initialized."
     * }
     */
    async findAllDocuments(options = new JSONStoreFindOptions()) {
        _checkParamClassType(options, JSONStoreFindOptions);

        result = await jsonStoreCollection.findAllDocuments(nameMap.get(this), options);
        return result;
    }

    /**
     * Find a document in the collection based on the given ID.
     * @param {number} id - The unique id that is associated with a document in the database (the _id search field).
     * @return {Promise<object, JSON>} - This function returns a document that is found for this given id. In case of any error this function returns a JSON.
     * @example - If the promise is rejected, an error JSON in the following format is available with more information.
     * {
     *      errorMsg: "Error adding data to collection: favourites",
     *      reason: "Collection is not initialized."
     * }
     */
    async findDocumentById(id = _mandatoryParam('id')) {
        _checkParamType(id, ParamTypes.NUMBER);
        result = await jsonStoreCollection.findDocumentById(nameMap.get(this), id);
        return result;
    }

    /**
     * Find all documents in the collection that have the given ids.
     * @param {Array} ids - An array of unique ids that are associated with a document in the database (the _id search field).
     * @return {Promise<Array, JSON>} - This function returns an array of all the documents that are found for this given ids. In case of any error this function returns a JSON.
     * @example - If the promise is rejected, an error JSON in the following format is available with more information.
     * {
     *      errorMsg: "Error adding data to collection: favourites",
     *      reason: "Collection is not initialized."
     * }
     */
    async findDocumentsById(ids = _mandatoryParam('ids')) {
        _checkParamClassType(ids, Array);
        result = await jsonStoreCollection.findDocumentsById(nameMap.get(this), ids);
        return result;
    }

    /**
     * Find documents in the collection that are based on the given query.
     * @param {Array<JSONStoreQueryPart>} query -  An array of JSONStoreQueryPart objects that limits the count scope. Every query part in the arrayare joined by an OR operation.
     * @param {JSONStoreFindOptions} [options] - Additional options to modify the count operation.
     * @return {Promise<Array, JSON>} - This function returns an array of all the documents that are found for this given query and find options. In case of any error this function returns a JSON.
     * @example - If the promise is rejected, an error JSON in the following format is available with more information.
     * {
     *      errorMsg: "Error adding data to collection: favourites",
     *      reason: "Collection is not initialized."
     * }
     */
    async findDocuments(query = _mandatoryParam('query'), options = new JSONStoreFindOptions()) {
        _checkParamArrayType(query, JSONStoreQueryPart);
        _checkParamClassType(options, JSONStoreFindOptions);

        var queryArray = new Array();
        for( var q of query) {
            queryArray.push(queryPartMap.get(q)) ;
        }
        result = await jsonStoreCollection.findDocuments(nameMap.get(this), queryArray, options);
        return result;
    }

    /**
     * Get a map of the additional search fields for this collection.
     * @return {Promise<object>} - This function returns an object of all the additional search fields for the given collection.
     */
    async getAdditionalSearchFields() {
        result = await jsonStoreCollection.getAdditionalSearchFields(nameMap.get(this));
        return result;
    }

    /**
     * Get a map of all search fields for this collection.
     * @return {Promise<object>} - This function returns an object of all the search fields for the given collection.
     */
    async getSearchFields() {
        result = await jsonStoreCollection.getSearchFields(nameMap.get(this));
        return result;
    }

    /**
     * Determines if the collection contains the given additional search field.
     * @param {string} searchField - The name of the additional search field to check for existence.
     * @return {Promise<boolean, JSON>} - This function returns a boolean value indicative of whether the collection contains the given additional search field or not, and it returns a JSON in case of any error
     * @example - If the promise is rejected, an error JSON in the following format is available with more information.
     * {
     *      errorMsg: "Error adding data to collection: favourites",
     *      reason: "Collection is not initialized."
     * }
     */
    async hasAdditionalSearchField(searchField = _mandatoryParam('searchField')) {
        _checkParamType(searchField, ParamTypes.STRING);
        result = await jsonStoreCollection.hasAdditionalSearchField(nameMap.get(this), searchField);
        return result;
    }

    /**
     * The name of the search field to check for existence.
     * @param {string} searchField - The name of the additional search field to check for existence.
     * @return {Promise<boolean, JSON>} - This function returns a boolean value indicative of whether the collection contains the given search field or not, and it returns a JSON in case of any error
     * @example - If the promise is rejected, an error JSON in the following format is available with more information.
     * {
     *      errorMsg: "Error adding data to collection: favourites",
     *      reason: "Collection is not initialized."
     * }
     */
    async hasSearchField(searchField = _mandatoryParam('searchField')) {
        _checkParamType(searchField, ParamTypes.STRING);
        result = await jsonStoreCollection.hasSearchField(nameMap.get(this), searchField);
        return result;
    }

    /**
     * Determine if a document is dirty or not.
     * @param {number} id - ID of the document to be checked.
     * @return {Promise<boolean, JSON>} - This function returns a boolean value indicative of whether the document is dirty or not, and it returns a JSON in case of any error
     * @example - If the promise is rejected, an error JSON in the following format is available with more information.
     * {
     *      errorMsg: "Error adding data to collection: favourites",
     *      reason: "Collection is not initialized."
     * }
     */
    async isDocumentDirty(id = _mandatoryParam('id')) {
        _checkParamType(id, ParamTypes.NUMBER);
        result = await jsonStoreCollection.isDocumentDirty(nameMap.get(this), id);
        return result;
    }

    /**
     * Mark a document in the collection clean.
     * @param {JSON} document - JSON document to be marked as clean.
     * @return {Promise<number, JSON>} - This function returns a number indicative of number of documents affected and it returns a JSON in case of any error
     * @example - If the promise is rejected, an error JSON in the following format is available with more information.
     * {
     *      errorMsg: "Error adding data to collection: favourites",
     *      reason: "Collection is not initialized."
     * }
     */
    async markDocumentClean(document = _mandatoryParam('document')) {
        _checkParamClassType(document, Object);
        result = await jsonStoreCollection.markDocumentClean(nameMap.get(this), document);
        return result;
    }

    /**
     * Mark an array of documents in the collection clean.
     * @param {Array} documents - An Array of JSON documents to be marked as clean.
     * @return {Promise<number, JSON>} - This function returns a number indicative of number of documents affected and it returns a JSON in case of any error
     * @example - If the promise is rejected, an error JSON in the following format is available with more information.
     * {
     *      errorMsg: "Error adding data to collection: favourites",
     *      reason: "Collection is not initialized."
     * }
     */
    async markDocumentsClean(documents = _mandatoryParam('documents')) {
        _checkParamClassType(documents, Array);
        result = await jsonStoreCollection.markDocumentsClean(nameMap.get(this), documents);
        return result;
    }

    /**
     * Permanently deletes all the documents that are stored in a collection and destroys the collection.
     * @return {Promise<string, JSON>} - This function returns an empty string in case of success and it returns a JSON in case of any error
     * @example - If the promise is rejected, an error JSON in the following format is available with more information.
     * {
     *      errorMsg: "Error adding data to collection: favourites",
     *      reason: "Collection is not initialized."
     * }
     */
    async removeCollection() {
        result = await jsonStoreCollection.removeCollection(nameMap.get(this));
        return result;
    }

    /**
     * Remove a document from the collection that is based on the given id.
     * @param {number} id - ID of the document to be deleted.
     * @param {boolean} [markDirty] - Mark the document as dirty. Default is false.
     * @return {Promise<number, JSON>} - This function returns a number indicative of number of documents affected and it returns a JSON in case of any error
     * @example - If the promise is rejected, an error JSON in the following format is available with more information.
     * {
     *      errorMsg: "Error adding data to collection: favourites",
     *      reason: "Collection is not initialized."
     * }
     */
    async removeDocumentById(id = _mandatoryParam('id'), markDirty = false) {
        _checkParamType(id, ParamTypes.NUMBER);
        _checkParamType(markDirty, ParamTypes.BOOLEAN);
        result = await jsonStoreCollection.removeDocumentById(nameMap.get(this), id, markDirty);
        return result;
    }

    /**
     * Remove array of documents from the collection, based on the given ids.
     * @param {Array} ids - ID of the document to be deleted.
     * @param {boolean} [markDirty] - Mark the document as dirty using this flag. Default is false.
     * @return {Promise<number, JSON>} - This function returns a number indicative of number of documents affected and it returns a JSON in case of any error
     * @example - If the promise is rejected, an error JSON in the following format is available with more information.
     * {
     *      errorMsg: "Error adding data to collection: favourites",
     *      reason: "Collection is not initialized."
     * }
     */
    async removeDocumentsById(ids = _mandatoryParam('id'), markDirty = false) {
        _checkParamClassType(ids, Array);
        _checkParamType(markDirty, ParamTypes.BOOLEAN);
        result = await jsonStoreCollection.removeDocumentsById(nameMap.get(this), ids, markDirty);
        return result;
    }

    /**
     * Replace a document in the collection.
     * @param {JSON} document - A JSONObject that represents the document to update in the collection. The document's '_id' is used to determine which document to replace.
     * @param {boolean} [markDirty] - Mark the document as dirty using this flag. Default is false.
     * @return {Promise<number, JSON>} - This function returns a number indicative of number of documents affected and it returns a JSON in case of any error
     * @example - If the promise is rejected, an error JSON in the following format is available with more information.
     * {
     *      errorMsg: "Error adding data to collection: favourites",
     *      reason: "Collection is not initialized."
     * }
     */
    async replaceDocument(document = _mandatoryParam('document'), markDirty = false) {
        _checkParamClassType(document, Object);
        _checkParamType(markDirty, ParamTypes.BOOLEAN);
        result = await jsonStoreCollection.replaceDocument(nameMap.get(this), document, markDirty);
        return result;
    }

    /**
     * Replace an array of documents in the collection.
     * @param {Array} documents - A List that contains JSONObjects that represent the documents to update in the collection. The document's '_id' is used to determine which document to replace. If all documents could not be updated, a rollback is performed to a state where no documents were updated.
     * @param {boolean} [markDirty] - Mark the document as dirty using this flag. Default is false.
     * @return {Promise<number, JSON>} - This function returns a number indicative of number of documents affected and it returns a JSON in case of any error
     * @example - If the promise is rejected, an error JSON in the following format is available with more information.
     * {
     *      errorMsg: "Error adding data to collection: favourites",
     *      reason: "Collection is not initialized."
     * }
     */
    async replaceDocuments(documents = _mandatoryParam('document'), markDirty = false) {
        _checkParamClassType(documents, Array);
        _checkParamType(markDirty, ParamTypes.BOOLEAN);
        result = await jsonStoreCollection.replaceDocuments(nameMap.get(this), documents, markDirty);
        return result;
    }

    /**
     * Set an additional search field for the collection.
     * @param {string} key - The name of the additional search field to add. Only useful before the collection is opened.
     * @param {string} searchFieldType - The type of the search field. Accepted values are ('boolean', 'integer', 'number', 'string')
     */
    setAdditionalSearchField(key = _mandatoryParam('key'), searchFieldType = _mandatoryParam('searchFieldType')) {
        _checkParamType(key, ParamTypes.STRING);
        _checkParamType(searchFieldType, ParamTypes.STRING);

        if (searchFieldType != "boolean" &&
            searchFieldType != "integer" &&
            searchFieldType != "number" &&
            searchFieldType != "string") {
            return Error(`Accepted value for searchFieldType is JSONStoreCollection.BOOLEAN, JSONStoreCollection.INTEGER, JSONStoreCollection.NUMBER OR JSONStoreCollection.STRING. ${searchFieldType} is not valid.`);
        }
        jsonStoreCollection.setAdditionalSearchField(nameMap.get(this), key, searchFieldType);
    }

    /**
     * Set a search field for the collection.
     * @param {string} key - The name of the additional search field to add. Only useful before the collection is opened.
     * @param {string} searchFieldType - The type of the search field. Accepted values are ('boolean', 'integer', 'number', 'string')
     */
    setSearchField(key = _mandatoryParam('key'), searchFieldType = _mandatoryParam('searchFieldType')) {
        _checkParamType(key, ParamTypes.STRING);
        _checkParamType(searchFieldType, ParamTypes.STRING);

        if (searchFieldType != "boolean" &&
            searchFieldType != "integer" &&
            searchFieldType != "number" &&
            searchFieldType != "string") {
            return Error(`Accepted value for searchFieldType is JSONStoreCollection.BOOLEAN, JSONStoreCollection.INTEGER, JSONStoreCollection.NUMBER OR JSONStoreCollection.STRING. ${searchFieldType} is not valid.`);
        }
        jsonStoreCollection.setSearchField(nameMap.get(this), key, searchFieldType);
    }

    /**
     * Sync this collection based on Sync policy set when the collection was opened.
     */
    sync() {
        jsonStoreCollection.sync(nameMap.get(this));
    }

    /**
     * Determine if the collection was reopened when it was initialized.
     * @return {Promise<boolean, JSON>} - This function returns a boolean value and it returns a JSON in case of any error
     * @example - If the promise is rejected, an error JSON in the following format is available with more information.
     * {
     *      errorMsg: "Error adding data to collection: favourites",
     *      reason: "Collection is not initialized."
     * }
     */
    async wasReopened() {
        result = jsonStoreCollection.wasReopened(nameMap.get(this));
        return result;
    }
}

export default JSONStoreCollection