jxp-helper 1.4.2 → 1.4.3

package/jxp-helper.js

@@ -1,12 +1,33 @@
 var axios = require("axios");
 
+/**
+ * JXPHelper class for interacting with a JXP server.
+ * @class
+ */
 class JXPHelper {
+	/**
+	 * Creates a new instance of the JXP Helper class.
+	 * @param {Object} opts - The options for configuring the JXP Helper.
+	 * @param {string} opts.server - The server URL.
+	 * @param {string} opts.apikey - The API key for the user.
+	 * @param {boolean} [opts.debug=false] - Whether to enable debug mode.
+	 * @param {boolean} [opts.hideErrors=false] - Whether to hide errors.
+	 */
 	constructor(opts) {
+		const defaults = {
+			debug: false,
+			hideErrors: false
+		};
+		opts = Object.assign({}, defaults, opts);
 		this.config(opts);
 		if (!this.server) throw ("parameter 'server' required");
 		this.api = this.server + "/api";
 	}
-	
+
+	/**
+	 * Configures the options for the jxp-helper.
+	 * @param {Object} opts - The options to configure.
+	 */
 	config(opts) {
 		for (var opt in opts) {
 			this[opt] = opts[opt];
@@ -35,7 +56,7 @@ class JXPHelper {
 
 	_displayError(err) {
 		try {
-			if (this.opts.hideErrors) return;
+			if (this.hideErrors) return;
 			console.error(`${new Date().toISOString()}\turl: ${err.config.url}\tmethod: ${err.request.method}\tstatus: ${err.response.status}\tstatusText: ${err.response.statusText}\tdata: ${(err.response.data) ? JSON.stringify(err.response.data) : 'No data'}`);
 		} catch (err) {
 			console.error(err);
@@ -46,6 +67,13 @@ class JXPHelper {
 		return `${this.server}/${ep}/${type}?${this._configParams(opts)}`;
 	}
 
+
+	/**
+	 * Logs in a user with the provided email and password.
+	 * @param {string} email - The user's email.
+	 * @param {string} password - The user's password.
+	 * @returns {Promise<{ data: any, user: any } | any>} - A promise that resolves to an object containing the login data and user information, or rejects with an error object.
+	 */
 	async login(email, password) {
 		try {
 			const data = (await axios.post(`${this.server}/login`, { email, password })).data;
@@ -56,6 +84,15 @@ class JXPHelper {
 		}
 	}
 
+	/**
+	 * Retrieves a single item of a specified type by its ID.
+	 *
+	 * @param {string} type - The type of the item.
+	 * @param {string} id - The ID of the item.
+	 * @param {Object} opts - Additional options for the request.
+	 * @returns {Promise<Object>} - A promise that resolves to the retrieved item.
+	 * @throws {Error} - If the request fails or returns a non-200 status code.
+	 */
 	async getOne(type, id, opts) {
 		const label = `getOne.${type}-${this._randomString()}`;
 		if (this.debug) console.time(label);
@@ -74,6 +111,14 @@ class JXPHelper {
 		}
 	}
 
+
+	/**
+	 * Retrieves data of a specified type from a URL.
+	 * @param {string} type - The type of data to retrieve.
+	 * @param {Object} opts - Additional options for the request.
+	 * @returns {Promise<any>} - A promise that resolves with the retrieved data.
+	 * @throws {Error} - If the request fails or returns a non-200 status code.
+	 */
 	async get(type, opts) {
 		const label = `get.${type}-${this._randomString()}`;
 		if (this.debug) console.time(label);
@@ -92,6 +137,13 @@ class JXPHelper {
 		}
 	}
 
+	/**
+	 * Retrieves data in CSV format from the server.
+	 * @param {string} type - The type of data to retrieve.
+	 * @param {Object} opts - Additional options for the request.
+	 * @returns {Promise<string>} - The CSV data.
+	 * @throws {Error} - If the request fails or returns a non-200 status code.
+	 */
 	async csv(type, opts) {
 		const label = `get.${type}-${this._randomString()}`;
 		if (this.debug) console.time(label);
@@ -110,6 +162,14 @@ class JXPHelper {
 		}
 	}
 
+	/**
+	 * Executes a query of the specified type with the given parameters.
+	 * @param {string} type - The type of query to execute.
+	 * @param {string} query - The query string.
+	 * @param {Object} opts - Additional options for the query.
+	 * @returns {Promise<any>} - A promise that resolves to the query result.
+	 * @throws {Error} - If the query fails or returns a non-200 status code.
+	 */
 	async query(type, query, opts) {
 		const label = `query.${type}-${this._randomString()}`;
 		if (this.debug) console.time(label);
@@ -128,6 +188,14 @@ class JXPHelper {
 		}
 	}
 
+	/**
+	 * Performs an aggregate operation on the specified type with the given query and options.
+	 * @param {string} type - The type to perform the aggregate operation on.
+	 * @param {object} query - The query object for the aggregate operation.
+	 * @param {object} opts - The options for the aggregate operation.
+	 * @returns {Promise<object>} - The result of the aggregate operation.
+	 * @throws {Error} - If the aggregate operation fails.
+	 */
 	async aggregate(type, query, opts) {
 		const label = `aggregate.${type}-${this._randomString()}`;
 		if (this.debug) console.time(label);
@@ -146,6 +214,17 @@ class JXPHelper {
 		}
 	}
 
+	/**
+	 * Performs a bulk post or put operation.
+	 * If the data parameter is an array, it performs a bulk update operation.
+	 * If the data parameter is an object, it performs a single post or put operation.
+	 *
+	 * @param {string} type - The type of operation to perform (post or put).
+	 * @param {string|string[]} key - The key(s) used to filter the data for the update operation.
+	 * @param {object|object[]} data - The data to be updated or inserted.
+	 * @returns {Promise} - A promise that resolves with the result of the bulk operation.
+	 * @throws {Error} - If an error occurs during the bulk operation.
+	 */
 	async bulk_postput(type, key, data) {
 		try {
 			if (!Array.isArray(data)) return await this.postput(type, key, data);
@@ -174,6 +253,14 @@ class JXPHelper {
 		}
 	}
 
+	/**
+	 * Performs a bulk update operation for a given type of data.
+	 * @param {string} type - The type of data to update.
+	 * @param {string} key - The key to use for filtering and updating the data.
+	 * @param {Array<Object>} data - The array of data objects to update.
+	 * @returns {Promise<Object>} - A promise that resolves to the response data from the bulk update operation.
+	 * @throws {Error} - If an error occurs during the bulk update operation.
+	 */
 	async bulk_put(type, key, data) {
 		try {
 			const updates = data.map(item => {
@@ -195,6 +282,13 @@ class JXPHelper {
 		}
 	}
 
+	/**
+	 * Performs a bulk post operation.
+	 * @param {string} type - The type of data to be posted.
+	 * @param {Array} data - The data to be posted.
+	 * @returns {Promise} - A promise that resolves with the response data.
+	 * @throws {Error} - If an error occurs during the operation.
+	 */
 	async bulk_post(type, data) {
 		try {
 			const updates = data.map(item => {
@@ -212,6 +306,13 @@ class JXPHelper {
 		}
 	}
 
+	/**
+	 * Performs a bulk write operation for a given type using the specified query.
+	 * @param {string} type - The type of the bulk write operation.
+	 * @param {object} query - The query object for the bulk write operation.
+	 * @returns {Promise<any>} - A promise that resolves to the result of the bulk write operation.
+	 * @throws {Error} - If an error occurs during the bulk write operation.
+	 */
 	async bulk(type, query) {
 		try {
 			if (this.debug) console.log("bulk", type);
@@ -223,7 +324,13 @@ class JXPHelper {
 		}
 	}
 
-	// A very fast way to update ALL rows in a collection, with no seatbelts
+	/**
+	 * Updates multiple documents of a specified type in the database.
+	 * @param {string} type - The type of documents to update.
+	 * @param {object} data - The data to update the documents with.
+	 * @returns {Promise<object>} - The response data from the database.
+	 * @throws {Error} - If an error occurs during the update process.
+	 */
 	async put_all(type, data) {
 		try {
 			if (this.debug) console.log("put_all", type);
@@ -244,6 +351,13 @@ class JXPHelper {
 		}
 	}
 
+	/**
+	 * Counts the number of items of a given type.
+	 * 
+	 * @param {string} type - The type of items to count.
+	 * @param {object} opts - Additional options for counting.
+	 * @returns {Promise<number>} - The count of items.
+	 */
 	async count(type, opts) {
 		const label = `count.${type}-${this._randomString()}`;
 		if (this.debug) console.time(label);
@@ -264,6 +378,13 @@ class JXPHelper {
 		}
 	}
 
+	/**
+	 * Creates a new record by making a POST request to the specified URL.
+	 * 
+	 * @param {string} type - The type of data to post.
+	 * @param {object} data - The data to post.
+	 * @returns {<Promise<object>} - The response data from the post operation.
+	 */
 	async post(type, data) {
 		var url = `${this.api}/${type}?apikey=${this.apikey}`;
 		if (this.debug) console.log("POSTing to ", url, data);
@@ -275,6 +396,16 @@ class JXPHelper {
 		}
 	}
 
+
+	/**
+	 * Updates an existing record by making a PUT request to the specified URL.
+	 * 
+	 * @param {string} type - The type of the record.
+	 * @param {string} id - The ID of the record.
+	 * @param {Object} data - The data to be sent in the request body.
+	 * @returns {Promise<Object>} - A promise that resolves to the response data.
+	 * @throws {Error} - If an error occurs during the request.
+	 */
 	async put(type, id, data) {
 		var url = `${this.api}/${type}/${id}?apikey=${this.apikey}`;
 		if (this.debug) console.log("PUTting to ", url, data);
@@ -286,6 +417,16 @@ class JXPHelper {
 		}
 	}
 
+	/**
+	 * Performs a POST or PUT request based on the existence of a specific key in the data object.
+	 * If the key exists in the data object, a PUT request is made with the corresponding ID.
+	 * If the key does not exist, a POST request is made with the data object.
+	 * 
+	 * @param {string} type - The type of resource to perform the request on.
+	 * @param {string} key - The key to check in the data object.
+	 * @param {object} data - The data object to be sent in the request.
+	 * @returns {Promise} - A promise that resolves with the response data or rejects with an error.
+	 */
 	async postput(type, key, data) {
 		// Post if we find key=id, else put
 		var obj = {};
@@ -303,7 +444,15 @@ class JXPHelper {
 			throw(err.response ? err.response.data : err);
 		}
 	}
-
+	
+	/**
+	 * Deletes an item of the specified type by its ID.
+	 * 
+	 * @param {string} type - The type of the item to delete.
+	 * @param {string} id - The ID of the item to delete.
+	 * @returns {Promise<any>} - A promise that resolves to the deleted item.
+	 * @throws {Error} - If an error occurs during the deletion process.
+	 */
 	async del(type, id) {
 		const url = `${this.api}/${type}/${id}?apikey=${this.apikey}`;
 		try {
@@ -314,7 +463,15 @@ class JXPHelper {
 		}
 	}
 
-	// Permanently delete
+	
+	/**
+	 * Deletes a resource permanently.
+	 *
+	 * @param {string} type - The type of resource to delete.
+	 * @param {string} id - The ID of the resource to delete.
+	 * @returns {Promise<any>} - A promise that resolves to the deleted resource data.
+	 * @throws {Error} - If an error occurs during the deletion process.
+	 */
 	async del_perm(type, id) {
 		const url = `${this.api}/${type}/${id}?_permaDelete=1&apikey=${this.apikey}`;
 		try {
@@ -325,6 +482,13 @@ class JXPHelper {
 		}
 	}
 
+	/**
+	 * Soft Deletes a resource and its cascading dependencies.
+	 * @param {string} type - The type of the resource to delete.
+	 * @param {string} id - The ID of the resource to delete.
+	 * @returns {Promise<any>} - A promise that resolves with the deleted resource data.
+	 * @throws {Error} - If an error occurs during the deletion process.
+	 */
 	async del_cascade(type, id) {
 		var url = `${this.api}/${type}/${id}?_cascade=1&apikey=${this.apikey}`;
 		try {
@@ -335,6 +499,13 @@ class JXPHelper {
 		}
 	}
 
+	/**
+	 * Permanently Deletes a resource and its associated data permanently, including all cascading dependencies.
+	 * @param {string} type - The type of resource to delete.
+	 * @param {string} id - The ID of the resource to delete.
+	 * @returns {Promise<any>} - A promise that resolves to the response data from the delete request.
+	 * @throws {Error} - If an error occurs during the delete request.
+	 */
 	async del_perm_cascade(type, id) {
 		var url = `${this.api}/${type}/${id}?_cascade=1&_permaDelete=1&apikey=${this.apikey}`;
 		try {
@@ -345,7 +516,16 @@ class JXPHelper {
 		}
 	}
 
-	// This should be rewritten as an async pattern
+	
+	/**
+	 * Deletes all items of a specified type that match a given key-value pair.
+	 * 
+	 * @param {string} type - The type of items to delete.
+	 * @param {string} key - The key to filter the items.
+	 * @param {string} id - The value to match against the key.
+	 * @returns {Promise<Array>} - A promise that resolves to an array of results from deleting each item.
+	 * @throws {Error} - If an error occurs during the deletion process.
+	 */
 	async del_all(type, key, id) {
 		var obj = {};
 		obj[`filter[${key}]`] = id;
@@ -395,6 +575,15 @@ class JXPHelper {
 		}
 	}
 
+	/**
+	 * Calls a function in the model.
+	 * 
+	 * @param {string} type - The type of the function.
+	 * @param {string} cmd - The command to be executed.
+	 * @param {object} data - The data to be sent with the request.
+	 * @returns {Promise<any>} - A promise that resolves to the response data.
+	 * @throws {any} - Throws an error if the request fails.
+	 */
 	async call(type, cmd, data) {
 		//Call a function in the model
 		var url = `${this.server}/call/${type}/${cmd}?apikey=${this.apikey}`;
@@ -406,6 +595,14 @@ class JXPHelper {
 		}
 	}
 
+	/**
+	 * Updates the groups for a user.
+	 * 
+	 * @param {string} user_id - The ID of the user.
+	 * @param {Array} groups - The groups to update.
+	 * @returns {Promise} - A promise that resolves to the updated data.
+	 * @throws {Error} - If an error occurs during the update.
+	 */
 	async groups_put(user_id, groups) {
 		var url = `${this.server}/groups/${user_id}?apikey=${this.apikey}`;
 		try {
@@ -415,6 +612,14 @@ class JXPHelper {
 		}
 	}
 
+	/**
+	 * Deletes a group for a specific user.
+	 * 
+	 * @param {string} user_id - The ID of the user.
+	 * @param {string} group - The name of the group to delete.
+	 * @returns {Promise} - A promise that resolves to the response data from the server.
+	 * @throws {Error} - If an error occurs during the deletion process.
+	 */
 	async groups_del(user_id, group) {
 		var url = `${this.server}/groups/${user_id}?group=${group}&apikey=${this.apikey}`;
 		try {
@@ -425,6 +630,14 @@ class JXPHelper {
 		}
 	}
 
+	/**
+	 * Add a user to a group
+	 * 
+	 * @param {string} user_id - The ID of the user.
+	 * @param {Array} groups - The groups to be posted.
+	 * @returns {Promise} - A promise that resolves to the response data.
+	 * @throws {Error} - If an error occurs during the post request.
+	 */
 	async groups_post(user_id, groups) {
 		var url = `${this.server}/groups/${user_id}?apikey=${this.apikey}`;
 		var data = { group: groups };
@@ -437,6 +650,13 @@ class JXPHelper {
 		}
 	}
 
+	/**
+	 * Generates a JWT (JSON Web Token) for the specified email.
+	 * 
+	 * @param {string} email - The email address used for authentication.
+	 * @returns {Promise<string>} - A promise that resolves with the JWT.
+	 * @throws {Error} - If an error occurs during the retrieval of the JWT.
+	 */
 	async getjwt(email) {
 		try {
 			const jwt = (await axios.post(`${ this.server }/login/getjwt?apikey=${ this.apikey }`, { email })).data;
@@ -448,6 +668,13 @@ class JXPHelper {
 		}
 	}
 
+	/**
+	 * Retrieves the definition of a model from the server.
+	 * 
+	 * @param {string} modelname - The name of the model to retrieve.
+	 * @returns {Promise<object>} - A promise that resolves to the model definition.
+	 * @throws {Error} - If an error occurs during the retrieval process.
+	 */
 	async model(modelname) {
 		try {
 			const modeldef = (await axios.get(`${ this.server }/model/${ modelname }?apikey=${ this.apikey }`)).data;
@@ -459,6 +686,12 @@ class JXPHelper {
 		}
 	}
 
+	/**
+	 * Retrieves the model definitions from the server.
+	 * 
+	 * @returns {Promise<Object>} A promise that resolves to the model definitions.
+	 * @throws {Error} If an error occurs while retrieving the model definitions.
+	 */
 	async models() {
 		try {
 			const modeldef = (await axios.get(`${ this.server }/model?apikey=${ this.apikey }`)).data;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jxp-helper",
-  "version": "1.4.2",
+  "version": "1.4.3",
   "description": "A bunch of helpful functions for talking to a JXP API server ",
   "main": "jxp-helper.js",
   "scripts": {
@@ -17,6 +17,6 @@
   },
   "homepage": "https://github.com/WorkSpaceMan/jxp-helper#readme",
   "dependencies": {
-    "axios": "^1.4.0"
+    "axios": "^1.6.2"
   }
 }