project/lib/specifications/SpecificationVersion.js

  1. import semver from "semver";
  3. const SPEC_VERSION_PATTERN = /^\d+\.\d+$/;
  4. const SUPPORTED_VERSIONS = [
  5. 	"0.1", "1.0", "1.1",
  6. 	"2.0", "2.1", "2.2", "2.3", "2.4", "2.5", "2.6",
  7. 	"3.0", "3.1", "3.2"
  8. ];
  10. /**
  11.  * Helper class representing a Specification Version. Featuring helper functions for easy comparison
  12.  * of versions.
  13.  *
  14.  * @public
  15.  * @class
  16.  * @alias @ui5/project/specifications/utils/SpecificationVersion
  17.  */
  18. class SpecificationVersion {
  19. 	#specVersion;
  20. 	#semverVersion;
  22. 	/**
  23. 	 * @public
  24. 	 * @param {string} specVersion Specification Version to use for all comparison operations
  25. 	 * @throws {Error} Throws if provided Specification Version is not supported by this version of @ui5/project
  26. 	 */
  27. 	constructor(specVersion) {
  28. 		this.#specVersion = specVersion;
  29. 		this.#semverVersion = getSemverCompatibleVersion(specVersion); // Throws for unsupported versions
  30. 	}
  32. 	/**
  33. 	 * Returns the Specification Version
  34. 	 *
  35. 	 * @public
  36. 	 * @returns {string} Specification Version
  37. 	 */
  38. 	toString() {
  39. 		return this.#specVersion;
  40. 	}
  42. 	/**
  43. 	 * Returns the major-version of the instance's Specification Version
  44. 	 *
  45. 	 * @public
  46. 	 * @returns {integer} Major version
  47. 	 */
  48. 	major() {
  49. 		return semver.major(this.#semverVersion);
  50. 	}
  52. 	/**
  53. 	 * Returns the minor-version of the instance's Specification Version
  54. 	 *
  55. 	 * @public
  56. 	 * @returns {integer} Minor version
  57. 	 */
  58. 	minor() {
  59. 		return semver.minor(this.#semverVersion);
  60. 	}
  62. 	/**
  63. 	 * Test whether the instance's Specification Version falls into the provided range
  64. 	 *
  65. 	 * @public
  66. 	 * @param {string} range [Semver]{@link https://www.npmjs.com/package/semver}-style version range,
  67. 	 * for example <code>2.2 - 2.4</code> or <code>=3.0</code>
  68. 	 * @returns {boolean} True if the instance's Specification Version falls into the provided range
  69. 	 */
  70. 	satisfies(range) {
  71. 		return semver.satisfies(this.#semverVersion, range);
  72. 	}
  74. 	/**
  75. 	 * Test whether the instance's Specification Version is greater than the provided test version
  76. 	 *
  77. 	 * @public
  78. 	 * @param {string} testVersion A Specification Version to compare the instance's Specification Version to
  79. 	 * @returns {boolean} True if the instance's Specification Version is greater than the provided version
  80. 	 */
  81. 	gt(testVersion) {
  82. 		return handleSemverComparator(semver.gt, this.#semverVersion, testVersion);
  83. 	}
  85. 	/**
  86. 	 * Test whether the instance's Specification Version is greater than or equal to the provided test version
  87. 	 *
  88. 	 * @public
  89. 	 * @param {string} testVersion A Specification Version to compare the instance's Specification Version to
  90. 	 * @returns {boolean} True if the instance's Specification Version is greater than or equal to the provided version
  91. 	 */
  92. 	gte(testVersion) {
  93. 		return handleSemverComparator(semver.gte, this.#semverVersion, testVersion);
  94. 	}
  96. 	/**
  97. 	 * Test whether the instance's Specification Version is smaller than the provided test version
  98. 	 *
  99. 	 * @public
  100. 	 * @param {string} testVersion A Specification Version to compare the instance's Specification Version to
  101. 	 * @returns {boolean} True if the instance's Specification Version is smaller than the provided version
  102. 	 */
  103. 	lt(testVersion) {
  104. 		return handleSemverComparator(semver.lt, this.#semverVersion, testVersion);
  105. 	}
  107. 	/**
  108. 	 * Test whether the instance's Specification Version is smaller than or equal to the provided test version
  109. 	 *
  110. 	 * @public
  111. 	 * @param {string} testVersion A Specification Version to compare the instance's Specification Version to
  112. 	 * @returns {boolean} True if the instance's Specification Version is smaller than or equal to the provided version
  113. 	 */
  114. 	lte(testVersion) {
  115. 		return handleSemverComparator(semver.lte, this.#semverVersion, testVersion);
  116. 	}
  118. 	/**
  119. 	 * Test whether the instance's Specification Version is equal to the provided test version
  120. 	 *
  121. 	 * @public
  122. 	 * @param {string} testVersion A Specification Version to compare the instance's Specification Version to
  123. 	 * @returns {boolean} True if the instance's Specification Version is equal to the provided version
  124. 	 */
  125. 	eq(testVersion) {
  126. 		return handleSemverComparator(semver.eq, this.#semverVersion, testVersion);
  127. 	}
  129. 	/**
  130. 	 * Test whether the instance's Specification Version is not equal to the provided test version
  131. 	 *
  132. 	 * @public
  133. 	 * @param {string} testVersion A Specification Version to compare the instance's Specification Version to
  134. 	 * @returns {boolean} True if the instance's Specification Version is not equal to the provided version
  135. 	 */
  136. 	neq(testVersion) {
  137. 		return handleSemverComparator(semver.neq, this.#semverVersion, testVersion);
  138. 	}
  140. 	/**
  141. 	 * Test whether the provided Specification Version is supported by this version of @ui5/project
  142. 	 *
  143. 	 * @public
  144. 	 * @param {string} testVersion A Specification Version to compare the instance's Specification Version to
  145. 	 * @returns {boolean} True if the provided Specification Version is supported
  146. 	 */
  147. 	static isSupportedSpecVersion(testVersion) {
  148. 		return SUPPORTED_VERSIONS.includes(testVersion);
  149. 	}
  151. 	/**
  152. 	 * Returns the major-version of the provided Specification Version
  153. 	 *
  154. 	 * @public
  155. 	 * @param {string} specVersion Specification Version
  156. 	 * @returns {integer} Major version
  157. 	 */
  158. 	static major(specVersion) {
  159. 		const comparator = new SpecificationVersion(specVersion);
  160. 		return comparator.major();
  161. 	}
  163. 	/**
  164. 	 * Returns the minor-version of the provided Specification Version
  165. 	 *
  166. 	 * @public
  167. 	 * @param {string} specVersion Specification Version
  168. 	 * @returns {integer} Minor version
  169. 	 */
  170. 	static minor(specVersion) {
  171. 		const comparator = new SpecificationVersion(specVersion);
  172. 		return comparator.minor();
  173. 	}
  175. 	/**
  176. 	 * Test whether the provided Specification Version falls into the provided range
  177. 	 *
  178. 	 * @public
  179. 	 * @param {string} specVersion Specification Version
  180. 	 * @param {string} range [Semver]{@link https://www.npmjs.com/package/semver}-style version range,
  181. 	 * for example <code>2.2 - 2.4</code>
  182. 	 * @returns {boolean} True if the provided Specification Version falls into the provided range
  183. 	 */
  184. 	static satisfies(specVersion, range) {
  185. 		const comparator = new SpecificationVersion(specVersion);
  186. 		return comparator.satisfies(range);
  187. 	}
  189. 	/**
  190. 	 * Test whether the provided Specification Version is greater than the provided test version
  191. 	 *
  192. 	 * @public
  193. 	 * @param {string} specVersion Specification Version
  194. 	 * @param {string} testVersion A Specification Version to compare the provided Specification Version to
  195. 	 * @returns {boolean} True if the provided Specification Version is greater than the provided version
  196. 	 */
  197. 	static gt(specVersion, testVersion) {
  198. 		const comparator = new SpecificationVersion(specVersion);
  199. 		return comparator.gt(testVersion);
  200. 	}
  202. 	/**
  203. 	 * Test whether the provided Specification Version is greater than or equal to the provided test version
  204. 	 *
  205. 	 * @public
  206. 	 * @param {string} specVersion Specification Version
  207. 	 * @param {string} testVersion A Specification Version to compare the provided Specification Version to
  208. 	 * @returns {boolean} True if the provided Specification Version is greater than or equal to the provided version
  209. 	 */
  210. 	static gte(specVersion, testVersion) {
  211. 		const comparator = new SpecificationVersion(specVersion);
  212. 		return comparator.gte(testVersion);
  213. 	}
  215. 	/**
  216. 	 * Test whether the provided Specification Version is smaller than the provided test version
  217. 	 *
  218. 	 * @public
  219. 	 * @param {string} specVersion Specification Version
  220. 	 * @param {string} testVersion A Specification Version to compare the provided Specification Version to
  221. 	 * @returns {boolean} True if the provided Specification Version is smaller than the provided version
  222. 	 */
  223. 	static lt(specVersion, testVersion) {
  224. 		const comparator = new SpecificationVersion(specVersion);
  225. 		return comparator.lt(testVersion);
  226. 	}
  228. 	/**
  229. 	 * Test whether the provided Specification Version is smaller than or equal to the provided test version
  230. 	 *
  231. 	 * @public
  232. 	 * @param {string} specVersion Specification Version
  233. 	 * @param {string} testVersion A Specification Version to compare the provided Specification Version to
  234. 	 * @returns {boolean} True if the provided Specification Version is smaller than or equal to the provided version
  235. 	 */
  236. 	static lte(specVersion, testVersion) {
  237. 		const comparator = new SpecificationVersion(specVersion);
  238. 		return comparator.lte(testVersion);
  239. 	}
  241. 	/**
  242. 	 * Test whether the provided Specification Version is equal to the provided test version
  243. 	 *
  244. 	 * @public
  245. 	 * @param {string} specVersion Specification Version
  246. 	 * @param {string} testVersion A Specification Version to compare the provided Specification Version to
  247. 	 * @returns {boolean} True if the provided Specification Version is equal to the provided version
  248. 	 */
  249. 	static eq(specVersion, testVersion) {
  250. 		const comparator = new SpecificationVersion(specVersion);
  251. 		return comparator.eq(testVersion);
  252. 	}
  254. 	/**
  255. 	 * Test whether the provided Specification Version is not equal to the provided test version
  256. 	 *
  257. 	 * @public
  258. 	 * @param {string} specVersion Specification Version
  259. 	 * @param {string} testVersion A Specification Version to compare the provided Specification Version to
  260. 	 * @returns {boolean} True if the provided Specification Version is not equal to the provided version
  261. 	 */
  262. 	static neq(specVersion, testVersion) {
  263. 		const comparator = new SpecificationVersion(specVersion);
  264. 		return comparator.neq(testVersion);
  265. 	}
  267. 	/**
  268. 	 * Creates an array of Specification Versions that match with the provided range. This is mainly used
  269. 	 * for testing purposes. I.e. to execute identical tests for a range of specification versions.
  270. 	 *
  271. 	 * @public
  272. 	 * @param {string} range [Semver]{@link https://www.npmjs.com/package/semver}-style version range,
  273. 	 * for example <code>2.2 - 2.4</code> or <code>=3.0</code>
  274. 	 * @returns {string[]} Array of versions that match the specified range
  275. 	 */
  276. 	static getVersionsForRange(range) {
  277. 		return SUPPORTED_VERSIONS.filter((specVersion) => {
  278. 			const comparator = new SpecificationVersion(specVersion);
  279. 			return comparator.satisfies(range);
  280. 		});
  281. 	}
  282. }
  284. function getUnsupportedSpecVersionMessage(specVersion) {
  285. 	return `Unsupported Specification Version ${specVersion} defined. Your UI5 CLI installation might be outdated. ` +
  286. 		`For details, see https://sap.github.io/ui5-tooling/pages/Configuration/#specification-versions`;
  287. }
  289. function getSemverCompatibleVersion(specVersion) {
  290. 	if (SpecificationVersion.isSupportedSpecVersion(specVersion)) {
  291. 		return specVersion + ".0";
  292. 	}
  293. 	throw new Error(getUnsupportedSpecVersionMessage(specVersion));
  294. }
  296. function handleSemverComparator(comparator, baseVersion, testVersion) {
  297. 	if (SPEC_VERSION_PATTERN.test(testVersion)) {
  298. 		const a = baseVersion;
  299. 		const b = testVersion + ".0";
  300. 		return comparator(a, b);
  301. 	}
  302. 	throw new Error("Invalid spec version expectation given in comparator: " + testVersion);
  303. }
  305. export default SpecificationVersion;
  307. // Export local function for testing only
  308. export const __localFunctions__ = (process.env.NODE_ENV === "test") ?
  309. 	{getSemverCompatibleVersion, handleSemverComparator} : /* istanbul ignore next */ undefined;