@openeo/js-client 2.5.1 → 2.7.0

package/src/openeo.js

@@ -1,138 +1,137 @@
-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');
-
-// API wrapper
-const Connection = require('./connection');
-const Job = require('./job');
-const Logs = require('./logs');
-const UserFile = require('./userfile');
-const UserProcess = require('./userprocess');
-const Service = require('./service');
-
-// Auth Providers
-const AuthProvider = require('./authprovider');
-const BasicProvider = require('./basicprovider');
-const OidcProvider = require('./oidcprovider');
-
-// Response wrapper
-const Capabilities = require('./capabilities');
-const FileTypes = require('./filetypes');
-
-// Builder
-const Builder = require('./builder/builder');
-const BuilderNode = require('./builder/node');
-const Parameter = require('./builder/parameter');
-const Formula = require('./builder/formula');
-
-const MIN_API_VERSION = '1.0.0-rc.2';
-const MAX_API_VERSION = '1.x.x';
-
-/**
- * Main class to start with openEO. Allows to connect to a server.
- * 
- * @hideconstructor
- */
-class OpenEO {
-
-	/**
-	 * Connect to a back-end with version discovery (recommended).
-	 * 
-	 * Includes version discovery (request to `GET /well-known/openeo`) and connects to the most suitable version compatible to this JS client version.
-	 * Requests the capabilities and authenticates where required.
-	 * 
-	 * @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, options = {}) {
-		let wellKnownUrl = Utils.normalizeUrl(url, '/.well-known/openeo');
-		let versionedUrl = url;
-		let response = null;
-		try {
-			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.");
-			}
-		} catch(error) {
-			console.warn("Can't read well-known document, connecting directly to the specified URL as fallback mechanism. Reason: " + error.message);
-		}
-	
-		if (Utils.isObject(response)) {
-			let version = Versions.findLatest(response.data.versions, true, MIN_API_VERSION, MAX_API_VERSION);
-			if (version !== null) {
-				versionedUrl = version.url;
-			}
-			else {
-				throw new Error("Server not supported. Client only supports the API versions between " + MIN_API_VERSION + " and " + MAX_API_VERSION);
-			}
-		}
-
-		let connection = await OpenEO.connectDirect(versionedUrl, options);
-		connection.url = url;
-		return connection;
-	}
-
-	/**
-	 * Connects directly to a back-end instance, without version discovery (NOT recommended).
-	 * 
-	 * Doesn't do version discovery, therefore a URL of a versioned API must be specified. Requests the capabilities and authenticates where required.
-	 * 
-	 * @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, options = {}) {
-		let connection = new Connection(versionedUrl, options);
-
-		// Check whether back-end is accessible and supports a compatible version.
-		let capabilities = await connection.init();
-		if (Versions.compare(capabilities.apiVersion(), MIN_API_VERSION, "<") || Versions.compare(capabilities.apiVersion(), MAX_API_VERSION, ">")) {
-			throw new Error("Client only supports the API versions between " + MIN_API_VERSION + " and " + MAX_API_VERSION);
-		}
-
-		return connection;
-	}
-
-	/**
-	 * Returns the version number of the client.
-	 * 
-	 * Not to confuse with the API version(s) supported by the client.
-	 * 
-	 * @returns {string} Version number (according to SemVer).
-	 */
-	static clientVersion() {
-		return "2.5.1";
-	}
-
-}
-
-OpenEO.Environment = require('./env');
-
-module.exports = {
-	AbortController,
-	AuthProvider,
-	BasicProvider,
-	Capabilities,
-	Connection,
-	FileTypes,
-	Job,
-	Logs,
-	OidcProvider,
-	OpenEO,
-	Service,
-	UserFile,
-	UserProcess,
-	Builder,
-	BuilderNode,
-	Parameter,
-	Formula
-};
+const axios = require('axios');
+const Utils = require('@openeo/js-commons/src/utils');
+const Versions = require('@openeo/js-commons/src/versions');
+
+// API wrapper
+const Connection = require('./connection');
+const Job = require('./job');
+const Logs = require('./logs');
+const UserFile = require('./userfile');
+const UserProcess = require('./userprocess');
+const Service = require('./service');
+
+// Auth Providers
+const AuthProvider = require('./authprovider');
+const BasicProvider = require('./basicprovider');
+const OidcProvider = require('./oidcprovider');
+
+// Response wrapper
+const Capabilities = require('./capabilities');
+const FileTypes = require('./filetypes');
+
+// Builder
+const Builder = require('./builder/builder');
+const BuilderNode = require('./builder/node');
+const Parameter = require('./builder/parameter');
+const Formula = require('./builder/formula');
+
+const MIN_API_VERSION = '1.0.0-rc.2';
+const MAX_API_VERSION = '1.x.x';
+
+/**
+ * Main class to start with openEO. Allows to connect to a server.
+ * 
+ * @hideconstructor
+ */
+class OpenEO {
+
+	/**
+	 * Connect to a back-end with version discovery (recommended).
+	 * 
+	 * Includes version discovery (request to `GET /well-known/openeo`) and connects to the most suitable version compatible to this JS client version.
+	 * Requests the capabilities and authenticates where required.
+	 * 
+	 * @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, options = {}) {
+		let wellKnownUrl = Utils.normalizeUrl(url, '/.well-known/openeo');
+		let versionedUrl = url;
+		let response = null;
+		try {
+			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.");
+			}
+		} catch(error) {
+			console.warn("Can't read well-known document, connecting directly to the specified URL as fallback mechanism. Reason: " + error.message);
+		}
+	
+		if (Utils.isObject(response)) {
+			let version = Versions.findLatest(response.data.versions, true, MIN_API_VERSION, MAX_API_VERSION);
+			if (version !== null) {
+				versionedUrl = version.url;
+			}
+			else {
+				throw new Error("Server not supported. Client only supports the API versions between " + MIN_API_VERSION + " and " + MAX_API_VERSION);
+			}
+		}
+
+		let connection = await OpenEO.connectDirect(versionedUrl, options);
+		connection.url = url;
+		return connection;
+	}
+
+	/**
+	 * Connects directly to a back-end instance, without version discovery (NOT recommended).
+	 * 
+	 * Doesn't do version discovery, therefore a URL of a versioned API must be specified. Requests the capabilities and authenticates where required.
+	 * 
+	 * @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, options = {}) {
+		let connection = new Connection(versionedUrl, options);
+
+		// Check whether back-end is accessible and supports a compatible version.
+		let capabilities = await connection.init();
+		if (Versions.compare(capabilities.apiVersion(), MIN_API_VERSION, "<") || Versions.compare(capabilities.apiVersion(), MAX_API_VERSION, ">")) {
+			throw new Error("Client only supports the API versions between " + MIN_API_VERSION + " and " + MAX_API_VERSION);
+		}
+
+		return connection;
+	}
+
+	/**
+	 * Returns the version number of the client.
+	 * 
+	 * Not to confuse with the API version(s) supported by the client.
+	 * 
+	 * @returns {string} Version number (according to SemVer).
+	 */
+	static clientVersion() {
+		return "2.7.0";
+	}
+
+}
+
+OpenEO.Environment = require('./env');
+
+module.exports = {
+	AbortController,
+	AuthProvider,
+	BasicProvider,
+	Capabilities,
+	Connection,
+	FileTypes,
+	Job,
+	Logs,
+	OidcProvider,
+	OpenEO,
+	Service,
+	UserFile,
+	UserProcess,
+	Builder,
+	BuilderNode,
+	Parameter,
+	Formula
+};

