@glion/util-semver 0.15.1 → 0.15.2

package/README.md

@@ -1,31 +1,31 @@
 # @glion/util-semver
 
-A tiny, fast, and secure version utility for HL7v2-like version strings. Intentionally simplified for our ecosystem while maintaining excellent performance and type safety.
+Parser, comparators, and range matcher for HL7v2-style numeric version strings.
 
-## Features
+## What it does
 
-✨ **Simple & Elegant** - Clean API, no unnecessary complexity
-⚡ **High Performance** - O(n) algorithms, Range caching for hot paths
-🔒 **Secure** - ReDoS protection, integer overflow guards
-📘 **Type Safe** - Full TypeScript support with structured errors
-🪶 **Tiny** - ~6KB, zero dependencies
+Parses, compares, and matches HL7v2 versions like `2.5.1` or `2.3`. Supports the `=`, `<`, `<=`, `>`, `>=` comparators and AND-combined ranges (`">=2.0 <3.0"`), plus helpers for sorting, increment, diff, and finding max/min versions that satisfy a range. Intentionally narrower than full semver: no prerelease, build metadata, wildcards, or `^`/`~` operators. Versions are capped at int32 and input lengths are bounded to protect against malformed input.
 
-## Installation
+## Install
 
 ```bash
 npm install @glion/util-semver
 ```
 
-## Quick Start
+## Use
 
 ```typescript
 import {
   parse,
   clean,
+  valid,
   compare,
+  eq,
+  gt,
   satisfies,
   sort,
   maxSatisfying,
+  minSatisfying,
   increment,
   diff,
   Range,
@@ -37,11 +37,11 @@ clean("2"); // "2.0.0"
 valid("2.5.1"); // true
 
 // Compare versions
-compare("2.3.1", "2.4"); // -1 (less than)
+compare("2.3.1", "2.4"); // -1
 eq("2.5.0", "2.5"); // true
 gt("2.5.1", "2.5.0"); // true
 
-// Version ranges
+// Ranges
 satisfies("2.5.1", ">=2.0 <3.0"); // true
 satisfies("2.5.1", "2.5.1"); // true (exact match)
 
@@ -50,14 +50,14 @@ sort(["2.5", "2.3.1", "2.10"]); // ["2.3.1", "2.5", "2.10"]
 maxSatisfying(["2.3", "2.5", "3.0"], ">=2.0 <3.0"); // "2.5"
 minSatisfying(["2.3", "2.5", "3.0"], ">=2.0 <3.0"); // "2.3"
 
-// Version manipulation
+// Manipulation
 increment("2.5.1", "minor"); // "2.6.0"
 diff("2.5.1", "2.6.0"); // "minor"
 ```
 
-## API Reference
+## API
 
-### Parsing & Validation
+### Parsing and validation
 
 #### `parse(version: string): Hl7Version`
 
@@ -69,11 +69,11 @@ parse("2.3"); // { major: 2, minor: 3, patch: 0 }
 parse("2"); // { major: 2, minor: 0, patch: 0 }
 ```
 
-**Throws:** `VersionParseError` if invalid format
+Throws `VersionParseError` if the format is invalid.
 
 #### `clean(version: string): string`
 
-Converts a version to canonical format (major.minor.patch).
+Converts a version to canonical `major.minor.patch` format.
 
 ```typescript
 clean("2"); // "2.0.0"
@@ -81,7 +81,7 @@ clean("2.5"); // "2.5.0"
 clean(" 2.5 "); // "2.5.0"
 ```
 
-**Throws:** `VersionParseError` if invalid format
+Throws `VersionParseError` if the format is invalid.
 
 #### `valid(version: string): boolean`
 
@@ -105,13 +105,13 @@ compare("2.5.1", "2.5.1"); // 0  (a = b)
 compare("2.6", "2.5.9"); // 1  (a > b)
 ```
 
-#### Comparison Operators
+#### Comparison operators
 
-- `eq(a, b)` - Equal to
-- `lt(a, b)` - Less than
-- `lte(a, b)` - Less than or equal
-- `gt(a, b)` - Greater than
-- `gte(a, b)` - Greater than or equal
+- `eq(a, b)` — equal to
+- `lt(a, b)` — less than
+- `lte(a, b)` — less than or equal
+- `gt(a, b)` — greater than
+- `gte(a, b)` — greater than or equal
 
 ```typescript
 eq("2.5.0", "2.5"); // true
@@ -119,35 +119,21 @@ lt("2.3", "2.4"); // true
 gte("2.5.1", "2.5"); // true
 ```
 
-### Range Matching
+### Range matching
 
 #### `satisfies(version, range): boolean`
 
 Checks if a version satisfies a range expression.
 
-**Range Syntax:**
-
-- Operators: `=`, `<`, `<=`, `>`, `>=`
-- Multiple comparators: Space-separated (AND logic)
-- Default operator: `=` (exact match)
-
 ```typescript
 satisfies("2.5.1", ">=2.0 <3.0"); // true
 satisfies("2.5.1", "2.5.1"); // true (exact match)
 satisfies("2.5.1", ">=2.6"); // false
 ```
 
