[FEATURE] Introduce Readers "Filter" and "Transformer"

index.js

@@ -22,6 +22,21 @@ module.exports = {
  */
  Memory: "./lib/adapters/Memory"
  },
+ /**
+ * @public
+ * @alias module:@ui5/fs.readers
+ * @namespace
+ */
+ readers: {
+ /**
+ * @type {typeof import('./lib/readers/Filter')}
+ */
+ Filter: "./lib/readers/Filter",
+ /**
+ * @type {typeof import('./lib/readers/Transformer')}
+ */
+ Transformer: "./lib/readers/Transformer",
+ },
  /**
  * @type {typeof import('./lib/AbstractReader')}
  */

lib/AbstractReader.js

@@ -70,6 +70,39 @@ class AbstractReader {
  });
  }
 
+
+ /**
+ * Create a [Filter-Reader]{@link module:@ui5/fs.readers.Filter} from the current reader
+ *
+ * @public
+ * @param {module:@ui5/fs.readers.Filter~callback} callback
+ * Filter function. Will be called for every resource passed through this reader.
+ * @returns {module:@ui5/fs.reader.Transformer} T
+ */
+ filter(callback) {
+ const Filter = require("./readers/Filter");
+ return new Filter({
+ reader: this,
+ callback
+ });
+ }
+
+ /**
+ * Create a [Transform-Reader]{@link module:@ui5/fs.readers.Transform} from the current reader
+ *
+ * @public
+ * @param {module:@ui5/fs.readers.Transformer~callback} callback
+ * Callback to check and eventually transform any resource passed through the reader
+ * @returns {module:@ui5/fs.reader.Transformer} T
+ */
+ transformer(callback) {
+ const Transformer = require("./readers/Transformer");
+ return new Transformer({
+ reader: this,
+ callback
+ });
+ }
+
  /**
  * Locates resources by one or more glob patterns.
  *

lib/ResourceTagCollection.js

@@ -2,53 +2,77 @@ const tagNamespaceRegExp = new RegExp("^[a-z][a-z0-9]*$"); // part before the co
 const tagNameRegExp = new RegExp("^[A-Z][A-Za-z0-9]+$"); // part after the colon
 
 class ResourceTagCollection {
- constructor({allowedTags}) {
+ constructor({allowedTags, superCollection}) {
  if (!allowedTags || !allowedTags.length) {
  throw new Error(`Missing parameter 'allowedTags'`);
  }
+
+ if (superCollection) {
+ this._superCollection = superCollection;
+ this._superTags = this._superCollection.getAcceptedTags();
+ } else {
+ this._superTags = [];
+ }
+
  // No validation of tag names here since we might remove/ignore
  // this parameter in the future and generally allow all tags
  this._allowedTags = Object.freeze(allowedTags);
  this._pathTags = {};
  }
 
- setTag(resource, tag, value = true) {
- this._validateResource(resource);
+ setTag(resourcePath, tag, value = true) {
+ if (this._superTags.includes(tag)) {
+ return this._superCollection.setTag(resourcePath, tag, value);
+ }
+
+ resourcePath = this._getPath(resourcePath);
  this._validateTag(tag);
  this._validateValue(value);
 
- const resourcePath = resource.getPath();
  if (!this._pathTags[resourcePath]) {
  this._pathTags[resourcePath] = {};
  }
  this._pathTags[resourcePath][tag] = value;
  }
 
- clearTag(resource, tag) {
- this._validateResource(resource);
+ clearTag(resourcePath, tag) {
+ if (this._superTags.includes(tag)) {
+ return this._superCollection.clearTag(resourcePath, tag);
+ }
+
+ resourcePath = this._getPath(resourcePath);
  this._validateTag(tag);
 
- const resourcePath = resource.getPath();
  if (this._pathTags[resourcePath]) {
  this._pathTags[resourcePath][tag] = undefined;
  }
  }
 
- getTag(resource, tag) {
- this._validateResource(resource);
+ getTag(resourcePath, tag) {
+ if (this._superTags.includes(tag)) {
+ return this._superCollection.getTag(resourcePath, tag);
+ }
+
+ resourcePath = this._getPath(resourcePath);
  this._validateTag(tag);
 
- const resourcePath = resource.getPath();
  if (this._pathTags[resourcePath]) {
  return this._pathTags[resourcePath][tag];
  }
  }
 
- _validateResource(resource) {
- const path = resource.getPath();
- if (!path) {
+ getAcceptedTags() {
+ return [...this._allowedTags, ...this._superTags];
+ }
+
+ _getPath(resourcePath) {
+ if (typeof resourcePath !== "string") {
+ resourcePath = resourcePath.getPath();
+ }
+ if (!resourcePath) {
  throw new Error(`Invalid Resource: Resource path must not be empty`);
  }
+ return resourcePath;
  }
 
  _validateTag(tag) {

lib/readers/Filter.js

@@ -0,0 +1,73 @@
+const AbstractReader = require("../AbstractReader");
+
+/**
+ * A reader that allows dynamic filtering of resources passed through it
+ *
+ * @public
+ * @memberof module:@ui5/fs
+ * @augments module:@ui5/fs.AbstractReader
+ */
+class Filter extends AbstractReader {
+ /**
+ * Filter callback
+ *
+ * @public
+ * @callback module:@ui5/fs.readers.Filter~callback
+ * @param {module:@ui5/fs.Resource} resource Resource to test
+ * @returns {boolean} Return <code>true</code> to keep the resource, or <code>false</code> to disregard it
+ */
+
+ /**
+ * Constructor
+ *
+ * @param {object} parameters Parameters
+ * @param {module:@ui5/fs.AbstractReader} parameters.reader The resource reader to wrap
+ * @param {module:@ui5/fs.readers.Filter~callback} parameters.callback
+ * Filter function. Will be called for every resource read through this reader.
+ */
+ constructor({reader, callback}) {
+ super();
+ if (!reader) {
+ throw new Error(`Missing parameter "reader"`);
+ }
+ if (!callback) {
+ throw new Error(`Missing parameter "callback"`);
+ }
+ this._reader = reader;
+ this._callback = callback;
+ }
+
+ /**
+ * Locates resources by glob.
+ *
+ * @private
+ * @param {string|string[]} pattern glob pattern as string or an array of
+ * glob patterns for virtual directory structure
+ * @param {object} options glob options
+ * @param {module:@ui5/fs.tracing.Trace} trace Trace instance
+ * @returns {Promise<module:@ui5/fs.Resource[]>} Promise resolving to list of resources
+ */
+ async _byGlob(pattern, options, trace) {
+ const result = await this._reader._byGlob(pattern, options, trace);
+ return result.filter(this._callback);
+ }
+
+ /**
+ * Locates resources by path.
+ *
+ * @private
+ * @param {string} virPath Virtual path
+ * @param {object} options Options
+ * @param {module:@ui5/fs.tracing.Trace} trace Trace instance
+ * @returns {Promise<module:@ui5/fs.Resource>} Promise resolving to a single resource
+ */
+ async _byPath(virPath, options, trace) {
+ const result = await this._reader._byPath(virPath, options, trace);
+ if (result && !this._callback(result)) {
+ return null;
+ }
+ return result;
+ }
+}
+
+module.exports = Filter;

