refactor(fs): Add Proxy reader

Author: RandomByte

packages/fs/lib/Resource.js

@@ -47,6 +47,8 @@ class Resource {
 	#lastModified;
 	#statInfo;
 	#isDirectory;
+	#integrity;
+	#inode;
 
 	/* States */
 	#isModified = false;
@@ -91,10 +93,12 @@ class Resource {
 	 * @param {boolean} [parameters.isDirectory] Flag whether the resource represents a directory
 	 * @param {number} [parameters.byteSize] Size of the resource content in bytes
 	 * @param {number} [parameters.lastModified] Last modified timestamp (in milliseconds since UNIX epoch)
+	 * @param {string} [parameters.integrity] Integrity hash of the resource content
+	 * @param {number} [parameters.inode] Inode number of the resource
 	 */
 	constructor({
 		path, statInfo, buffer, createBuffer, string, createStream, stream, project, sourceMetadata,
-		isDirectory, byteSize, lastModified,
+		isDirectory, byteSize, lastModified, integrity, inode,
 	}) {
 		if (!path) {
 			throw new Error("Unable to create Resource: Missing parameter 'path'");
@@ -140,6 +144,7 @@ class Resource {
 		this.#sourceMetadata.contentModified ??= false;
 
 		this.#project = project;
+		this.#integrity = integrity;
 
 		if (createStream) {
 			// We store both factories individually
@@ -193,13 +198,21 @@ class Resource {
 			this.#lastModified = lastModified;
 		}
 
+		if (inode !== undefined) {
+			if (typeof inode !== "number" || inode < 0) {
+				throw new Error("Unable to create Resource: Parameter 'inode' must be a positive number");
+			}
+			this.#inode = inode;
+		}
+
 		if (statInfo) {
 			this.#isDirectory ??= statInfo.isDirectory();
 			if (!this.#isDirectory && statInfo.isFile && !statInfo.isFile()) {
 				throw new Error("Unable to create Resource: statInfo must represent either a file or a directory");
 			}
 			this.#byteSize ??= statInfo.size;
 			this.#lastModified ??= statInfo.mtimeMs;
+			this.#inode ??= statInfo.ino;
 
 			// Create legacy statInfo object
 			this.#statInfo = parseStat(statInfo);
@@ -518,7 +531,10 @@ class Resource {
 		this.#contendModified();
 	}
 
-	async getHash() {
+	async getIntegrity() {
+		if (this.#integrity) {
+			return this.#integrity;
+		}
 		if (this.isDirectory()) {
 			throw new Error(`Unable to calculate hash for directory resource: ${this.#path}`);
 		}
@@ -535,27 +551,32 @@ class Resource {
 
 		switch (this.#contentType) {
 		case CONTENT_TYPES.BUFFER:
-			return ssri.fromData(this.#content, SSRI_OPTIONS).toString();
+			this.#integrity = ssri.fromData(this.#content, SSRI_OPTIONS);
+			break;
 		case CONTENT_TYPES.FACTORY:
-			return (await ssri.fromStream(this.#createStreamFactory(), SSRI_OPTIONS)).toString();
+			this.#integrity = await ssri.fromStream(this.#createStreamFactory(), SSRI_OPTIONS);
+			break;
 		case CONTENT_TYPES.STREAM:
 			// To be discussed: Should we read the stream into a buffer here (using #getBufferFromStream) to avoid
 			// draining it?
-			return (await ssri.fromStream(this.#getStream(), SSRI_OPTIONS)).toString();
+			this.#integrity = ssri.fromData(await this.#getBufferFromStream(this.#content), SSRI_OPTIONS);
+			break;
 		case CONTENT_TYPES.DRAINED_STREAM:
 			throw new Error(`Unexpected error: Content of Resource ${this.#path} is flagged as drained.`);
 		case CONTENT_TYPES.IN_TRANSFORMATION:
 			throw new Error(`Unexpected error: Content of Resource ${this.#path} is currently being transformed`);
 		default:
 			throw new Error(`Resource ${this.#path} has no content`);
 		}
+		return this.#integrity;
 	}
 
 	#contendModified() {
 		this.#sourceMetadata.contentModified = true;
 		this.#isModified = true;
 
 		this.#byteSize = undefined;
+		this.#integrity = undefined;
 		this.#lastModified = new Date().getTime(); // TODO: Always update or keep initial value (= fs stat)?
 
 		if (this.#contentType === CONTENT_TYPES.BUFFER) {
@@ -681,6 +702,16 @@ class Resource {
 		return this.#lastModified;
 	}
 
+	/**
+	 * Gets the inode number of the resource.
+	 *
+	 * @public
+	 * @returns {number} Inode number of the resource
+	 */
+	getInode() {
+		return this.#inode;
+	}
+
 	/**
 	 * Resource content size in bytes.
 	 *

packages/fs/lib/readers/Filter.js

@@ -23,6 +23,7 @@ class Filter extends AbstractReader {
 	 *
  	 * @public
 	 * @param {object} parameters Parameters
+	 * @param {object} parameters.name Name of the reader
 	 * @param {@ui5/fs/AbstractReader} parameters.reader The resource reader or collection to wrap
 	 * @param {@ui5/fs/readers/Filter~callback} parameters.callback
 	 * 				Filter function. Will be called for every resource read through this reader.

packages/fs/lib/readers/Link.js

@@ -41,6 +41,7 @@ class Link extends AbstractReader {
 	 *
  	 * @public
 	 * @param {object} parameters Parameters
+	 * @param {object} parameters.name Name of the reader
 	 * @param {@ui5/fs/AbstractReader} parameters.reader The resource reader or collection to wrap
 	 * @param {@ui5/fs/readers/Link/PathMapping} parameters.pathMapping
 	 */

packages/fs/lib/readers/Proxy.js

@@ -0,0 +1,126 @@
+import micromatch from "micromatch";
+import AbstractReader from "../AbstractReader.js";
+
+/**
+ * Callback function to retrieve a resource by its virtual path.
+ *
+ * @public
+ * @callback @ui5/fs/readers/Proxy~getResource
+ * @param {string} virPath Virtual path
+ * @returns {Promise<module:@ui5/fs/Resource>} Promise resolving with a Resource instance
+ */
+
+/**
+ * Callback function to list all available virtual resource paths.
+ *
+ * @public
+ * @callback @ui5/fs/readers/Proxy~listResourcePaths
+ * @returns {Promise<string[]>} Promise resolving to an array of strings (the virtual resource paths)
+ */
+
+/**
+ * Generic proxy adapter. Allowing to serve resources using callback functions. Read only.
+ *
+ * @public
+ * @class
+ * @alias @ui5/fs/readers/Proxy
+ * @extends @ui5/fs/readers/AbstractReader
+ */
+class Proxy extends AbstractReader {
+	/**
+	 * Constructor
+	 *
+	 * @public
+	 * @param {object} parameters
+	 * @param {object} parameters.name Name of the reader
+	 * @param {@ui5/fs/readers/Proxy~getResource} parameters.getResource
+	 * 	Callback function to retrieve a resource by its virtual path.
+	 * @param {@ui5/fs/readers/Proxy~listResourcePaths} parameters.listResourcePaths
+	 * 	Callback function to list all available virtual resource paths.
+	 * @returns {@ui5/fs/readers/Proxy} Reader instance
+	 */
+	constructor({name, getResource, listResourcePaths}) {
+		super(name);
+		if (typeof getResource !== "function") {
+			throw new Error(`Proxy adapter: Missing or invalid parameter 'getResource'`);
+		}
+		if (typeof listResourcePaths !== "function") {
+			throw new Error(`Proxy adapter: Missing or invalid parameter 'listResourcePaths'`);
+		}
+		this._getResource = getResource;
+		this._listResourcePaths = listResourcePaths;
+	}
+
+	async _listResourcePaths() {
+		const virPaths = await this._listResourcePaths();
+		if (!Array.isArray(virPaths) || !virPaths.every((p) => typeof p === "string")) {
+			throw new Error(
+				`Proxy adapter: 'listResourcePaths' did not return an array of strings`);
+		}
+		return virPaths;
+	}
+
+	/**
+	 * Matches and returns resources from a given map (either _virFiles or _virDirs).
+	 *
+	 * @private
+	 * @param {string[]} patterns
+	 * @param {string[]} resourcePaths
+	 * @returns {Promise<module:@ui5/fs.Resource[]>}
+	 */
+	async _matchPatterns(patterns, resourcePaths) {
+		const matchedPaths = micromatch(resourcePaths, patterns, {
+			dot: true
+		});
+		return await Promise.all(matchedPaths.map((virPath) => {
+			return this._getResource(virPath);
+		}));
+	}
+
+	/**
+	 * Locate resources by glob.
+	 *
+	 * @private
+	 * @param {string|string[]} virPattern glob pattern as string or array of glob patterns for
+	 * 										virtual directory structure
+	 * @param {object} [options={}] glob options
+	 * @param {boolean} [options.nodir=true] Do not match directories
+	 * @param {@ui5/fs/tracing.Trace} trace Trace instance
+	 * @returns {Promise<@ui5/fs/Resource[]>} Promise resolving to list of resources
+	 */
+	async _byGlob(virPattern, options = {nodir: true}, trace) {
+		if (!(virPattern instanceof Array)) {
+			virPattern = [virPattern];
+		}
+
+		if (virPattern[0] === "" && !options.nodir) { // Match virtual root directory
+			return [
+				this._createDirectoryResource(this._virBasePath.slice(0, -1))
+			];
+		}
+
+		return await this._matchPatterns(virPattern, await this._listResourcePaths());
+	}
+
+	/**
+	 * Locates resources by path.
+	 *
+	 * @private
+	 * @param {string} virPath Virtual path
+	 * @param {object} options Options
+	 * @param {@ui5/fs/tracing.Trace} trace Trace instance
+	 * @returns {Promise<@ui5/fs/Resource>} Promise resolving to a single resource
+	 */
+	async _byPath(virPath, options, trace) {
+		trace.pathCall();
+
+		const resource = await this._getResource(virPath);
+		if (!resource || (options.nodir && resource.getStatInfo().isDirectory())) {
+			return null;
+		} else {
+			return resource;
+		}
+	}
+}
+
+export default Proxy;

packages/fs/lib/resourceFactory.js

@@ -9,6 +9,7 @@ import Resource from "./Resource.js";
 import WriterCollection from "./WriterCollection.js";
 import Filter from "./readers/Filter.js";
 import Link from "./readers/Link.js";
+import Proxy from "./readers/Proxy.js";
 import Tracker from "./Tracker.js";
 import DuplexTracker from "./DuplexTracker.js";
 import {getLogger} from "@ui5/logger";
@@ -238,6 +239,19 @@ export function createLinkReader(parameters) {
 	return new Link(parameters);
 }
 
+/**
+ * @param {object} parameters
+ * @param {object} parameters.name Name of the reader
+ * @param {@ui5/fs/readers/Proxy~getResource} parameters.getResource
+ * 	Callback function to retrieve a resource by its virtual path.
+ * @param {@ui5/fs/readers/Proxy~listResourcePaths} parameters.listResourcePaths
+ * 	Callback function to list all available virtual resource paths.
+ * @returns {@ui5/fs/readers/Proxy} Reader instance
+ */
+export function createProxy(parameters) {
+	return new Proxy(parameters);
+}
+
 /**
  * Create a [Link-Reader]{@link @ui5/fs/readers/Link} where all requests are prefixed with
  * <code>/resources/<namespace></code>.