-**Performance Tip:** Use `Range` objects for repeated checks:
+For repeated checks, use a `Range` object to avoid re-parsing:
 
 ```typescript
-// Slow: Parse range every time
-for (const version of versions) {
-  if (satisfies(version, ">=2.0 <3.0")) {
-    /* ... */
-  }
-}
-
-// Fast: Parse once, reuse many times
 const range = new Range(">=2.0 <3.0");
 for (const version of versions) {
   if (satisfies(version, range)) {
@@ -156,7 +142,7 @@ for (const version of versions) {
 }
 ```
 
-#### `Range` Class
+#### `Range` class
 
 Pre-parsed range for efficient reuse.
 
@@ -171,15 +157,15 @@ maxSatisfying(versions, range);
 minSatisfying(versions, range);
 ```
 
-### Collection Operations
+### Collection operations
 
 #### `sort(versions: string[]): string[]`
 
-Sorts versions in ascending order. Returns new array (does not mutate).
+Sorts versions in ascending order. Returns a new array; does not mutate.
 
 ```typescript
 sort(["2.5", "2.3.1", "2.10.0"]);
-// => ["2.3.1", "2.5", "2.10.0"]
+// ["2.3.1", "2.5", "2.10.0"]
 ```
 
 #### `maxSatisfying(versions, range): string | null`
@@ -187,11 +173,8 @@ sort(["2.5", "2.3.1", "2.10.0"]);
 Finds the highest version that satisfies a range.
 
 ```typescript
-maxSatisfying(["2.3.0", "2.5.1", "3.0.0"], ">=2.0 <3.0");
-// => "2.5.1"
-
-maxSatisfying(["2.3.0", "2.5.1"], ">=3.0");
-// => null (no matches)
+maxSatisfying(["2.3.0", "2.5.1", "3.0.0"], ">=2.0 <3.0"); // "2.5.1"
+maxSatisfying(["2.3.0", "2.5.1"], ">=3.0"); // null
 ```
 
 #### `minSatisfying(versions, range): string | null`
@@ -199,11 +182,10 @@ maxSatisfying(["2.3.0", "2.5.1"], ">=3.0");
 Finds the lowest version that satisfies a range.
 
 ```typescript
-minSatisfying(["2.3.0", "2.5.1", "3.0.0"], ">=2.0 <3.0");
-// => "2.3.0"
+minSatisfying(["2.3.0", "2.5.1", "3.0.0"], ">=2.0 <3.0"); // "2.3.0"
 ```
 
-### Version Manipulation
+### Version manipulation
 
 #### `increment(version, release): string`
 
@@ -223,12 +205,10 @@ Determines which component differs between versions.
 diff("2.5.1", "3.0.0"); // "major"
 diff("2.5.1", "2.6.0"); // "minor"
 diff("2.5.1", "2.5.2"); // "patch"
-diff("2.5.1", "2.5.1"); // null (equal)
+diff("2.5.1", "2.5.1"); // null
 ```
 
-## Error Handling
-
-All parsing/operation functions throw structured errors for invalid input:
+### Errors
 
 ```typescript
 import { VersionParseError, RangeParseError } from "@glion/util-semver";
@@ -239,7 +219,6 @@ try {
   if (e instanceof VersionParseError) {
     console.log(e.input); // "INVALID"
     console.log(e.reason); // "expected format: major.minor.patch..."
-    console.log(e.message); // Full formatted message
   }
 }
 
@@ -247,105 +226,36 @@ try {
   satisfies("2.5.1", "INVALID_RANGE");
 } catch (e) {
   if (e instanceof RangeParseError) {
-    console.log(e.token); // "INVALID_RANGE"
-    console.log(e.reason); // "expected format: [operator]version..."
+    console.log(e.token);
+    console.log(e.reason);
   }
 }
 ```
 
-**Validation functions never throw:**
-
-- `valid(version)` - Returns `false` for invalid input
-
-**Operation functions throw on invalid input:**
-
-- `parse()`, `clean()`, `compare()`, `satisfies()`, etc.
+- `valid(version)` never throws — returns `false` for invalid input.
+- `parse()`, `clean()`, `compare()`, `satisfies()`, etc. throw on invalid input.
 
-## Performance
+## Version comparison rules
 
-### Algorithm Complexity
+### Version format
 
-- `parse()`, `compare()`: O(1)
-- `sort()`: O(n log n)
-- `maxSatisfying()`, `minSatisfying()`: O(n) - optimized to avoid full sort
-- Range parsing: O(k) where k = number of comparators
+- Generic numeric versions: `major[.minor][.patch]`.
+- Missing components default to 0: `"2"` → `{ major: 2, minor: 0, patch: 0 }`.
+- Whitespace is trimmed: `" 2.5.1 "` → `"2.5.1"`.
+- No prerelease or build metadata.
+- No wildcards, hyphen ranges, or `^`/`~` operators.
 
-### Optimization Tips
+### Range syntax
 
-**1. Reuse Range objects**
+Operators:
 
