@openeo/js-client 2.0.0 → 2.3.0

package/src/builder/builder.js

@@ -3,6 +3,7 @@ const Parameter = require('./parameter');
 const axios = require('axios').default;
 const Utils = require('@openeo/js-commons/src/utils');
 const ProcessUtils = require("@openeo/js-commons/src/processUtils");
+const ProcessRegistry = require('@openeo/js-commons/src/processRegistry');
 
 const PROCESS_META = [
 	"id", "summary", "description", "categories", "parameters", "returns",
@@ -83,7 +84,7 @@ class Builder {
 	 * 
 	 * @async
 	 * @static
-	 * @param {?string} version 
+	 * @param {?string} [version=null]
 	 * @returns {Promise<Builder>}
 	 * @throws {Error}
 	 */
@@ -103,7 +104,7 @@ class Builder {
 	 * 
 	 * @async
 	 * @static
-	 * @param {?string} url 
+	 * @param {string | null} url 
 	 * @returns {Promise<Builder>}
 	 * @throws {Error}
 	 */
@@ -117,16 +118,17 @@ class Builder {
 	 * 
 	 * Each process passed to the constructor is made available as object method.
 	 * 
-	 * @param {Array.<Process>|Processes} processes - Either an array containing processes or an object compatible with `GET /processes` of the API.
+	 * @param {Array.<Process>|Processes|ProcessRegistry} processes - Either an array containing processes or an object compatible with `GET /processes` of the API.
 	 * @param {?Builder} parent - The parent builder, usually only used by the Builder itself.
 	 * @param {string} id - A unique identifier for the process.
 	 */
 	constructor(processes, parent = null, id = undefined) {
 		/**
-		 * List of all process specifications.
-		 * @type {Array.<Process>}
+		 * A unique identifier for the process.
+		 * @public
+		 * @type {string}
 		 */
-		this.processes = [];
+		this.id = id;
 		/**
 		 * The parent builder.
 		 * @type {?Builder}
@@ -149,57 +151,75 @@ class Builder {
 		this.parameters = undefined;
 
 		/**
-		 * A unique identifier for the process.
-		 * @public
-		 * @type {string}
+		 * List of all non-namespaced process specifications.
+		 * @type {ProcessRegistry}
 		 */
-		this.id = id;
+		this.processes = null;
 
-		if (Utils.isObject(processes) && Array.isArray(processes.processes)) {
-			processes = processes.processes;
+		// Create process registry if not available yet
+		if (processes instanceof ProcessRegistry) {
+			this.processes = processes;
 		}
-		if (Array.isArray(processes)) {
-			for(let process of processes) {
-				try {
-					this.addProcessSpec(process);
-				} catch (error) {
-					console.warn(error);
-				}
-			}
+		else if (Utils.isObject(processes) && Array.isArray(processes.processes)) {
+			this.processes = new ProcessRegistry(processes.processes);
+		}
+		else if (Array.isArray(processes)) {
+			this.processes = new ProcessRegistry(processes);
 		}
 		else {
 			throw new Error("Processes are invalid; must be array or object according to the API.");
 		}
+
+		// Create processes
+		this.processes.all().forEach(process => this.createFunction(process));
+	}
+
+	/**
+	 * Creates a callable function on the builder object for a process.
+	 * 
+	 * @param {Process} process
+	 * @throws {Error}
+	 */
+	createFunction(process) {
+		if (typeof this[process.id] !== 'undefined') {
+			throw new Error("Can't create function for process '" + process.id + "'. Already exists in Builder class.");
+		}
+
+		/**
+		 * Implicitly calls the process with the given name on the back-end by adding it to the process.
+		 * 
+		 * This is a shortcut for {@link Builder#process}.
+		 * 
+		 * @param {...*} args - The arguments for the process.
+		 * @returns {BuilderNode}
+		 * @see Builder#process
+		 */
+		this[process.id] = function(...args) {
+			// Don't use arrow functions, they don't support the arguments keyword.
+			return this.process(process.id, args);
+		};
 	}
 
 	/**
 	 * Adds a process specification to the builder so that it can be used to create a process graph.
 	 * 
 	 * @param {Process} process - Process specification compliant to openEO API
+	 * @param {?string} [namespace=null] - Namespace of the process (default to `null`, i.e. pre-defined processes). EXPERIMENTAL!
 	 * @throws {Error}
 	 */
-	addProcessSpec(process) {
+	addProcessSpec(process, namespace = null) {
 		if (!Utils.isObject(process)) {
 			throw new Error("Process '" + process.id + "' must be an object.");
 		}
-		if (typeof this[process.id] === 'undefined') {
-			this.processes.push(process);
-			/**
-			 * Implicitly calls the process with the given name on the back-end by adding it to the process.
-			 * 
-			 * This is a shortcut for {@link Builder#process}.
-			 * 
-			 * @param {...*} args - The arguments for the process.
-			 * @returns {BuilderNode}
-			 * @see Builder#process
-			 */
-			this[process.id] = function(...args) {
-				// Don't use arrow functions, they don't support the arguments keyword.
-				return this.process(process.id, args);
-			};
+
+		if (!namespace) {
+			namespace = 'backend';
 		}
-		else {
-			throw new Error("Can't create function for process '" + process.id + "'. Already exists in Builder class.");
+		this.processes.add(process, namespace);
+
+		// Create callable function for pre-defined processes
+		if (namespace === 'backend') {
+			this.createFunction(process);
 		}
 	}
 
@@ -281,13 +301,14 @@ class Builder {
 	}
 
 	/**
-	 * Returns the process specification for the given process identifier.
+	 * Returns the process specification for the given process identifier and namespace (or `null`).
 	 * 
-	 * @param {string} id 
-	 * @returns {Process}
+	 * @param {string} id - Process identifier
+	 * @param {?string} [namespace=null] - Namespace of the process (default to `null`, i.e. user or backend namespace). EXPERIMENTAL!
+	 * @returns {Process | null}
 	 */
-	spec(id) {
-		return this.processes.find(process => process.id === id);
+	spec(id, namespace = null) {
+		return this.processes.get(id, namespace);
 	}
 
 	/**
@@ -308,25 +329,32 @@ class Builder {
 	}
 
 	/**
-	 * Checks whether a process with the given id is supported by the back-end.
+	 * Checks whether a process with the given id and namespace is supported by the back-end.
 	 * 
-	 * @param {string} processId - The id of the process to call.
+	 * @param {string} processId - The id of the process.
+	 * @param {?string} [namespace=null] - Namespace of the process (default to `null`, i.e. pre-defined processes). EXPERIMENTAL!
 	 * @returns {boolean}
 	 */
-	supports(processId) {
-		return Utils.isObject(this.spec(processId));
+	supports(processId, namespace = null) {
+		return Boolean(this.spec(processId, namespace));
 	}
 
 	/**
 	 * Adds another process call to the process chain.
 	 * 
-	 * @param {string} processId - The id of the process to call.
-	 * @param {object.<string, *>|Array} args - The arguments as key-value pairs or as array. For objects, they keys must be the parameter names and the values must be the arguments. For arrays, arguments must be specified in the same order as in the corresponding process.
-	 * @param {?string} description - An optional description for the process call.
+	 * @param {string} processId - The id of the process to call. To access a namespaced process, use the `process@namespace` notation.
+	 * @param {object.<string, *>|Array} [args={}] - The arguments as key-value pairs or as array. For objects, they keys must be the parameter names and the values must be the arguments. For arrays, arguments must be specified in the same order as in the corresponding process.
+	 * @param {?string} [description=null] - An optional description for the process call.
 	 * @returns {BuilderNode}
 	 */
 	process(processId, args = {}, description = null) {
-		let node = new BuilderNode(this, processId, args, description);
+		let namespace = null;
+		if (processId.includes('@')) {
+			let rest;
+			[processId, ...rest] = processId.split('@');
+			namespace = rest.join('@');
+		}
+		let node = new BuilderNode(this, processId, args, description, namespace);
 		this.nodes[node.id] = node;
 		return node;
 	}

package/src/builder/formula.js

@@ -8,13 +8,15 @@ const BuilderNode = require('./node');
  * Operators: - (subtract), + (add), / (divide), * (multiply), ^ (power)
  * 
  * It supports all mathematical functions (i.e. expects a number and returns a number) the back-end implements, e.g. `sqrt(x)`.
+ * For namespaced processes, use for example `process@namespace(x)` - EXPERIMENTAL!
  * 
  * Only available if a builder is specified in the constructor:
  * You can refer to output from processes with a leading `#`, e.g. `#loadco1` if the node to refer to has the key `loadco1`.
  * 
  * Only available if a parent node is set via `setNode()`:
  * Parameters can be accessed simply by name. 
- * If the first parameter is a (labeled) array, the value for a specific index or label can be accessed by typing the numeric index or textual label with a $ in front, for example $B1 for the label B1 or $0 for the first element in the array. Numeric labels are not supported.
+ * If the first parameter is a (labeled) array, the value for a specific index or label can be accessed by typing the numeric index or textual label with a `$` in front, for example `$B1` for the label `B1` or `$0` for the first element in the array. Numeric labels are not supported.
+ * You can access subsequent parameters by adding additional `$` at the beginning, e.g. `$$0` to access the first element of an array in the second parameter, `$$$0` for the same in the third parameter etc.
  * 
  * An example that computes an EVI (assuming the labels for the bands are `NIR`, `RED` and `BLUE`): `2.5 * ($NIR - $RED) / (1 + $NIR + 6 * $RED + (-7.5 * $BLUE))`
  */
@@ -145,18 +147,20 @@ class Formula {
 
 		let callbackParams = this.builder.getParentCallbackParameters();
 		// Array labels / indices
-		if (typeof value === 'string' && value.startsWith('$') && callbackParams.length > 0) {
-			let ref = value.substring(1);
-			// Array access always refers to the first parameter passed
-			return callbackParams[0][ref];
+		if (typeof value === 'string' && callbackParams.length > 0) {
+			let prefix = value.match(/^\$+/);
+			let count = prefix ? prefix[0].length : 0;
+			if (count > 0 && callbackParams.length >= count) {
+				let ref = value.substring(count);
+				return callbackParams[count-1][ref];
+			}
 		}
+
 		// Everything else is a parameter
-		else {
-			let parameter = new Parameter(value);
-			// Add new parameter if it doesn't exist
-			this.builder.addParameter(parameter);
-			return parameter;
-		}
+		let parameter = new Parameter(value);
+		// Add new parameter if it doesn't exist
+		this.builder.addParameter(parameter);
+		return parameter;
 	}
 
 	/**

package/src/builder/node.js

@@ -13,8 +13,9 @@ class BuilderNode {
 	 * @param {string} processId 
 	 * @param {object.<string, *>} [processArgs={}]
 	 * @param {?string} [processDescription=null]
+	 * @param {?string} [processNamespace=null]
 	 */
-	constructor(parent, processId, processArgs = {}, processDescription = null) {
+	constructor(parent, processId, processArgs = {}, processDescription = null, processNamespace = null) {
 		/**
 		 * The parent builder.
 		 * @type {Builder}
@@ -26,8 +27,8 @@ class BuilderNode {
 		 * @type {Process}
 		 * @readonly
 		 */
-		this.spec = this.parent.spec(processId);
-		if (!Utils.isObject(this.spec)) {
+		this.spec = this.parent.spec(processId, processNamespace);
+		if (!this.spec) {
 			throw new Error("Process doesn't exist: " + processId);
 		}
 
@@ -36,6 +37,11 @@ class BuilderNode {
 		 * @type {string}
 		 */
 		this.id = parent.generateId(processId);
+		/**
+		 * The namespace of the process - EXPERIMENTAL!
+		 * @type {string}
+		 */
+		this.namespace = processNamespace;
 		/**
 		 * The arguments for the process.
 		 * @type {object.<string, *>}
@@ -176,7 +182,7 @@ class BuilderNode {
 	 * 
 	 * @protected
 	 * @param {?BuilderNode} [parentNode=null]
-	 * @param {?string} parentParameter
+	 * @param {?string} [parentParameter=null]
 	 * @returns {BuilderNode}
 	 */
 	createBuilder(parentNode = null, parentParameter = null) {
@@ -228,6 +234,9 @@ class BuilderNode {
 			process_id: this.spec.id,
 			arguments: {}
 		};
+		if (this.namespace) {
+			obj.namespace = this.namespace;
+		}
 		for(let name in this.arguments) {
 			if (typeof this.arguments[name] !== 'undefined') {
 				obj.arguments[name] = this.exportArgument(this.arguments[name], name);

package/src/builder/parameter.js

@@ -88,15 +88,14 @@ class Parameter {
 				 */
 				set(target, name, value, receiver) {
 					if (!Reflect.has(target, name)) {
-						console.warn('Simplified array access is read-only');
+						throw new Error('Simplified array access is read-only');
 					}
 					return Reflect.set(target, name, value, receiver);
 				}
 			});
 		}
 		else {
-			console.warn('Simplified array access not supported, use array_element directly');
-			return parameter;
+			throw new Error('Simplified array access not supported, use array_element directly');
 		}
 	}
 	

package/src/builder/tapdigit.js

@@ -119,23 +119,34 @@ TapDigit.Lexer = function () {
         return (ch === '_') || (ch === '#') || (ch === '$') || isLetter(ch);
     }
 
-    function isIdentifierPart(ch) {
-        return (ch === '_') || isLetter(ch) || isDecimalDigit(ch);
+    function isAdditionalNamespaceChar(ch) {
+        return (ch === '-') || (ch === '.') || (ch === '~') || (ch === '@');
     }
 
-    function scanIdentifier() {
-        let ch
-        let id;
+    function isIdentifierPart(ch, ns = false) {
+        return (ch === '_') || isLetter(ch) || isDecimalDigit(ch) || (ns && isAdditionalNamespaceChar(ch));
+    }
 
-        ch = peekNextChar();
-        if (!isIdentifierStart(ch)) {
+    function scanIdentifier() {
+        let startCh = peekNextChar();
+        if (!isIdentifierStart(startCh)) {
             return undefined;
         }
 
-        id = getNextChar();
+        let id = getNextChar();
+        let ns = false;
         while (true) {
-            ch = peekNextChar();
-            if (!isIdentifierPart(ch)) {
+            let ch = peekNextChar();
+            // If the first character is a $, it is allowed that more $ follow directly after
+            if (startCh === '$') {
+                if (ch !== '$') {
+                    startCh = ''; // Stop allowing $ once the first non-$ has been found
+                } // else: allowed
+            }
+            else if (ch === '@') {
+                ns = true;
+            }
+            else if (!isIdentifierPart(ch, ns)) {
                 break;
             }
             id += getNextChar();

package/src/capabilities.js

@@ -190,7 +190,7 @@ class Capabilities {
 	/**
 	 * Get the billing currency.
 	 * 
-	 * @returns {?string} The billing currency or `null` if not available.
+	 * @returns {string | null} The billing currency or `null` if not available.
 	 */
 	currency() {
 		return (Utils.isObject(this.data.billing) && typeof this.data.billing.currency === 'string' ? this.data.billing.currency : null);