project/lib/specifications/Project.js

  1. import Specification from "./Specification.js";
  2. import ResourceTagCollection from "@ui5/fs/internal/ResourceTagCollection";
  4. /**
  5.  * Project
  6.  *
  7.  * @public
  8.  * @abstract
  9.  * @class
  10.  * @alias @ui5/project/specifications/Project
  11.  * @extends @ui5/project/specifications/Specification
  12.  * @hideconstructor
  13.  */
  14. class Project extends Specification {
  15. 	constructor(parameters) {
  16. 		super(parameters);
  17. 		if (new.target === Project) {
  18. 			throw new TypeError("Class 'Project' is abstract. Please use one of the 'types' subclasses");
  19. 		}
  21. 		this._resourceTagCollection = null;
  22. 	}
  24. 	/**
  25. 	 * @param {object} parameters Specification parameters
  26. 	 * @param {string} parameters.id Unique ID
  27. 	 * @param {string} parameters.version Version
  28. 	 * @param {string} parameters.modulePath File System path to access resources
  29. 	 * @param {object} parameters.configuration Configuration object
  30. 	 * @param {object} [parameters.buildManifest] Build metadata object
  31. 	 */
  32. 	async init(parameters) {
  33. 		await super.init(parameters);
  35. 		this._buildManifest = parameters.buildManifest;
  37. 		await this._configureAndValidatePaths(this._config);
  38. 		await this._parseConfiguration(this._config, this._buildManifest);
  40. 		return this;
  41. 	}
  43. 	/* === Attributes === */
  44. 	/**
  45. 	 * Get the project namespace. Returns `null` for projects that have none or multiple namespaces,
  46. 	 * for example Modules or Theme Libraries.
  47. 	 *
  48. 	 * @public
  49. 	 * @returns {string|null} Project namespace in slash notation (e.g. <code>my/project/name</code>) or null
  50. 	 */
  51. 	getNamespace() {
  52. 		// Default namespace for general Projects:
  53. 		// Their resources should be structured with globally unique paths, hence their namespace is undefined
  54. 		return null;
  55. 	}
  57. 	/**
  58. 	 * Check whether the project is a UI5-Framework project
  59. 	 *
  60. 	 * @public
  61. 	 * @returns {boolean} True if the project is a framework project
  62. 	 */
  63. 	isFrameworkProject() {
  64. 		const id = this.getId();
  65. 		return id.startsWith("@openui5/") || id.startsWith("@sapui5/");
  66. 	}
  68. 	/**
  69. 	 * Get the project's customConfiguration
  70. 	 *
  71. 	 * @public
  72. 	 * @returns {object} Custom Configuration
  73. 	 */
  74. 	getCustomConfiguration() {
  75. 		return this._config.customConfiguration;
  76. 	}
  78. 	/**
  79. 	 * Get the path of the project's source directory. This might not be POSIX-style on some platforms.
  80. 	 * Projects with multiple source paths will throw an error. For example Modules.
  81. 	 *
  82. 	 * @public
  83. 	 * @returns {string} Absolute path to the source directory of the project
  84. 	 * @throws {Error} In case a project has multiple source directories
  85. 	 */
  86. 	getSourcePath() {
  87. 		throw new Error(`getSourcePath must be implemented by subclass ${this.constructor.name}`);
  88. 	}
  90. 	/**
  91. 	 * Get the project's framework name configuration
  92. 	 *
  93. 	 * @public
  94. 	 * @returns {string} Framework name configuration, either <code>OpenUI5</code> or <code>SAPUI5</code>
  95. 	 */
  96. 	getFrameworkName() {
  97. 		return this._config.framework?.name;
  98. 	}
  100. 	/**
  101. 	 * Get the project's framework version configuration
  102. 	 *
  103. 	 * @public
  104. 	 * @returns {string} Framework version configuration, e.g <code>1.110.0</code>
  105. 	 */
  106. 	getFrameworkVersion() {
  107. 		return this._config.framework?.version;
  108. 	}
  111. 	/**
  112. 	 * Framework dependency entry of the project configuration.
  113. 	 * Also see [Framework Configuration: Dependencies]{@link https://sap.github.io/ui5-tooling/stable/pages/Configuration/#dependencies}
  114. 	 *
  115. 	 * @public
  116. 	 * @typedef {object} @ui5/project/specifications/Project~FrameworkDependency
  117. 	 * @property {string} name Name of the framework library. For example <code>sap.ui.core</code>
  118. 	 * @property {boolean} development Whether the dependency is meant for development purposes only
  119. 	 * @property {boolean} optional Whether the dependency should be treated as optional
  120. 	 */
  122. 	/**
  123. 	 * Get the project's framework dependencies configuration
  124. 	 *
  125. 	 * @public
  126. 	 * @returns {@ui5/project/specifications/Project~FrameworkDependency[]} Framework dependencies configuration
  127. 	 */
  128. 	getFrameworkDependencies() {
  129. 		return this._config.framework?.libraries || [];
  130. 	}
  132. 	/**
  133. 	 * Get the project's deprecated configuration
  134. 	 *
  135. 	 * @private
  136. 	 * @returns {boolean} True if the project is flagged as deprecated
  137. 	 */
  138. 	isDeprecated() {
  139. 		return !!this._config.metadata.deprecated;
  140. 	}
  142. 	/**
  143. 	 * Get the project's sapInternal configuration
  144. 	 *
  145. 	 * @private
  146. 	 * @returns {boolean} True if the project is flagged as SAP-internal
  147. 	 */
  148. 	isSapInternal() {
  149. 		return !!this._config.metadata.sapInternal;
  150. 	}
  152. 	/**
  153. 	 * Get the project's allowSapInternal configuration
  154. 	 *
  155. 	 * @private
  156. 	 * @returns {boolean} True if the project allows for using SAP-internal projects
  157. 	 */
  158. 	getAllowSapInternal() {
  159. 		return !!this._config.metadata.allowSapInternal;
  160. 	}
  162. 	/**
  163. 	 * Get the project's builderResourcesExcludes configuration
  164. 	 *
  165. 	 * @private
  166. 	 * @returns {string[]} BuilderResourcesExcludes configuration
  167. 	 */
  168. 	getBuilderResourcesExcludes() {
  169. 		return this._config.builder?.resources?.excludes || [];
  170. 	}
  172. 	/**
  173. 	 * Get the project's customTasks configuration
  174. 	 *
  175. 	 * @private
  176. 	 * @returns {object[]} CustomTasks configuration
  177. 	 */
  178. 	getCustomTasks() {
  179. 		return this._config.builder?.customTasks || [];
  180. 	}
  182. 	/**
  183. 	 * Get the project's customMiddleware configuration
  184. 	 *
  185. 	 * @private
  186. 	 * @returns {object[]} CustomMiddleware configuration
  187. 	 */
  188. 	getCustomMiddleware() {
  189. 		return this._config.server?.customMiddleware || [];
  190. 	}
  192. 	/**
  193. 	 * Get the project's serverSettings configuration
  194. 	 *
  195. 	 * @private
  196. 	 * @returns {object} ServerSettings configuration
  197. 	 */
  198. 	getServerSettings() {
  199. 		return this._config.server?.settings;
  200. 	}
  202. 	/**
  203. 	 * Get the project's builderSettings configuration
  204. 	 *
  205. 	 * @private
  206. 	 * @returns {object} BuilderSettings configuration
  207. 	 */
  208. 	getBuilderSettings() {
  209. 		return this._config.builder?.settings;
  210. 	}
  212. 	/**
  213. 	 * Get the project's buildManifest configuration
  214. 	 *
  215. 	 * @private
  216. 	 * @returns {object|null} BuildManifest configuration or null if none is available
  217. 	 */
  218. 	getBuildManifest() {
  219. 		return this._buildManifest || null;
  220. 	}
  222. 	/* === Resource Access === */
  223. 	/**
  224. 	 * Get a [ReaderCollection]{@link @ui5/fs/ReaderCollection} for accessing all resources of the
  225. 	 * project in the specified "style":
  226. 	 *
  227. 	 * <ul>
  228. 	 * <li><b>buildtime:</b> Resource paths are always prefixed with <code>/resources/</code>
  229. 	 *  or <code>/test-resources/</code> followed by the project's namespace.
  230. 	 *  Any configured build-excludes are applied</li>
  231. 	 * <li><b>dist:</b> Resource paths always match with what the UI5 runtime expects.
  232. 	 *  This means that paths generally depend on the project type. Applications for example use a "flat"-like
  233. 	 *  structure, while libraries use a "buildtime"-like structure.
  234. 	 *  Any configured build-excludes are applied</li>
  235. 	 * <li><b>runtime:</b> Resource paths always match with what the UI5 runtime expects.
  236. 	 *  This means that paths generally depend on the project type. Applications for example use a "flat"-like
  237. 	 *  structure, while libraries use a "buildtime"-like structure.
  238. 	 *  This style is typically used for serving resources directly. Therefore, build-excludes are not applied
  239. 	 * <li><b>flat:</b> Resource paths are never prefixed and namespaces are omitted if possible. Note that
  240. 	 *  project types like "theme-library", which can have multiple namespaces, can't omit them.
  241. 	 *  Any configured build-excludes are applied</li>
  242. 	 * </ul>
  243. 	 *
  244. 	 * Resource readers always use POSIX-style paths.
  245. 	 *
  246. 	 * @public
  247. 	 * @param {object} [options]
  248. 	 * @param {string} [options.style=buildtime] Path style to access resources.
  249. 	 *   Can be "buildtime", "dist", "runtime" or "flat"
  250. 	 * @returns {@ui5/fs/ReaderCollection} Reader collection allowing access to all resources of the project
  251. 	 */
  252. 	getReader(options) {
  253. 		throw new Error(`getReader must be implemented by subclass ${this.constructor.name}`);
  254. 	}
  256. 	getResourceTagCollection() {
  257. 		if (!this._resourceTagCollection) {
  258. 			this._resourceTagCollection = new ResourceTagCollection({
  259. 				allowedTags: ["ui5:IsDebugVariant", "ui5:HasDebugVariant"],
  260. 				allowedNamespaces: ["project"],
  261. 				tags: this.getBuildManifest()?.tags
  262. 			});
  263. 		}
  264. 		return this._resourceTagCollection;
  265. 	}
  267. 	/**
  268. 	* Get a [DuplexCollection]{@link @ui5/fs/DuplexCollection} for accessing and modifying a
  269. 	* project's resources. This is always of style <code>buildtime</code>.
  270. 	*
  271. 	* @public
  272. 	* @returns {@ui5/fs/DuplexCollection} DuplexCollection
  273. 	*/
  274. 	getWorkspace() {
  275. 		throw new Error(`getWorkspace must be implemented by subclass ${this.constructor.name}`);
  276. 	}
  278. 	/* === Internals === */
  279. 	/**
  280. 	 * @private
  281. 	 * @param {object} config Configuration object
  282. 	*/
  283. 	async _configureAndValidatePaths(config) {}
  285. 	/**
  286. 	 * @private
  287. 	 * @param {object} config Configuration object
  288. 	*/
  289. 	async _parseConfiguration(config) {}
  290. }
  292. export default Project;