-```typescript
-// ❌ Slow: Parse range on every call
-for (const version of manyVersions) {
-  if (satisfies(version, ">=2.0 <3.0")) {
-    /* ... */
-  }
-}
-
-// ✅ Fast: Parse once, reuse unlimited times
-const range = new Range(">=2.0 <3.0");
-for (const version of manyVersions) {
-  if (satisfies(version, range)) {
-    /* ... */
-  }
-}
-```
+- `=` or omitted — exact match
+- `<` — less than
+- `<=` — less than or equal
+- `>` — greater than
+- `>=` — greater than or equal
 
-**2. Use appropriate algorithms**
-
-```typescript
-// ❌ Unnecessary: Full sort just to find max
-const sorted = sort(versions);
-const max = sorted[sorted.length - 1];
-
-// ✅ Efficient: O(n) instead of O(n log n)
-const max = maxSatisfying(versions, ">=0.0.0");
-```
-
-## Security
-
-Built-in protections against common vulnerabilities:
-
-**ReDoS Protection:**
-
-- Maximum input length: 100 chars (versions), 1000 chars (ranges)
-- Throws `VersionParseError` or `RangeParseError` if exceeded
-
-**Integer Overflow Protection:**
-
-- Version components capped at 2³¹-1 (max safe int32)
-- Ensures cross-platform interoperability
-- Throws `VersionParseError` if exceeded
-
-**Input Sanitization:**
-
-- Comprehensive validation rejects malformed input early
-- Structured errors for debugging
-
-## Version Format
-
-- **Generic numeric versions:** `major[.minor][.patch]`
-- **Missing components default to 0:** `"2"` → `{ major: 2, minor: 0, patch: 0 }`
-- **Whitespace is trimmed:** `" 2.5.1 "` → `"2.5.1"`
-- **No prerelease/build metadata**
-- **No wildcards, hyphen ranges, or `^`/`~` operators**
-
-## Range Syntax
-
-**Operators:**
-
-- `=` or omitted - Exact match
-- `<` - Less than
-- `<=` - Less than or equal
-- `>` - Greater than
-- `>=` - Greater than or equal
-
-**Multiple comparators:**
-
-- Space-separated for AND logic: `">=2.3 <3.0"`
-- All comparators must be satisfied
-
-**Examples:**
+Multiple comparators are space-separated with AND semantics — all must be satisfied:
 
 ```typescript
 "2.5.1"; // Exact match
@@ -354,26 +264,14 @@ Built-in protections against common vulnerabilities:
 ">=2.3 <2.6 >2.4"; // Multiple AND conditions
 ```
 
-## Contributing
-
-We welcome contributions! Please see our [Contributing Guide][github-contributing] for more details.
-
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add some amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
-
-## Code of Conduct
-
-To ensure a welcoming and positive environment, we have a [Code of Conduct][github-code-of-conduct] that all contributors and participants are expected to adhere to.
+### Input limits
 
-## License
+- Versions are capped at 100 characters; ranges at 1000 characters. Longer inputs throw `VersionParseError` or `RangeParseError`.
+- Version components are capped at 2³¹−1; overflow throws `VersionParseError`.
 
-Copyright 2025 Rethink Health, SUARL. All rights reserved.
+## Part of Glion
 
-This program is licensed to you under the terms of the [MIT License](https://opensource.org/licenses/MIT). This program is distributed WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the [LICENSE][github-license] file for details.
+`@glion/util-semver` is part of **[Glion]**, the application framework for HL7v2. See the [Glion README] for the full package catalog and architecture.
 
-[github-code-of-conduct]: https://github.com/rethinkhealth/glion/blob/main/CODE_OF_CONDUCT.md
-[github-license]: https://github.com/rethinkhealth/glion/blob/main/LICENSE
-[github-contributing]: https://github.com/rethinkhealth/glion/blob/main/CONTRIBUTING.md
+[Glion]: https://github.com/rethinkhealth/glion#readme
+[Glion README]: https://github.com/rethinkhealth/glion#readme

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glion/util-semver",
-  "version": "0.15.1",
+  "version": "0.15.2",
   "description": "Tiny, fast HL7v2 version and range utilities (basic comparators only)",
   "keywords": [
     "health",
@@ -35,11 +35,13 @@
   "devDependencies": {
     "@types/node": "^25.5.0",
     "@vitest/coverage-v8": "4.1.2",
+    "publint": "0.3.18",
     "tsdown": "0.21.7",
     "typescript": "^5.9.3",
     "vitest": "4.1.2",
-    "@glion/testing": "0.15.1",
-    "@glion/tsconfig": "0.15.1"
+    "@glion/testing": "0.15.2",
+    "@glion/check-readme": "0.15.2",
+    "@glion/tsconfig": "0.15.2"
   },
   "engines": {
     "node": ">=18"
@@ -48,8 +50,10 @@
   "scripts": {
     "build": "tsdown && tsc --emitDeclarationOnly",
     "check-types": "tsc --noEmit",
+    "check:readme": "glion-check-readme",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "publint": "publint --strict"
   }
 }