package/src/pages.js

@@ -0,0 +1,349 @@
+/* eslint-disable max-classes-per-file */
+
+const Job = require('./job.js');
+const Service = require('./service.js');
+const UserFile = require('./userfile.js');
+const UserProcess = require('./userprocess.js');
+const Utils = require('@openeo/js-commons/src/utils');
+const StacMigrate = require('@radiantearth/stac-migrate');
+
+const FED_MISSING = 'federation:missing';
+
+/**
+ * A class to handle pagination of resources.
+ * 
+ * @abstract
+ */
+class Pages {
+  /**
+   * Creates an instance of Pages.
+   *
+   * @param {Connection} connection
+   * @param {string} endpoint
+   * @param {string} key
+   * @param {Constructor} cls
+   * @param {object} [params={}]
+   * @param {string} primaryKey
+   */
+  constructor(connection, endpoint, key, cls, params = {}, primaryKey = "id") {
+    this.connection = connection;
+		this.nextUrl = endpoint;
+    this.key = key;
+    this.primaryKey = primaryKey;
+    this.cls = cls;
+    if (!(params.limit > 0)) {
+      delete params.limit;
+    }
+    this.params = params;
+  }
+
+  /**
+   * Returns true if there are more pages to fetch.
+   *
+   * @returns {boolean}
+   */
+  hasNextPage() {
+    return this.nextUrl !== null;
+  }
+
+  /**
+   * Returns the next page of resources.
+   * 
+   * @async
+   * @param {Array.<object>} oldObjects - Existing objects to update, if any.
+   * @param {boolean} [toArray=true] - Whether to return the objects as a simplified array or as an object with all information.
+   * @returns {Array.<object>}
+   * @throws {Error}
+   */
+  async nextPage(oldObjects = [], toArray = true) {
+    // Request data from server
+    const response = await this.connection._get(this.nextUrl, this.params);
+
+    let data = response.data;
+    // Check response
+    if (!Utils.isObject(data)) {
+      throw new Error(`Response is invalid, is not an object`);
+    }
+    if (!Array.isArray(data[this.key])) {
+      throw new Error(`Response is invalid, '${this.key}' property is not an array`);
+    }
+
+    // Update existing objects if needed
+    let newObjects = data[this.key].map(updated => {
+      let resource = oldObjects.find(old => old[this.primaryKey] === updated[this.primaryKey]);
+      if (resource) {
+        resource.setAll(updated);
+      }
+      else {
+        resource = this._createObject(updated);
+      }
+      return resource;
+    });
+
+    // Store objects in cache if needed
+    newObjects = this._cache(newObjects);
+
+    // Add self link if missing
+    data.links = this._ensureArray(data.links);
+    const selfLink = this.connection._getLinkHref(data.links, 'self');
+    if (!selfLink) {
+      data.links.push({rel: 'self', href: this.nextUrl});
+    }
+
+    // Check whether a next page is available
+    this.nextUrl = this._getNextLink(response);
+    // Don't append initial params to the next URL
+    this.params = null;
+
+    // Either return as ResponseArray or full API response body
+    if (toArray) {
+      newObjects.links = data.links;
+      newObjects[FED_MISSING] = this._ensureArray(data[FED_MISSING]);
+      return newObjects;
+    }
+    else {
+      data[this.key] = newObjects;
+      return data;
+    }
+  }
+
+  /**
+   * Ensures a variable is an array.
+   * 
+   * @protected
+   * @param {*} x 
+   * @returns {Array}
+   */
+  _ensureArray(x) {
+    return Array.isArray(x) ? x : [];
+  }
+
+  /**
+   * Creates a facade for the object, if needed.
+   *
+   * @protected
+   * @param {object} obj 
+   * @returns {object}
+   */
+  _createObject(obj) {
+    if (this.cls) {
+      const cls = this.cls;
+      const newObj = new cls(this.connection, obj[this.primaryKey]);
+      newObj.setAll(obj);
+      return newObj;
+    }
+    else {
+      return obj;
+    }
+  }
+
+  /**
+   * Caches the plain objects if needed.
+   * 
+   * @param {Array.<object>} objects
+   * @returns {Array.<object>}
+   */
+  _cache(objects) {
+    return objects;
+  }
+  
+  /**
+   * Get the URL of the next page from a response.
+   * 
+   * @protected
+   * @param {AxiosResponse} response 
+   * @returns {string | null}
+   */
+  _getNextLink(response) {
+    const links = this.connection.makeLinksAbsolute(response.data.links, response);
+    return this.connection._getLinkHref(links, 'next');
+  }
+  
+  /**
+   * Makes this class asynchronously iterable.
+   *
+   * @returns {AsyncIterator}
+   */
+  [Symbol.asyncIterator]() {
+    return {
+      self: this,
+      /**
+       * Get the next page of resources.
+       *
+       * @async
+       * @returns {{done: boolean, value: Array.<object>}}
+       */
+      async next() {
+        const done = !this.self.hasNextPage();
+        let value;
+        if (!done) {
+          value = await this.self.nextPage();
+        }
+        return { done, value };
+      }
+    }
+  }
+
+}
+
+/**
+ * Paginate through jobs.
+ */
+class JobPages extends Pages {
+  /**
+   * Paginate through jobs.
+   *
+   * @param {Connection} connection
+   * @param {?number} limit
+   */
+  constructor(connection, limit = null) {
+    super(connection, "/jobs", "jobs", Job, {limit});
+  }
+}
+
+/**
+ * Paginate through services.
+ */
+class ServicePages extends Pages {
+  /**
+   * Paginate through services.
+   *
+   * @param {Connection} connection
+   * @param {?number} limit
+   */
+  constructor(connection, limit = null) {
+    super(connection, "/services", "services", Service, {limit});
+  }
+}
+
+/**
+ * Paginate through user files.
+ */
+class UserFilePages extends Pages {
+  /**
+   * Paginate through user files.
+   *
+   * @param {Connection} connection
+   * @param {?number} limit
+   */
+  constructor(connection, limit = null) {
+    super(connection, "/files", "files", UserFile, {limit}, "path");
+  }
+}
+
+/**
+ * Paginate through processes.
+ */
+class ProcessPages extends Pages {
+  /**
+   * Paginate through processes.
+   *
+   * @param {Connection} connection
+   * @param {?number} limit
+   * @param {?string} namespace
+   */
+  constructor(connection, limit = null, namespace = null) {
+    if (!namespace) {
+			namespace = 'backend';
+		}
+    let endpoint;
+    let cls = null
+    if (namespace === 'user') {
+      endpoint = '/process_graphs';
+      cls = UserProcess;
+    }
+    else {
+      endpoint = '/processes';
+      if (namespace !== 'backend') {
+        const normalized = connection.normalizeNamespace(namespace);
+        endpoint += `/${normalized}`;
+      }
+    }
+    super(connection, endpoint, "processes", cls, {limit});
+    this.namespace = namespace;
+  }
+
+  /**
+   * Caches the objects to the ProcessRegistry.
+   * 
+   * @param {Array.<object>} objects
+   * @returns {Array.<object>}
+   */
+  _cache(objects) {
+    const plainObjects = objects.map(p => (typeof p.toJSON === 'function' ? p.toJSON() : p));
+    this.connection.processes.addAll(plainObjects, this.namespace);
+    if (!this.cls) {
+      for (let i in objects) {
+        objects[i] = this.connection.processes.get(objects[i].id, this.namespace);
+      }
+    }
+    return objects;
+  }
+}
+
+/**
+ * Paginate through collections.
+ */
+class CollectionPages extends Pages {
+  /**
+   * Paginate through collections.
+   *
+   * @param {Connection} connection
+   * @param {?number} limit
+   */
+  constructor(connection, limit = null) {
+    super(connection, "/collections", "collections", null, {limit});
+  }
+
+  /**
+   * Migrates the STAC collection to the latest version.
+   * 
+   * @param {object} obj 
+   * @returns {Collection}
+   */
+  _createObject(obj) {
+    if (obj.stac_version) {
+      return StacMigrate.collection(obj);
+    }
+    return obj;
+  }
+}
+
+/**
+ * Paginate through collection items.
+ */
+class ItemPages extends Pages {
+  /**
+   * Paginate through collection items.
+   *
+   * @param {Connection} connection
+   * @param {string} collectionId
+   * @param {object} params
+   */
+  constructor(connection, collectionId, params) {
+    super(connection, `/collections/${collectionId}/items`, "features", null, params);
+  }
+
+  /**
+   * Migrates the STAC item to the latest version.
+   * 
+   * @param {object} obj 
+   * @returns {Item}
+   */
+  _createObject(obj) {
+    if (obj.stac_version) {
+      return StacMigrate.item(obj);
+    }
+    return obj;
+  }
+}
+
+module.exports = {
+  Pages,
+  CollectionPages,
+  ItemPages,
+  JobPages,
+  ProcessPages,
+  ServicePages,
+  UserFilePages
+}