lib/readers/Transformer.js

@@ -0,0 +1,98 @@
+const AbstractReader = require("../AbstractReader");
+
+/**
+ * A reader that allows modification of all resources passed through it.
+ *
+ * @public
+ * @memberof module:@ui5/fs.readers
+ * @augments module:@ui5/fs.AbstractReader
+ */
+class Transformer extends AbstractReader {
+ /**
+ * Callback to check and eventually transform a resource
+ *
+ * @public
+ * @callback module:@ui5/fs.readers.Transformer~callback
+ * @param {module:@ui5/fs.Resource} resourcePath Path of the resource to process.
+ * This can be used to decide whether the resource should be transformed
+ * @param {module:@ui5/fs.readers.Transformer~getResource}
+ * Function to retrieve the given resource instance in order to transform it
+ * @returns {Promise} Promise resolving once the transformation is done
+ */
+
+ /**
+ * Callback to retrieve a resource for modification. This will create a clone of the original
+ * resource which then takes its place in the result set of the reader
+ *
+ * @public
+ * @callback module:@ui5/fs.readers.Transformer~getResource
+ * @returns {Promise<module:@ui5/fs.Resource>} Promise resolving to the resource
+ */
+
+ /**
+ * Constructor
+ *
+ * @param {object} parameters Parameters
+ * @param {module:@ui5/fs.AbstractReader} parameters.reader The resource reader to wrap
+ * @param {module:@ui5/fs.readers.Transformer~callback} parameters.callback
+ * Filter function. Will be called for every resource read through this reader.
+ */
+ constructor({reader, callback}) {
+ super();
+ if (!reader) {
+ throw new Error(`Missing parameter "reader"`);
+ }
+ if (!callback) {
+ throw new Error(`Missing parameter "callback"`);
+ }
+ this._reader = reader;
+ this._callback = callback;
+ }
+
+ /**
+ * Locates resources by glob.
+ *
+ * @private
+ * @param {string|string[]} pattern glob pattern as string or an array of
+ * glob patterns for virtual directory structure
+ * @param {object} options glob options
+ * @param {module:@ui5/fs.tracing.Trace} trace Trace instance
+ * @returns {Promise<module:@ui5/fs.Resource[]>} Promise resolving to list of resources
+ */
+ async _byGlob(pattern, options, trace) {
+ const result = await this._reader._byGlob(pattern, options, trace);
+ return Promise.all(result.map(async (resource) => {
+ let resourceClone;
+ await this._callback(resource.getPath(), async function() {
+ // Make sure to only clone once
+ resourceClone = resourceClone || await resource.clone();
+ return resourceClone;
+ });
+ return resourceClone || resource;
+ }));
+ }
+
+ /**
+ * Locates resources by path.
+ *
+ * @private
+ * @param {string} virPath Virtual path
+ * @param {object} options Options
+ * @param {module:@ui5/fs.tracing.Trace} trace Trace instance
+ * @returns {Promise<module:@ui5/fs.Resource>} Promise resolving to a single resource
+ */
+ async _byPath(virPath, options, trace) {
+ const resource = await this._reader._byPath(virPath, options, trace);
+ let resourceClone;
+ if (resource) {
+ await this._callback(resource.getPath(), async function() {
+ // Make sure to only clone once
+ resourceClone = resourceClone || await resource.clone();
+ return resourceClone;
+ });
+ }
+ return resourceClone || resource;
+ }
+}
+
+module.exports = Transformer;