project/lib/build/helpers/TaskUtil.js

  1. import {
  2. 	createReaderCollection,
  3. 	createReaderCollectionPrioritized,
  4. 	createResource,
  5. 	createFilterReader,
  6. 	createLinkReader,
  7. 	createFlatReader
  8. } from "@ui5/fs/resourceFactory";
  10. /**
  11.  * Convenience functions for UI5 tasks.
  12.  * An instance of this class is passed to every standard UI5 task that requires it.
  13.  *
  14.  * Custom tasks that define a specification version >= 2.2 will receive an interface
  15.  * to an instance of this class when called.
  16.  * The set of available functions on that interface depends on the specification
  17.  * version defined for the extension.
  18.  *
  19.  * @public
  20.  * @class
  21.  * @alias @ui5/project/build/helpers/TaskUtil
  22.  * @hideconstructor
  23.  */
  24. class TaskUtil {
  25. 	/**
  26. 	 * Standard Build Tags. See UI5 Tooling
  27. 	 * [RFC 0008]{@link https://github.com/SAP/ui5-tooling/blob/main/rfcs/0008-resource-tagging-during-build.md}
  28. 	 * for details.
  29. 	 *
  30. 	 * @public
  31. 	 * @typedef {object} @ui5/project/build/helpers/TaskUtil~StandardBuildTags
  32. 	 * @property {string} OmitFromBuildResult
  33. 	 * 		Setting this tag to true will prevent the resource from being written to the build target directory
  34. 	 * @property {string} IsBundle
  35. 	 * 		This tag identifies resources that contain (i.e. bundle) multiple other resources
  36. 	 * @property {string} IsDebugVariant
  37. 	 * 		This tag identifies resources that are a debug variant (typically named with a "-dbg" suffix)
  38. 	 * 		of another resource. This tag is part of the build manifest.
  39. 	 * @property {string} HasDebugVariant
  40. 	 * 		This tag identifies resources for which a debug variant has been created.
  41. 	 * 		This tag is part of the build manifest.
  42. 	 */
  44. 	/**
  45. 	 * Since <code>@ui5/project/build/helpers/ProjectBuildContext</code> is a private class, TaskUtil must not be
  46. 	 * instantiated by modules other than @ui5/project itself.
  47. 	 *
  48. 	 * @param {object} parameters
  49. 	 * @param {@ui5/project/build/helpers/ProjectBuildContext} parameters.projectBuildContext ProjectBuildContext
  50. 	 * @public
  51. 	 */
  52. 	constructor({projectBuildContext}) {
  53. 		this._projectBuildContext = projectBuildContext;
  54. 		/**
  55. 		 * @member {@ui5/project/build/helpers/TaskUtil~StandardBuildTags}
  56. 		 * @public
  57. 		*/
  58. 		this.STANDARD_TAGS = Object.freeze({
  59. 			// "Project" tags:
  60. 			// Will be stored on project instance and are hence part of the build manifest
  61. 			IsDebugVariant: "ui5:IsDebugVariant",
  62. 			HasDebugVariant: "ui5:HasDebugVariant",
  64. 			// "Build" tags:
  65. 			// Will be stored on the project build context
  66. 			// They are only available to the build tasks of a single project
  67. 			OmitFromBuildResult: "ui5:OmitFromBuildResult",
  68. 			IsBundle: "ui5:IsBundle"
  69. 		});
  70. 	}
  72. 	/**
  73. 	 * Stores a tag with value for a given resource's path. Note that the tag is independent of the supplied
  74. 	 * resource instance. For two resource instances with the same path, the same tag value is returned.
  75. 	 * If the path of a resource is changed, any tag information previously stored for that resource is lost.
  76. 	 *
  77. 	 * </br></br>
  78. 	 * This method is only available to custom task extensions defining
  79. 	 * <b>Specification Version 2.2 and above</b>.
  80. 	 *
  81. 	 * @param {@ui5/fs/Resource} resource Resource-instance the tag should be stored for
  82. 	 * @param {string} tag Name of the tag. Currently only the
  83. 	 * 	[STANDARD_TAGS]{@link @ui5/project/build/helpers/TaskUtil#STANDARD_TAGS} are allowed
  84. 	 * @param {string|boolean|integer} [value=true] Tag value. Must be primitive
  85. 	 * @public
  86. 	 */
  87. 	setTag(resource, tag, value) {
  88. 		if (typeof resource === "string") {
  89. 			throw new Error("Deprecated parameter: " +
  90. 				"Since UI5 Tooling 3.0, #setTag requires a resource instance. Strings are no longer accepted");
  91. 		}
  93. 		const collection = this._projectBuildContext.getResourceTagCollection(resource, tag);
  94. 		return collection.setTag(resource, tag, value);
  95. 	}
  97. 	/**
  98. 	 * Retrieves the value for a stored tag. If no value is stored, <code>undefined</code> is returned.
  99. 	 *
  100. 	 * </br></br>
  101. 	 * This method is only available to custom task extensions defining
  102. 	 * <b>Specification Version 2.2 and above</b>.
  103. 	 *
  104. 	 * @param {@ui5/fs/Resource} resource Resource-instance the tag should be retrieved for
  105. 	 * @param {string} tag Name of the tag
  106. 	 * @returns {string|boolean|integer|undefined} Tag value for the given resource.
  107. 	 * 										<code>undefined</code> if no value is available
  108. 	 * @public
  109. 	 */
  110. 	getTag(resource, tag) {
  111. 		if (typeof resource === "string") {
  112. 			throw new Error("Deprecated parameter: " +
  113. 				"Since UI5 Tooling 3.0, #getTag requires a resource instance. Strings are no longer accepted");
  114. 		}
  115. 		const collection = this._projectBuildContext.getResourceTagCollection(resource, tag);
  116. 		return collection.getTag(resource, tag);
  117. 	}
  119. 	/**
  120. 	 * Clears the value of a tag stored for the given resource's path.
  121. 	 * It's like the tag was never set for that resource.
  122. 	 *
  123. 	 * </br></br>
  124. 	 * This method is only available to custom task extensions defining
  125. 	 * <b>Specification Version 2.2 and above</b>.
  126. 	 *
  127. 	 * @param {@ui5/fs/Resource} resource Resource-instance the tag should be cleared for
  128. 	 * @param {string} tag Tag
  129. 	 * @public
  130. 	 */
  131. 	clearTag(resource, tag) {
  132. 		if (typeof resource === "string") {
  133. 			throw new Error("Deprecated parameter: " +
  134. 				"Since UI5 Tooling 3.0, #clearTag requires a resource instance. Strings are no longer accepted");
  135. 		}
  136. 		const collection = this._projectBuildContext.getResourceTagCollection(resource, tag);
  137. 		return collection.clearTag(resource, tag);
  138. 	}
  140. 	/**
  141. 	 * Check whether the project currently being built is the root project.
  142. 	 *
  143. 	 * </br></br>
  144. 	 * This method is only available to custom task extensions defining
  145. 	 * <b>Specification Version 2.2 and above</b>.
  146. 	 *
  147. 	 * @returns {boolean} <code>true</code> if the currently built project is the root project
  148. 	 * @public
  149. 	 */
  150. 	isRootProject() {
  151. 		return this._projectBuildContext.isRootProject();
  152. 	}
  154. 	/**
  155. 	 * Retrieves a build option defined by its <code>key</code.
  156. 	 * If no option with the given <code>key</code> is stored, <code>undefined</code> is returned.
  157. 	 *
  158. 	 * @param {string} key The option key
  159. 	 * @returns {any|undefined} The build option (or undefined)
  160. 	 * @private
  161. 	 */
  162. 	getBuildOption(key) {
  163. 		return this._projectBuildContext.getOption(key);
  164. 	}
  166. 	/**
  167. 	 * Callback that is executed once the build has finished
  168. 	 *
  169. 	 * @public
  170. 	 * @callback @ui5/project/build/helpers/TaskUtil~cleanupTaskCallback
  171. 	 * @param {boolean} force Whether the cleanup callback should
  172. 	 * 							gracefully wait for certain jobs to be completed (<code>false</code>)
  173. 	 * 							or enforce immediate termination (<code>true</code>)
  174. 	 */
  176. 	/**
  177. 	 * Register a function that must be executed once the build is finished. This can be used to, for example,
  178. 	 * clean up files temporarily created on the file system. If the callback returns a Promise, it will be waited for.
  179. 	 * It will also be executed in cases where the build has failed or has been aborted.
  180. 	 *
  181. 	 * </br></br>
  182. 	 * This method is only available to custom task extensions defining
  183. 	 * <b>Specification Version 2.2 and above</b>.
  184. 	 *
  185. 	 * @param {@ui5/project/build/helpers/TaskUtil~cleanupTaskCallback} callback Callback to
  186. 	 * 									register; it will be waited for if it returns a Promise
  187. 	 * @public
  188. 	 */
  189. 	registerCleanupTask(callback) {
  190. 		return this._projectBuildContext.registerCleanupTask(callback);
  191. 	}
  193. 	/**
  194. 	 * Specification Version-dependent [Project]{@link @ui5/project/specifications/Project} interface.
  195. 	 * For details on individual functions, see [Project]{@link @ui5/project/specifications/Project}
  196. 	 *
  197. 	 * @public
  198. 	 * @typedef {object} @ui5/project/build/helpers/TaskUtil~ProjectInterface
  199. 	 * @property {Function} getType Get the project type
  200. 	 * @property {Function} getName Get the project name
  201. 	 * @property {Function} getVersion Get the project version
  202. 	 * @property {Function} getNamespace Get the project namespace
  203. 	 * @property {Function} getRootReader Get the project rootReader
  204. 	 * @property {Function} getReader Get the project reader
  205. 	 * @property {Function} getRootPath Get the local File System path of the project's root directory
  206. 	 * @property {Function} getSourcePath Get the local File System path of the project's source directory
  207. 	 * @property {Function} getCustomConfiguration Get the project Custom Configuration
  208. 	 * @property {Function} isFrameworkProject Check whether the project is a UI5-Framework project
  209. 	 * @property {Function} getFrameworkName Get the project's framework name configuration
  210. 	 * @property {Function} getFrameworkVersion Get the project's framework version configuration
  211. 	 * @property {Function} getFrameworkDependencies Get the project's framework dependencies configuration
  212. 	 */
  214. 	/**
  215. 	 * Retrieve a single project from the dependency graph
  216. 	 *
  217. 	 * </br></br>
  218. 	 * This method is only available to custom task extensions defining
  219. 	 * <b>Specification Version 3.0 and above</b>.
  220. 	 *
  221. 	 * @param {string|@ui5/fs/Resource} [projectNameOrResource]
  222. 	 * Name of the project to retrieve or a Resource instance to retrieve the associated project for.
  223. 	 * Defaults to the name of the project currently being built
  224. 	 * @returns {@ui5/project/build/helpers/TaskUtil~ProjectInterface|undefined}
  225. 	 * Specification Version-dependent interface to the Project instance or <code>undefined</code>
  226. 	 * if the project name is unknown or the provided resource is not associated with any project.
  227. 	 * @public
  228. 	 */
  229. 	getProject(projectNameOrResource) {
  230. 		if (projectNameOrResource) {
  231. 			if (typeof projectNameOrResource === "string" || projectNameOrResource instanceof String) {
  232. 				// A project name has been provided
  233. 				return this._projectBuildContext.getProject(projectNameOrResource);
  234. 			} else {
  235. 				// A Resource instance has been provided
  236. 				return projectNameOrResource.getProject();
  237. 			}
  238. 		}
  239. 		// No parameter has been provided, default to the project currently being built.
  240. 		return this._projectBuildContext.getProject();
  241. 	}
  243. 	/**
  244. 	 * Retrieve a list of direct dependencies of a given project from the dependency graph.
  245. 	 * Note that this list does not include transitive dependencies.
  246. 	 *
  247. 	 * </br></br>
  248. 	 * This method is only available to custom task extensions defining
  249. 	 * <b>Specification Version 3.0 and above</b>.
  250. 	 *
  251. 	 * @param {string} [projectName] Name of the project to retrieve. Defaults to the project currently being built
  252. 	 * @returns {string[]} Names of all direct dependencies
  253. 	 * @throws {Error} If the requested project is unknown to the graph
  254. 	 * @public
  255. 	 */
  256. 	getDependencies(projectName) {
  257. 		return this._projectBuildContext.getDependencies(projectName);
  258. 	}
  260. 	/**
  261. 	 * Specification Version-dependent set of [@ui5/fs/resourceFactory]{@link @ui5/fs/resourceFactory}
  262. 	 * functions provided to tasks.
  263. 	 * For details on individual functions, see [@ui5/fs/resourceFactory]{@link @ui5/fs/resourceFactory}
  264. 	 *
  265. 	 * @public
  266. 	 * @typedef {object} @ui5/project/build/helpers/TaskUtil~resourceFactory
  267. 	 * @property {Function} createResource Creates a [Resource]{@link @ui5/fs/Resource}.
  268. 	 * 	Accepts the same parameters as the [Resource]{@link @ui5/fs/Resource} constructor.
  269. 	 * @property {Function} createReaderCollection Creates a reader collection:
  270. 	 *	[ReaderCollection]{@link @ui5/fs/ReaderCollection}
  271. 	 * @property {Function} createReaderCollectionPrioritized Creates a prioritized reader collection:
  272. 	 *	[ReaderCollectionPrioritized]{@link @ui5/fs/ReaderCollectionPrioritized}
  273. 	 * @property {Function} createFilterReader
  274. 	 * 	Create a [Filter-Reader]{@link @ui5/fs/readers/Filter} with the given reader.
  275. 	 * @property {Function} createLinkReader
  276. 	 * 	Create a [Link-Reader]{@link @ui5/fs/readers/Filter} with the given reader.
  277. 	 * @property {Function} createFlatReader Create a [Link-Reader]{@link @ui5/fs/readers/Link}
  278. 	 * where all requests are prefixed with <code>/resources/<namespace></code>.
  279. 	 */
  281. 	/**
  282. 	 * Provides limited access to [@ui5/fs/resourceFactory]{@link @ui5/fs/resourceFactory} functions
  283. 	 *
  284. 	 * </br></br>
  285. 	 * This attribute is only available to custom task extensions defining
  286. 	 * <b>Specification Version 3.0 and above</b>.
  287. 	 *
  288. 	 * @type {@ui5/project/build/helpers/TaskUtil~resourceFactory}
  289. 	 * @public
  290. 	 */
  291. 	resourceFactory = {
  292. 		createResource,
  293. 		createReaderCollection,
  294. 		createReaderCollectionPrioritized,
  295. 		createFilterReader,
  296. 		createLinkReader,
  297. 		createFlatReader,
  298. 	};
  300. 	/**
  301. 	 * Get an interface to an instance of this class that only provides those functions
  302. 	 * that are supported by the given custom task extension specification version.
  303. 	 *
  304. 	 * @param {@ui5/project/specifications/SpecificationVersion} specVersion
  305. 	 * SpecVersionComparator instance of the custom task
  306. 	 * @returns {object} An object with bound instance methods supported by the given specification version
  307. 	 */
  308. 	getInterface(specVersion) {
  309. 		if (specVersion.lte("2.1")) {
  310. 			// Tasks defining specVersion <= 2.1 do not have access to any TaskUtil APIs
  311. 			return undefined;
  312. 		}
  314. 		const baseInterface = {
  315. 			STANDARD_TAGS: this.STANDARD_TAGS,
  316. 		};
  317. 		bindFunctions(this, baseInterface, [
  318. 			"setTag", "clearTag", "getTag", "isRootProject", "registerCleanupTask"
  319. 		]);
  321. 		if (specVersion.gte("3.0")) {
  322. 			// getProject function, returning an interfaced project instance
  323. 			baseInterface.getProject = (projectName) => {
  324. 				const project = this.getProject(projectName);
  325. 				const baseProjectInterface = {};
  326. 				bindFunctions(project, baseProjectInterface, [
  327. 					"getType", "getName", "getVersion", "getNamespace",
  328. 					"getRootReader", "getReader", "getRootPath", "getSourcePath",
  329. 					"getCustomConfiguration", "isFrameworkProject", "getFrameworkName",
  330. 					"getFrameworkVersion", "getFrameworkDependencies"
  331. 				]);
  332. 				return baseProjectInterface;
  333. 			};
  334. 			// getDependencies function, returning an array of project names
  335. 			baseInterface.getDependencies = (projectName) => {
  336. 				return this.getDependencies(projectName);
  337. 			};
  339. 			baseInterface.resourceFactory = Object.create(null);
  340. 			[
  341. 				// Once new functions get added, extract this array into a variable
  342. 				// and enhance based on spec version once new functions get added
  343. 				"createResource", "createReaderCollection", "createReaderCollectionPrioritized",
  344. 				"createFilterReader", "createLinkReader", "createFlatReader",
  345. 			].forEach((factoryFunction) => {
  346. 				baseInterface.resourceFactory[factoryFunction] = this.resourceFactory[factoryFunction];
  347. 			});
  348. 		}
  349. 		return baseInterface;
  350. 	}
  351. }
  353. function bindFunctions(sourceObject, targetObject, funcNames) {
  354. 	funcNames.forEach((funcName) => {
  355. 		targetObject[funcName] = sourceObject[funcName].bind(sourceObject);
  356. 	});
  357. }
  359. export default TaskUtil;