@openeo/js-client 2.0.0 → 2.3.0

package/src/connection.js

@@ -1,5 +1,6 @@
 const Environment = require('./env');
 const Utils = require('@openeo/js-commons/src/utils');
+const ProcessRegistry = require('@openeo/js-commons/src/processRegistry');
 const axios = require('axios').default;
 const StacMigrate = require('@radiantearth/stac-migrate');
 
@@ -25,27 +26,70 @@ class Connection {
 	/**
 	 * Creates a new Connection.
 	 * 
-	 * @param {string} baseUrl - URL to the back-end
+	 * @param {string} baseUrl - The versioned URL or the back-end instance.
+	 * @param {Options} [options={}] - Additional options for the connection.
+	 * @param {?string} [url=null] - User-provided URL of the backend connected to.
 	 */
-	constructor(baseUrl) {
+	constructor(baseUrl, options = {}, url = null) {
 		/**
+		 * User-provided URL of the backend connected to.
+		 * 
+		 * `null` if not given and the connection was directly made to a versioned instance of the back-end.
+		 * 
+		 * @protected
+		 * @type {string | null}
+		 */
+		this.url = url;
+		/**
+		 * The versioned URL or the back-end instance.
+		 * 
+		 * @protected
 		 * @type {string}
 		 */
 		this.baseUrl = Utils.normalizeUrl(baseUrl);
 		/**
+		 * Auth Provider cache
+		 * 
+		 * @protected
 		 * @type {?Array.<AuthProvider>}
 		 */
 		this.authProviderList = null;
 		/**
+		 * Current auth provider
+		 * 
+		 * @protected
 		 * @type {?AuthProvider}
 		 */
 		this.authProvider = null;
 		/**
+		 * Capability cache
+		 * 
+		 * @protected
 		 * @type {?Capabilities}
 		 */
 		this.capabilitiesObject = null;
-		this.processes = null;
+		/**
+		 * Process cache
+		 * 
+		 * @protected
+		 * @type {ProcessRegistry}
+		 */
+		this.processes = new ProcessRegistry([], Boolean(options.addNamespaceToProcess));
+		this.processes.listeners.push((...args) => this.emit('processesChanged', ...args));
+		/**
+		 * Listeners for events.
+		 * 
+		 * @protected
+		 * @type {object.<string|Function>}
+		 */
 		this.listeners = {};
+		/**
+		 * Additional options for the connection.
+		 * 
+		 * @protected
+		 * @type {Options}
+		 */
+		this.options = options;
 	}
 
 	/**
@@ -61,14 +105,23 @@ class Connection {
 	}
 
 	/**
-	 * Returns the URL of the back-end currently connected to.
+	 * Returns the URL of the versioned back-end instance currently connected to.
 	 * 
-	 * @returns {string} The URL or the back-end.
+	 * @returns {string} The versioned URL or the back-end instance.
 	 */
 	getBaseUrl() {
 		return this.baseUrl;
 	}
 
+	/**
+	 * Returns the user-provided URL of the back-end currently connected to.
+	 * 
+	 * @returns {string} The URL or the back-end.
+	 */
+	getUrl() {
+		return this.url || this.baseUrl;
+	}
+
 	/**
 	 * Returns the capabilities of the back-end.
 	 * 
@@ -156,16 +209,16 @@ class Connection {
 	 * 
 	 * @async
 	 * @param {string} collectionId - Collection ID to request items for.
-	 * @param {?Array.<number>} spatialExtent - Limits the items to the given bounding box in WGS84:
+	 * @param {?Array.<number>} [spatialExtent=null] - Limits the items to the given bounding box in WGS84:
 	 * 1. Lower left corner, coordinate axis 1
 	 * 2. Lower left corner, coordinate axis 2
 	 * 3. Upper right corner, coordinate axis 1
 	 * 4. Upper right corner, coordinate axis 2
-	 * @param {?Array.<*>} temporalExtent - Limits the items to the specified temporal interval.
+	 * @param {?Array.<*>} [temporalExtent=null] - Limits the items to the specified temporal interval.
 	 * The interval has to be specified as an array with exactly two elements (start, end) and
 	 * each must be either an RFC 3339 compatible string or a Date object.
 	 * Also supports open intervals by setting one of the boundaries to `null`, but never both.
-	 * @param {?number} limit - The amount of items per request/page as integer. If `null` (default), the back-end decides.
+	 * @param {?number} [limit=null] - The amount of items per request/page as integer. If `null` (default), the back-end decides.
 	 * @yields {Promise<ItemCollection>} A response compatible to the API specification.
 	 * @throws {Error}
 	 */
@@ -208,20 +261,35 @@ class Connection {
 	}
 
 	/**
-	 * List all processes available on the back-end.
+	 * List processes available on the back-end.
 	 * 
-	 * Data is cached in memory.
+	 * Requests pre-defined processes by default.
+	 * Set the namespace parameter to request processes from a specific namespace.
+	 * 
+	 * Note: The list of namespaces can be retrieved by calling `listProcesses` without a namespace given.
+	 * The namespaces are then listed in the property `namespaces`.
 	 * 
 	 * @async
+	 * @param {?string} [namespace=null] - Namespace of the processes (default to `null`, i.e. pre-defined processes). EXPERIMENTAL!
 	 * @returns {Promise<Processes>} - A response compatible to the API specification.
 	 * @throws {Error}
 	 */
-	async listProcesses() {
-		if (this.processes === null) {
-			let response = await this._get('/processes');
-			this.processes = response.data;
+	async listProcesses(namespace = null) {
+		if (!namespace) {
+			namespace = 'backend';
+		}
+		let path = (namespace === 'backend') ? '/processes' : `/processes/${namespace}`;
+		let response = await this._get(path);
+
+		if (!Utils.isObject(response.data) || !Array.isArray(response.data.processes)) {
+			throw new Error('Invalid response received for processes');
 		}
-		return this.processes;
+
+		// Store processes in cache
+		this.processes.remove(null, namespace);
+		this.processes.addAll(response.data.processes, namespace);
+		
+		return Object.assign(response.data, {processes: this.processes.namespace(namespace)});
 	}
 
 	/**
@@ -229,20 +297,30 @@ class Connection {
 	 * 
 	 * @async
 	 * @param {string} processId - Collection ID to request further metadata for.
+	 * @param {?string} [namespace=null] - Namespace of the process (default to `null`, i.e. pre-defined processes). EXPERIMENTAL!
 	 * @returns {Promise<?Process>} - A single process as object, or `null` if none is found.
 	 * @throws {Error}
 	 * @see Connection#listProcesses
 	 */
-	async describeProcess(processId) {
-		let response = await this.listProcesses();
-		if (Array.isArray(response.processes)) {
-			return response.processes.find(process => Utils.isObject(process) && process.id === processId) || null;
+	async describeProcess(processId, namespace = null) {
+		if (!namespace) {
+			namespace = 'backend';
 		}
-		return null;
+		if (namespace === 'backend') {
+			await this.listProcesses();
+		}
+		else {
+			let response = await this._get(`/processes/${namespace}/${processId}`);
+			if (!Utils.isObject(response.data) || typeof response.data.id !== 'string') {
+				throw new Error('Invalid response received for process');
+			}
+			this.processes.add(response.data, namespace);
+		}
+		return this.processes.get(processId, namespace);
 	}
 
 	/**
-	 * Returns an object to simply build user-defined processes.
+	 * Returns an object to simply build user-defined processes based upon pre-defined processes.
 	 * 
 	 * @async
 	 * @param {string} id - A name for the process.
@@ -251,8 +329,8 @@ class Connection {
 	 * @see Connection#listProcesses
 	 */
 	async buildProcess(id) {
-		let response = await this.listProcesses();
-		return new Builder(response.processes, null, id);
+		await this.listProcesses();
+		return new Builder(this.processes, null, id);
 	}
 
 	/**
@@ -305,7 +383,7 @@ class Connection {
 	 *
 	 * @callback oidcProviderFactoryFunction
 	 * @param {object.<string, *>} providerInfo - The provider information as provided by the API, having the properties `id`, `issuer`, `title` etc.
-	 * @returns {?AuthProvider}
+	 * @returns {AuthProvider | null}
 	 */
 
 	/**
@@ -315,7 +393,7 @@ class Connection {
 	 * on the AuthProvider interface (or OIDCProvider class), e.g. to use a
 	 * OIDC library other than oidc-client-js.
 	 * 
-	 * @param {?oidcProviderFactoryFunction} providerFactoryFunc
+	 * @param {?oidcProviderFactoryFunction} [providerFactoryFunc=null]
 	 * @see AuthProvider
 	 */
 	setOidcProviderFactory(providerFactoryFunc) {
@@ -328,7 +406,7 @@ class Connection {
 	 * Returns `null` if OIDC is not supported by the client or an instance
 	 * can't be created for whatever reason.
 	 * 
-	 * @returns {?oidcProviderFactoryFunction}
+	 * @returns {oidcProviderFactoryFunction | null}
 	 * @see AuthProvider
 	 */
 	getOidcProviderFactory() {
@@ -390,6 +468,7 @@ class Connection {
 	 * Currently supported:
 	 * - authProviderChanged(provider): Raised when the auth provider has changed.
 	 * - tokenChanged(token): Raised when the access token has changed.
+	 * - processesChanged(type, data, namespace): Raised when the process registry has changed (i.e. a process was added, updated or deleted).
 	 * 
 	 * @param {string} event 
 	 * @param {Function} callback 
@@ -410,7 +489,7 @@ class Connection {
 	/**
 	 * Returns the AuthProvider.
 	 * 
-	 * @returns {?AuthProvider} 
+	 * @returns {AuthProvider | null} 
 	 */
 	getAuthProvider() {
 		return this.authProvider;
@@ -487,12 +566,12 @@ class Connection {
 		);
 	}
 
-
 	/**
 	 * A callback that is executed on upload progress updates.
 	 * 
 	 * @callback uploadStatusCallback
 	 * @param {number} percentCompleted - The percent (0-100) completed.
+	 * @param {UserFile} file - The file object corresponding to the callback.
 	 */
 
 	/**
@@ -507,15 +586,16 @@ class Connection {
 	 * @param {*} source - The source, see method description for details.
 	 * @param {?string} [targetPath=null] - The target path on the server, relative to the user workspace. Defaults to the file name of the source file.
 	 * @param {?uploadStatusCallback} [statusCallback=null] - Optionally, a callback that is executed on upload progress updates.
+	 * @param {?AbortController} [abortController=null] - An AbortController object that can be used to cancel the upload process.
 	 * @returns {Promise<UserFile>}
 	 * @throws {Error}
 	 */
-	async uploadFile(source, targetPath = null, statusCallback = null) {
+	async uploadFile(source, targetPath = null, statusCallback = null, abortController = null) {
 		if (targetPath === null) {
 			targetPath = Environment.fileNameForUpload(source);
 		}
 		let file = await this.getFile(targetPath);
-		return await file.uploadFile(source, statusCallback);
+		return await file.uploadFile(source, statusCallback, abortController);
 	}
 
 	/**
@@ -582,6 +662,15 @@ class Connection {
 	 */
 	async listUserProcesses() {
 		let response = await this._get('/process_graphs');
+
+		if (!Utils.isObject(response.data) || !Array.isArray(response.data.processes)) {
+			throw new Error('Invalid response received for processes');
+		}
+
+		// Store processes in cache
+		this.processes.remove(null, 'user');
+		this.processes.addAll(response.data.processes, 'user');
+
 		return response.data.processes.map(
 			pg => new UserProcess(this, pg.id).setAll(pg)
 		);
@@ -623,9 +712,10 @@ class Connection {
 	 * @param {Process} process - A user-defined process.
 	 * @param {?string} [plan=null] - The billing plan to use for this computation.
 	 * @param {?number} [budget=null] - The maximum budget allowed to spend for this computation.
+	 * @param {?AbortController} [abortController=null] - An AbortController object that can be used to cancel the processing request.
 	 * @returns {Promise<SyncResult>} - An object with the data and some metadata.
 	 */
-	async computeResult(process, plan = null, budget = null) {
+	async computeResult(process, plan = null, budget = null, abortController = null) {
 		let requestBody = this._normalizeUserProcess(
 			process,
 			{
@@ -633,7 +723,7 @@ class Connection {
 				budget: budget
 			}
 		);
-		let response = await this._post('/result', requestBody, Environment.getResponseType());
+		let response = await this._post('/result', requestBody, Environment.getResponseType(), abortController);
 		let syncResult = {
 			data: response.data,
 			costs: null,
@@ -684,10 +774,11 @@ class Connection {
 	 * @param {string} targetPath - The target, see method description for details.
 	 * @param {?string} [plan=null] - The billing plan to use for this computation.
 	 * @param {?number} [budget=null] - The maximum budget allowed to spend for this computation.
+	 * @param {?AbortController} [abortController=null] - An AbortController object that can be used to cancel the processing request.
 	 * @throws {Error}
 	 */
-	async downloadResult(process, targetPath, plan = null, budget = null) {
-		let response = await this.computeResult(process, plan, budget);
+	async downloadResult(process, targetPath, plan = null, budget = null, abortController = null) {
+		let response = await this.computeResult(process, plan, budget, abortController);
 		// @ts-ignore
 		await Environment.saveToFile(response.data, targetPath);
 	}
@@ -824,7 +915,7 @@ class Connection {
 	 * 
 	 * @param {Array.<Link>} links - An array of links.
 	 * @param {string} rel - Relation type to find, defaults to `next`.
-	 * @returns {?string}
+	 * @returns {string | null}
 	 * @throws {Error}
 	 */
 	_getLinkHref(links, rel = 'next') {
@@ -855,7 +946,7 @@ class Connection {
 			url: path,
 			// Timeout for capabilities requests as they are used for a quick first discovery to check whether the server is a openEO back-end.
 			// Without timeout connecting with a wrong server url may take forever.
-			timeout: path === '/' ? 3000 : 0,
+			timeout: path === '/' ? 5000 : 0,
 			params: query
 		});
 	}
@@ -867,17 +958,19 @@ class Connection {
 	 * @param {string} path 
 	 * @param {*} body 
 	 * @param {string} responseType - Response type according to axios, defaults to `json`.
+	 * @param {?AbortController} [abortController=null] - An AbortController object that can be used to cancel the request.
 	 * @returns {Promise<AxiosResponse>}
 	 * @throws {Error}
 	 * @see https://github.com/axios/axios#request-config
 	 */
-	async _post(path, body, responseType) {
-		return await this._send({
+	async _post(path, body, responseType, abortController = null) {
+		let options = {
 			method: 'post',
 			responseType: responseType,
 			url: path,
 			data: body
-		});
+		};
+		return await this._send(options, abortController);
 	}
 
 	/**
@@ -963,11 +1056,12 @@ class Connection {
 	 * 
 	 * @async
 	 * @param {object.<string, *>} options 
+	 * @param {?AbortController} [abortController=null] - An AbortController object that can be used to cancel the request.
 	 * @returns {Promise<AxiosResponse>}
 	 * @throws {Error}
 	 * @see https://github.com/axios/axios
 	 */
-	async _send(options) {
+	async _send(options, abortController = null) {
 		options.baseURL = this.baseUrl;
 		if (this.isAuthenticated() && (typeof options.authorization === 'undefined' || options.authorization === true)) {
 			if (!options.headers) {
@@ -978,6 +1072,9 @@ class Connection {
 		if (!options.responseType) {
 			options.responseType = 'json';
 		}
+		if (abortController) {
+			options.signal = abortController.signal;
+		}
 
 		try {
 			return await axios(options);

package/src/filetypes.js

@@ -64,7 +64,7 @@ class FileTypes {
 	 * Returns null if no input file format was found for the given identifier.
 	 * 
 	 * @param {string} type - Case-insensitive file format identifier
-	 * @returns {?FileType}
+	 * @returns {FileType | null}
 	 */
 	getInputType(type) {
 		return this._findType(type, 'input');
@@ -76,7 +76,7 @@ class FileTypes {
 	 * Returns null if no output file format was found for the given identifier.
 	 * 
 	 * @param {string} type - Case-insensitive file format identifier
-	 * @returns {?FileType}
+	 * @returns {FileType | null}
 	 */
 	getOutputType(type) {
 		return this._findType(type, 'output');
@@ -87,7 +87,7 @@ class FileTypes {
 	 * 
 	 * @param {string} type - Identifier of the file type
 	 * @param {string} io - Either `input` or `output`
-	 * @returns {?FileType}
+	 * @returns {FileType | null}
 	 * @protected
 	 */
 	_findType(type, io) {

package/src/job.js

@@ -265,6 +265,9 @@ class Job extends BaseEntity {
 	 */
 	async getResultsAsStac() {
 		let response = await this.connection._get('/jobs/' + this.id + '/results');
+		if (!Utils.isObject(response) || !Utils.isObject(response.data)) {
+			throw new Error("Results received from the back-end are invalid");
+		}
 		let data = StacMigrate.stac(response.data);
 		if (!Utils.isObject(data.assets)) {
 			data.assets = {};

package/src/oidcprovider.js

@@ -271,7 +271,7 @@ class OidcProvider extends AuthProvider {
 	 * 
 	 * This may override a detected default client ID.
 	 * 
-	 * @param {?string} clientId
+	 * @param {string | null} clientId
 	 */
 	setClientId(clientId) {
 		this.clientId = clientId;
@@ -281,7 +281,7 @@ class OidcProvider extends AuthProvider {
 	 * Sets the OIDC User.
 	 * 
 	 * @see https://github.com/IdentityModel/oidc-client-js/wiki#user
-	 * @param {?Oidc.User} user - The OIDC User. Passing `null` resets OIDC authentication details.
+	 * @param {Oidc.User | null} user - The OIDC User. Passing `null` resets OIDC authentication details.
 	 */
 	setUser(user) {
 		if (!user) {
@@ -299,7 +299,7 @@ class OidcProvider extends AuthProvider {
 	 * 
 	 * Sets the grant and client ID accordingly.
 	 * 
-	 * @returns {?OidcClient}
+	 * @returns {OidcClient | null}
 	 * @see OidcProvider#setGrant
 	 * @see OidcProvider#setClientId
 	 */

package/src/openeo.js

@@ -1,4 +1,5 @@
 const axios = require('axios').default;
+const { AbortController } = require("node-abort-controller");
 const Utils = require('@openeo/js-commons/src/utils');
 const Versions = require('@openeo/js-commons/src/versions');
 
@@ -43,15 +44,17 @@ class OpenEO {
 	 * 
 	 * @async
 	 * @param {string} url - The server URL to connect to.
+	 * @param {Options} [options={}] - Additional options for the connection.
 	 * @returns {Promise<Connection>}
 	 * @throws {Error}
 	 * @static
 	 */
-	static async connect(url) {
+	static async connect(url, options = {}) {
 		let wellKnownUrl = Utils.normalizeUrl(url, '/.well-known/openeo');
+		let versionedUrl = url;
 		let response = null;
 		try {
-			response = await axios.get(wellKnownUrl);
+			response = await axios.get(wellKnownUrl, {timeout: 5000});
 
 			if (!Utils.isObject(response.data) || !Array.isArray(response.data.versions)) {
 				throw new Error("Well-Known Document doesn't list any versions.");
@@ -63,14 +66,16 @@ class OpenEO {
 		if (Utils.isObject(response)) {
 			let version = Versions.findLatest(response.data.versions, true, MIN_API_VERSION, MAX_API_VERSION);
 			if (version !== null) {
-				url = version.url;
+				versionedUrl = version.url;
 			}
 			else {
 				throw new Error("Server not supported. Client only supports the API versions between " + MIN_API_VERSION + " and " + MAX_API_VERSION);
 			}
 		}
 
-		return await OpenEO.connectDirect(url);
+		let connection = await OpenEO.connectDirect(versionedUrl, options);
+		connection.url = url;
+		return connection;
 	}
 
 	/**
@@ -80,12 +85,13 @@ class OpenEO {
 	 * 
 	 * @async
 	 * @param {string} versionedUrl - The server URL to connect to.
+	 * @param {Options} [options={}] - Additional options for the connection.
 	 * @returns {Promise<Connection>}
 	 * @throws {Error}
 	 * @static
 	 */
-	static async connectDirect(versionedUrl) {
-		let connection = new Connection(versionedUrl);
+	static async connectDirect(versionedUrl, options = {}) {
+		let connection = new Connection(versionedUrl, options);
 
 		// Check whether back-end is accessible and supports a compatible version.
 		let capabilities = await connection.init();
@@ -104,7 +110,7 @@ class OpenEO {
 	 * @returns {string} Version number (according to SemVer).
 	 */
 	static clientVersion() {
-		return "2.0.0";
+		return "2.3.0";
 	}
 
 }
@@ -112,6 +118,7 @@ class OpenEO {
 OpenEO.Environment = require('./env');
 
 module.exports = {
+	AbortController,
 	AuthProvider,
 	BasicProvider,
 	Capabilities,

package/src/typedefs.js

@@ -170,11 +170,20 @@
  * @property {Array.<Link>} links Links
  */
 
+/**
+ * Connection options.
+ * 
+ * @typedef Options
+ * @type {object}
+ * @property {boolean} addNamespaceToProcess Add a namespace property to processes if set to `true`. Defaults to `false`.
+ */
+
 /**
  * @typedef Processes
  * @type {object}
  * @property {Array.<Process>} processes
  * @property {Array.<Link>} links
+ * @property {?Array.<string>} namespaces EXPERIMENTAL!
  */
 
 /**
@@ -214,8 +223,9 @@
  * @typedef UserAccount
  * @type {object}
  * @property {string} user_id
- * @property {string} name
- * @property {UserAccountStorage} storage
+ * @property {?string} name
+ * @property {?string} default_plan
+ * @property {?UserAccountStorage} storage
  * @property {?number} budget
- * @property {Array.<Link>} links
+ * @property {?Array.<Link>} links
  */

package/src/userfile.js

@@ -90,10 +90,11 @@ class UserFile extends BaseEntity {
 	 * @async
 	 * @param {*} source - The source, see method description for details.
 	 * @param {?uploadStatusCallback} statusCallback - Optionally, a callback that is executed on upload progress updates.
+	 * @param {?AbortController} [abortController=null] - An AbortController object that can be used to cancel the upload process.
 	 * @returns {Promise<UserFile>}
 	 * @throws {Error}
 	 */
-	async uploadFile(source, statusCallback = null) {
+	async uploadFile(source, statusCallback = null, abortController = null) {
 		let options = {
 			method: 'put',
 			url: '/files/' + this.path,
@@ -109,7 +110,7 @@ class UserFile extends BaseEntity {
 			};
 		}
 
-		let response = await this.connection._send(options);
+		let response = await this.connection._send(options, abortController);
 		return this.setAll(response.data);
 	}
 

package/src/userprocess.js

@@ -1,4 +1,5 @@
 const BaseEntity = require('./baseentity');
+const Utils = require('@openeo/js-commons/src/utils');
 
 /**
  * A Stored Process Graph.
@@ -120,6 +121,10 @@ class UserProcess extends BaseEntity {
 	 */
 	async describeUserProcess() {
 		let response = await this.connection._get('/process_graphs/' + this.id);
+		if (!Utils.isObject(response.data) || typeof response.data.id !== 'string') {
+			throw new Error('Invalid response received for user process');
+		}
+		this.connection.processes.add(response.data, 'user');
 		return this.setAll(response.data);
 	}
 
@@ -140,7 +145,9 @@ class UserProcess extends BaseEntity {
 			return this.describeUserProcess();
 		}
 		else {
-			return this.setAll(parameters);
+			let obj = this.setAll(parameters);
+			this.connection.processes.add(obj.toJSON(), 'user');
+			return obj;
 		}
 	}
 
@@ -152,6 +159,7 @@ class UserProcess extends BaseEntity {
 	 */
 	async deleteUserProcess() {
 		await this.connection._delete('/process_graphs/' + this.id);
+		this.connection.processes.remove(this.id, 'user');
 	}
 }