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