@magic/semver 0.0.18 → 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
@@ -122,6 +282,16 @@ update dependencies
 
 - fix handling a v in front of the version, eg v0.0.1
 
-##### 0.0.19 - unreleased
+##### 0.0.19
+
+- better type exports
+
+##### 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.18",
+  "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/bump.js

@@ -7,10 +7,6 @@ import { isSemver } from './isSemver.js'
 
 const libName = '@magic/semver.bump'
 
-/**
- *  @typedef {import('./types.js').Version} Version
- */
-
 /**
  * @param {string} v
  * @param {object} options
@@ -19,14 +15,14 @@ const libName = '@magic/semver.bump'
  * @param {boolean} [options.patch]
  * @param {boolean} [options.beta]
  * @param {boolean} [options.alpha]
- * @returns {Version | string}
+ * @returns {import('./types.js').Version | string}
  */
 export const bump = (v, options = {}) => {
   if (is.empty(v)) {
     throw error(`${libName} expects arguments to be non-empty`, 'E_VERSION_EMPTY')
   }
 
-  /** @type {Partial<Version> } */
+  /** @type {Partial<import('./types.js').Version> } */
   let version
 
   const isString = is.string(v)

package/src/index.js

@@ -12,6 +12,9 @@ export const parse = p
 export const stringify = s
 export const serialize = s
 
+/** @typedef {import('./types.js').Version} Version */
+/** @typedef {import('./types.js').VersionResult} VersionResult */
+
 export default {
   bump,
   isBigger,

package/src/isSemver.js

@@ -3,12 +3,8 @@ import { parse } from './parse.js'
 import { serialize } from './serialize.js'
 
 /**
- * @typedef {import('./types.js').Version} Version
- */
-
-/**
- * @param {Version | string | unknown} v
- * @returns {v is Version}
+ * @param {import('./types.js').Version | string | unknown} v
+ * @returns {v is import('./types.js').Version}
  *
  */
 export const isSemver = v => {

package/src/parse.js

@@ -3,14 +3,9 @@ import error from '@magic/error'
 
 const libName = `@magic/semver.parse:`
 
-/**
- * @typedef {import('./types.js').Version} Version
- * @typedef {import('./types.js').VersionResult} VersionResult
- */
-
 /**
  * @param {string} v
- * @returns {VersionResult}
+ * @returns {import('./types.js').VersionResult}
  */
 export const parse = v => {
   if (is.empty(v)) {
@@ -27,7 +22,7 @@ export const parse = v => {
 
   const [major, minor, patch, demo] = v.split('.')
 
-  /** @type {VersionResult} */
+  /** @type {import('./types.js').VersionResult} */
   const result = {
     major: parseInt(major.replace('v', '')),
     minor: parseInt(minor),

package/src/serialize.js

@@ -4,11 +4,7 @@ import error from '@magic/error'
 const libName = `@magic/semver.serialize:`
 
 /**
- *  @typedef {import('./types.js').Version} Version
- */
-
-/**
- * @param {Version | unknown} v
+ * @param {import('./types.js').Version | unknown} v
  * @returns {string}
  */
 export const serialize = v => {

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/bump.d.ts

@@ -7,5 +7,4 @@ export function bump(
     beta?: boolean | undefined
     alpha?: boolean | undefined
   },
-): Version | string
-export type Version = import('./types.js').Version
+): import('./types.js').Version | string

package/types/index.d.ts

@@ -7,13 +7,15 @@ export const bump: (
     beta?: boolean | undefined
     alpha?: boolean | undefined
   },
-) => Version | string
+) => import('./types.js').Version | string
 export const isBigger: (a: string, b: string) => boolean
-export const isSemver: (v: Version | string | unknown) => v is Version
+export const isSemver: (
+  v: import('./types.js').Version | string | unknown,
+) => v is import('./types.js').Version
 export const isSmaller: (a: string, b: string) => boolean
-export const parse: (v: string) => VersionResult
-export const stringify: (v: Version | unknown) => string
-export const serialize: (v: Version | unknown) => string
+export const parse: (v: string) => import('./types.js').VersionResult
+export const stringify: (v: import('./types.js').Version | unknown) => string
+export const serialize: (v: import('./types.js').Version | unknown) => string
 declare namespace _default {
   export { bump }
   export { isBigger }
@@ -24,3 +26,5 @@ declare namespace _default {
   export { stringify }
 }
 export default _default
+export type Version = import('./types.js').Version
+export type VersionResult = import('./types.js').VersionResult

package/types/isSemver.d.ts

@@ -1,2 +1,3 @@
-export function isSemver(v: Version | string | unknown): v is Version
-export type Version = import('./types.js').Version
+export function isSemver(
+  v: import('./types.js').Version | string | unknown,
+): v is import('./types.js').Version

package/types/parse.d.ts

@@ -1,3 +1 @@
-export function parse(v: string): VersionResult
-export type Version = import('./types.js').Version
-export type VersionResult = import('./types.js').VersionResult
+export function parse(v: string): import('./types.js').VersionResult

package/types/serialize.d.ts

@@ -1,2 +1 @@
-export function serialize(v: Version | unknown): string
-export type Version = import('./types.js').Version
+export function serialize(v: import('./types.js').Version | unknown): string

package/types/sort.d.ts

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