@magic/semver 0.0.19 → 0.0.20

package/README.md

@@ -37,13 +37,173 @@ const version = '0.0.1-alpha.0'
 
 const parsed = semver.parse(version)
 
-// parsed === { major: 0, minor: 0, patch: 1, demo: { string: 'alpha', version: 0 } }
+// parsed === { major: 0, minor: 0, patch: 1, demo: { string: 'alpha', version: 0 }, v: '0.0.1-alpha.0' }
 
 const serialized = semver.serialize(parsed)
 
 // version === serialized
 ```
 
+## API
+
+### parse(version)
+
+Parses a semver string into a `VersionResult` object.
+
+**Parameters:**
+
+- `version` (string): A semantic version string (e.g., `"1.2.3"`, `"1.2.3-alpha.0"`, `"v1.2.3"`)
+
+**Returns:** `VersionResult` — An object with `major`, `minor`, `patch`, `demo`, and `v` properties.
+
+```javascript
+semver.parse('1.2.3')
+// { major: 1, minor: 2, patch: 3, v: '1.2.3' }
+
+semver.parse('1.2.3-alpha.0')
+// { major: 1, minor: 2, patch: 3, demo: { string: 'alpha', version: 0 }, v: '1.2.3-alpha.0' }
+
+semver.parse('v1.2.3')
+// { major: 1, minor: 2, patch: 3, v: 'v1.2.3' }
+```
+
+### serialize(version)
+
+**Aliases:** `stringify`
+
+Converts a `Version` object back into a semver string.
+
+**Parameters:**
+
+- `version` (Version): An object with `major`, `minor`, and `patch` properties. Optional `demo` property for pre-release versions.
+
+**Returns:** (string): The serialized semver string.
+
+```javascript
+semver.serialize({ major: 1, minor: 2, patch: 3 })
+// '1.2.3'
+
+semver.serialize({ major: 1, minor: 2, patch: 3, demo: { string: 'alpha', version: 0 } })
+// '1.2.3-alpha.0'
+```
+
+### isSemver(value)
+
+Type guard that checks if a value is a valid semver (either a string or object).
+
+**Parameters:**
+
+- `value` (unknown): The value to check.
+
+**Returns:** (boolean): `true` if the value is a valid semver string or object.
+
+```javascript
+semver.isSemver('1.2.3') // true
+semver.isSemver('1.2.3-alpha.0') // true
+semver.isSemver({ major: 1, minor: 2, patch: 3 }) // true
+semver.isSemver('not-a-version') // false
+semver.isSemver(123) // false
+```
+
+### bump(version, options)
+
+Increments a semver version. Returns a string if input was a string, or a `Version` object if input was an object.
+
+**Parameters:**
+
+- `version` (string | Version): The version to bump.
+- `options` (object):
+  - `options.major` (boolean): Bump major version, resets minor and patch.
+  - `options.minor` (boolean): Bump minor version, resets patch.
+  - `options.patch` (boolean): Bump patch version.
+  - `options.alpha` (boolean): Set or increment alpha pre-release.
+  - `options.beta` (boolean): Set or increment beta pre-release.
+
+**Returns:** (string | Version): The bumped version in the same format as input.
+
+```javascript
+semver.bump('1.2.3', { major: true }) // '2.0.0'
+semver.bump('1.2.3', { minor: true }) // '1.3.0'
+semver.bump('1.2.3', { patch: true }) // '1.2.4'
+semver.bump('1.2.3', { alpha: true }) // '1.2.4-alpha.0'
+semver.bump('1.2.3-alpha.0', { alpha: true }) // '1.2.3-alpha.1'
+semver.bump('1.2.3-alpha.0', { beta: true }) // '1.2.3-beta.0'
+semver.bump('1.2.3', { beta: true }) // '1.2.4-beta.0'
+
+// No options: increments alpha version if present, otherwise patch
+semver.bump('1.2.3-alpha.0') // '1.2.3-alpha.1'
+semver.bump('1.2.3') // '1.2.4'
+```
+
+### isBigger(a, b)
+
+Compares two versions. Returns `true` if `a` is greater than `b`.
+
+**Parameters:**
+
+- `a` (string): First version string.
+- `b` (string): Second version string.
+
+**Returns:** (boolean): `true` if `a > b`.
+
+```javascript
+semver.isBigger('2.0.0', '1.0.0') // true
+semver.isBigger('1.0.0', '1.0.0') // false
+semver.isBigger('1.0.0-alpha', '1.0.0') // false (release > pre-release)
+semver.isBigger('1.0.0-beta', '1.0.0-alpha') // true (beta > alpha)
+```
+
+### isSmaller(a, b)
+
+Compares two versions. Returns `true` if `a` is less than `b`.
+
+**Parameters:**
+
+- `a` (string): First version string.
+- `b` (string): Second version string.
+
+**Returns:** (boolean): `true` if `a < b`.
+
+```javascript
+semver.isSmaller('1.0.0', '2.0.0') // true
+semver.isSmaller('1.0.0', '1.0.0') // false
+semver.isSmaller('1.0.0-alpha', '1.0.0') // true (pre-release < release)
+```
+
+### sort(versions)
+
+Sorts an array of versions in ascending order according to semver spec (pre-releases come before releases, alpha < beta).
+
+**Parameters:**
+
+- `versions` (Array<string | Version>): An array of version strings or objects.
+
+**Returns:** (Array<string | Version>): The sorted array, preserving input types.
+
+```javascript
+semver.sort(['1.0.0', '2.0.0-alpha', '1.0.0-alpha.0', '2.0.0'])
+// ['1.0.0-alpha.0', '1.0.0', '2.0.0-alpha', '2.0.0']
+
+semver.sort(['1.2.3', '1.2.0', '1.3.0'])
+// ['1.2.0', '1.2.3', '1.3.0']
+```
+
+## Types
+
+```typescript
+type Version = {
+  major: number
+  minor: number
+  patch: number
+  demo?: {
+    string: string // 'alpha' or 'beta'
+    version: number
+  }
+}
+
+type VersionResult = Version & { v: string }
+```
+
 ##### changelog
 
 ##### 0.0.1
@@ -126,6 +286,12 @@ update dependencies
 
 - better type exports
 
-##### 0.0.20 - unreleased
+##### 0.0.20
+
+- add sort function, sorts arrays of versions
+- add documentation to README.md
+- update dependencies
+
+##### 0.0.21 - unreleased
 
 ...

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magic/semver",
-  "version": "0.0.19",
+  "version": "0.0.20",
   "author": "Wizards & Witches",
   "description": "semantic version parsing and serialization.",
   "license": "AGPL-3.0",
@@ -37,8 +37,8 @@
     "url": "https://github.com/magic/semver/issues"
   },
   "dependencies": {
-    "@magic/error": "0.0.21",
-    "@magic/types": "0.1.31"
+    "@magic/error": "0.0.23",
+    "@magic/types": "0.1.37"
   },
   "devDependencies": {
     "@magic-modules/git-badges": "0.0.12",
@@ -46,10 +46,10 @@
     "@magic-modules/no-spy": "0.0.9",
     "@magic-modules/pre": "0.0.12",
     "@magic-themes/docs": "0.0.15",
-    "@magic/core": "0.0.156",
-    "@magic/format": "0.0.69",
-    "@magic/test": "0.2.28",
-    "typescript": "5.9.3"
+    "@magic/core": "0.0.158",
+    "@magic/format": "0.0.73",
+    "@magic/test": "0.3.12",
+    "typescript": "6.0.3"
   },
   "files": [
     "src",

package/src/sort.js

@@ -0,0 +1,77 @@
+import is from '@magic/types'
+import { parse } from './parse.js'
+
+/**
+ * Compares pre-release identifiers according to semver rules
+ * @private
+ * @param {import('./types.js').Version['demo']} a
+ * @param {import('./types.js').Version['demo']} b
+ * @returns {number}
+ */
+const comparePreRelease = (a, b) => {
+  if (!a && !b) {
+    return 0
+  }
+  if (!a) {
+    return -1
+  }
+  if (!b) {
+    return 1
+  }
+
+  // First compare the string identifiers (alpha, beta, etc)
+  if (a.string < b.string) {
+    return -1
+  }
+  if (a.string > b.string) {
+    return 1
+  }
+
+  // If strings are same, compare version numbers
+  return a.version - b.version
+}
+
+/**
+ * Sorts versions according to semver spec
+ * @param {(import('./types.js').Version | string)[]} versions
+ * @returns {import('./types.js').Version[]}
+ */
+export const sort = versions => {
+  return /** @type {import('./types.js').Version[]} */ (
+    versions
+      .map(
+        v =>
+          /** @type {[string | import('./types.js').Version, import('./types.js').Version]} */ ([
+            v,
+            is.str(v) ? parse(v) : v,
+          ]),
+      )
+      .sort(([, a], [, b]) => {
+        if (a.major !== b.major) {
+          return a.major - b.major
+        }
+        if (a.minor !== b.minor) {
+          return a.minor - b.minor
+        }
+        if (a.patch !== b.patch) {
+          return a.patch - b.patch
+        }
+
+        const hasPreA = !!a.demo
+        const hasPreB = !!b.demo
+
+        if (hasPreA && !hasPreB) {
+          return -1
+        }
+        if (!hasPreA && hasPreB) {
+          return 1
+        }
+        if (hasPreA && hasPreB) {
+          return comparePreRelease(a.demo, b.demo)
+        }
+
+        return 0
+      })
+      .map(([original]) => original)
+  )
+}

package/types/sort.d.ts

@@ -0,0 +1,3 @@
+export function sort(
+  versions: (import('./types.js').Version | string)[],
+): import('./types.js').Version[]