Whether one version satisfies one range
Version 1.2.3 against the range ^1.2.0 returns a match. The caret (^) range allows any version that doesn't change the leftmost non-zero digit -- so ^1.2.0 permits anything from 1.2.0 up to (but not including) 2.0.0, and 1.2.3 falls comfortably within that window.
This distinction matters in practice: ^1.2.0 would also match 1.5.0 or 1.9.9 (since the major version stays 1), but would not match 2.0.0 (a major version bump) or 1.1.9 (a version below the specified minimum) -- caret ranges are designed to allow the backward-compatible updates that semantic versioning promises within a major version.
This is exactly the kind of check package managers (npm, yarn) run internally when resolving whether an installed or available package version satisfies what's declared in a package.json dependency range -- this tool exposes that same logic for manual checking.
What this simplified matcher does and doesn't parse
Simple ^ ~ >= and exact. Hyphen ranges and || unions are not parsed. This handles the most common range types: caret (^) ranges, tilde (~) ranges (which allow only patch-level updates within a minor version), greater-than-or-equal (>=), and exact version matches -- covering the large majority of range syntax actually used in real package.json files.
Full semver range syntax also supports hyphen ranges (like 1.2.3 - 2.3.4, an explicit inclusive range) and OR unions (like 1.2.7 || >=1.2.9 <2.0.0, matching either sub-range) -- neither of which this simplified matcher parses, so a range using that syntax would need a full semver library to evaluate correctly.
Pre-release versions (like 1.2.3-beta.1) follow additional semver comparison rules beyond simple numeric comparison, which can behave differently across range types -- verify pre-release version matching specifically if that applies to your use case.
Related dependency and version tools
For cleaning up and pinning the actual dependency ranges in a package.json file (rather than checking one version against one range), the Package.json Dependency Cleaner handles that directly.
Frequently Asked Questions (FAQ)
Why does 1.2.3 match ^1.2.0?
A caret range like ^1.2.0 permits any version from 1.2.0 up to (but not including) the next major version, 2.0.0. Since 1.2.3 keeps the same major version (1) and is greater than or equal to 1.2.0, it satisfies the range.
What's the difference between a caret (^) range and a tilde (~) range?
A caret range (^1.2.0) allows updates that don't change the leftmost non-zero version digit (so up to but not including 2.0.0). A tilde range (~1.2.0) is more restrictive, allowing only patch-level updates within the same minor version (so up to but not including 1.3.0).
Does this parse hyphen ranges or || (OR) unions?
No. Simple ^ ~ >= and exact. Hyphen ranges and || unions are not parsed. Explicit hyphen ranges (like 1.2.3 - 2.3.4) and OR-combined ranges (like 1.2.7 || >=1.2.9 <2.0.0) require a full semver parsing library, which this simplified matcher doesn't implement.
Is this the same logic npm or yarn uses to resolve dependencies?
Conceptually yes for the range types it covers -- caret, tilde, >=, and exact matches follow the same semantic versioning rules package managers use. For the full range syntax package managers support, a complete semver library would be needed rather than this simplified tool.
Does this handle pre-release versions like 1.2.3-beta.1 correctly?
Pre-release versions follow additional comparison rules in the full semver specification that can behave differently across range types -- verify this specifically if your use case involves pre-release versions, since this simplified matcher may not capture every nuance of those rules.
