0
# semver-diff
1

2
Get the diff type of two [semver](https://github.com/npm/node-semver) versions: `0.0.1 0.0.2` → `patch`. This package provides a simple utility function for determining the semantic version difference type between two semver versions.
3

4
**Note:** This package is built on top of the [semver](https://github.com/npm/node-semver) library and uses its parsing and comparison logic.
5

6
## Package Information
7

8
- **Package Name**: semver-diff
9
- **Package Type**: npm
10
- **Language**: JavaScript (ES Module with TypeScript definitions)
11
- **Installation**: `npm install semver-diff`
12
- **Node.js**: Requires Node.js >=12
13

14
## Core Imports
15

16
```javascript
17
import semverDiff from 'semver-diff';
18
```
19

20
With TypeScript type definitions:
21

22
```typescript
23
import semverDiff, { Difference } from 'semver-diff';
24
```
25

26
For CommonJS:
27

28
```javascript
29
const semverDiff = require('semver-diff');
30
```
31

32
## Basic Usage
33

34
```javascript
35
import semverDiff from 'semver-diff';
36

37
// Basic version comparisons
38
semverDiff('1.1.1', '1.1.2');
39
//=> 'patch'
40

41
semverDiff('0.0.1', '1.0.0');
42
//=> 'major'
43

44
semverDiff('0.0.1', '0.1.0');
45
//=> 'minor'
46

47
// Returns undefined if versions are identical or second is lower
48
semverDiff('0.0.1', '0.0.1');
49
//=> undefined
50

51
semverDiff('0.0.2', '0.0.1');
52
//=> undefined
53
```
54

55
## Capabilities
56

57
### Version Difference Detection
58

59
Determines the type of difference between two semantic version strings.
60

61
```javascript { .api }
62
/**
63
 * Get the diff type of two semver versions
64
 * @param versionA - First version string
65
 * @param versionB - Second version string  
66
 * @returns The difference type between versions, or undefined if identical or second is lower
67
 */
68
function semverDiff(versionA: string, versionB: string): Difference | undefined;
69
```
70

71
**Parameters:**
72
- `versionA` (string): First version to compare
73
- `versionB` (string): Second version to compare
74

75
**Returns:** `Difference | undefined`
76
- Returns the difference type if `versionB` is higher than `versionA`
77
- Returns `undefined` if versions are identical or `versionB` is lower than `versionA`
78
- For build metadata: Uses semver build comparison logic where build metadata is compared lexically
79

80
**Usage Examples:**
81

82
```javascript
83
import semverDiff from 'semver-diff';
84

85
// Major version changes
86
semverDiff('0.0.1', '1.0.0');          //=> 'major'
87
semverDiff('0.0.1-foo', '1.0.0');      //=> 'premajor'
88

89
// Minor version changes  
90
semverDiff('0.0.1', '0.1.0');          //=> 'minor'
91
semverDiff('0.0.1-foo', '0.1.0');      //=> 'preminor'
92

93
// Patch version changes
94
semverDiff('0.0.1', '0.0.2');          //=> 'patch'
95
semverDiff('1.1.1-foo', '1.1.2');      //=> 'prepatch'
96

97
// Prerelease changes
98
semverDiff('0.0.1-foo', '0.0.1-foo.bar'); //=> 'prerelease'
99

100
// Build metadata changes
101
semverDiff('0.1.0', '0.1.0+foo');      //=> 'build'
102
semverDiff('0.0.1+1', '0.0.1+2');      //=> 'build'
103

104
// Complex build metadata comparison behavior
105
semverDiff('0.0.1+0', '0.0.1');        //=> undefined (build to no-build)
106
semverDiff('0.0.1+2', '0.0.1+2');      //=> undefined (identical)
107
semverDiff('0.0.1+3', '0.0.1+2');      //=> undefined (build metadata downgrade)
108
semverDiff('0.0.1+2', '0.0.1+2.0');    //=> 'build'
109
semverDiff('0.0.1+2.0', '0.0.1+2');    //=> undefined (downgrade)
110
semverDiff('0.0.1+2.a', '0.0.1+2.0');  //=> undefined (downgrade)
111
semverDiff('0.0.1+2.0', '0.0.1+2.a');  //=> 'build'
112

113
// No difference cases
114
semverDiff('0.0.1', '0.0.1');          //=> undefined
115
semverDiff('0.0.2', '0.0.1');          //=> undefined (downgrade)
116
```
117

118
## Types
119

120
```typescript { .api }
121
/**
122
 * Union type defining all possible semver difference types
123
 */
124
type Difference = 
125
  | 'major'        // Major version increase (1.0.0 → 2.0.0)
126
  | 'premajor'     // Major version increase from prerelease (1.0.0-alpha → 2.0.0)
127
  | 'minor'        // Minor version increase (1.0.0 → 1.1.0)  
128
  | 'preminor'     // Minor version increase from prerelease (1.0.0-alpha → 1.1.0)
129
  | 'patch'        // Patch version increase (1.0.0 → 1.0.1)
130
  | 'prepatch'     // Patch version increase from prerelease (1.0.0-alpha → 1.0.1)
131
  | 'prerelease'   // Prerelease version change (1.0.0-alpha → 1.0.0-beta)
132
  | 'build';       // Build metadata change (1.0.0 → 1.0.0+build.1)
133
```