fs/lib/AbstractReader.js

  1. import randomInt from "random-int";
  2. import Trace from "./tracing/Trace.js";
  4. /**
  5.  * Abstract resource locator implementing the general API for <b>reading</b> resources
  6.  *
  7.  * @abstract
  8.  * @public
  9.  * @class
  10.  * @alias @ui5/fs/AbstractReader
  11.  */
  12. class AbstractReader {
  13. 	/**
  14. 	 * The constructor.
  15. 	 *
  16. 	 * @public
  17. 	 * @param {string} name Name of the reader. Typically used for tracing purposes
  18. 	 */
  19. 	constructor(name) {
  20. 		if (new.target === AbstractReader) {
  21. 			throw new TypeError("Class 'AbstractReader' is abstract");
  22. 		}
  23. 		this._name = name;
  24. 	}
  26. 	/*
  27. 	 * Returns the name of the reader instance. This can be used for logging/tracing purposes.
  28. 	 *
  29. 	 * @returns {string} Name of the reader
  30. 	 */
  31. 	getName() {
  32. 		return this._name || `<unnamed ${this.constructor.name} Reader>`;
  33. 	}
  35. 	/**
  36. 	 * Locates resources by matching glob patterns.
  37. 	 *
  38. 	 * @example
  39. 	 * byGlob("**‏/*.{html,htm}");
  40. 	 * byGlob("**‏/.library");
  41. 	 * byGlob("/pony/*");
  42. 	 *
  43. 	 * @public
  44. 	 * @param {string|string[]} virPattern glob pattern as string or array of glob patterns for
  45. 	 * 										virtual directory structure
  46. 	 * @param {object} [options] glob options
  47. 	 * @param {boolean} [options.nodir=true] Do not match directories
  48. 	 * @returns {Promise<@ui5/fs/Resource[]>} Promise resolving to list of resources
  49. 	 */
  50. 	byGlob(virPattern, options = {nodir: true}) {
  51. 		const trace = new Trace(virPattern);
  52. 		return this._byGlob(virPattern, options, trace).then(function(result) {
  53. 			trace.printReport();
  54. 			return result;
  55. 		}).then((resources) => {
  56. 			if (resources.length > 1) {
  57. 				// Pseudo randomize result order to prevent consumers from relying on it:
  58. 				// Swap the first object with a randomly chosen one
  59. 				const x = 0;
  60. 				const y = randomInt(0, resources.length - 1);
  61. 				// Swap object at index "x" with  "y"
  62. 				resources[x] = [resources[y], resources[y]=resources[x]][0];
  63. 			}
  64. 			return resources;
  65. 		});
  66. 	}
  68. 	/**
  69. 	 * Locates resources by matching a given path.
  70. 	 *
  71. 	 * @public
  72. 	 * @param {string} virPath Virtual path
  73. 	 * @param {object} [options] Options
  74. 	 * @param {boolean} [options.nodir=true] Do not match directories
  75. 	 * @returns {Promise<@ui5/fs/Resource>} Promise resolving to a single resource
  76. 	 */
  77. 	byPath(virPath, options = {nodir: true}) {
  78. 		const trace = new Trace(virPath);
  79. 		return this._byPath(virPath, options, trace).then(function(resource) {
  80. 			trace.printReport();
  81. 			return resource;
  82. 		});
  83. 	}
  85. 	/**
  86. 	 * Locates resources by one or more glob patterns.
  87. 	 *
  88. 	 * @abstract
  89. 	 * @protected
  90. 	 * @param {string|string[]} virPattern glob pattern as string or an array of
  91. 	 *         glob patterns for virtual directory structure
  92. 	 * @param {object} options glob options
  93. 	 * @param {@ui5/fs/tracing.Trace} trace Trace instance
  94. 	 * @returns {Promise<@ui5/fs/Resource[]>} Promise resolving to list of resources
  95. 	 */
  96. 	_byGlob(virPattern, options, trace) {
  97. 		throw new Error("Function '_byGlob' is not implemented");
  98. 	}
  100. 	/**
  101. 	 * Locate resources by matching a single glob pattern.
  102. 	 *
  103. 	 * @abstract
  104. 	 * @protected
  105. 	 * @param {string} pattern glob pattern
  106. 	 * @param {object} options glob options
  107. 	 * @param {@ui5/fs/tracing.Trace} trace Trace instance
  108. 	 * @returns {Promise<@ui5/fs/Resource[]>} Promise resolving to list of resources
  109. 	 */
  110. 	_runGlob(pattern, options, trace) {
  111. 		throw new Error("Function '_runGlob' is not implemented");
  112. 	}
  114. 	/**
  115. 	 * Locates resources by path.
  116. 	 *
  117. 	 * @abstract
  118. 	 * @protected
  119. 	 * @param {string} virPath Virtual path
  120. 	 * @param {object} options Options
  121. 	 * @param {@ui5/fs/tracing.Trace} trace Trace instance
  122. 	 * @returns {Promise<@ui5/fs/Resource>} Promise resolving to a single resource
  123. 	 */
  124. 	_byPath(virPath, options, trace) {
  125. 		throw new Error("Function '_byPath' is not implemented");
  126. 	}
  127. }
  129. export default AbstractReader;