Registry / serialization / balena-semver

balena-semver

library4.0.18jsnpmunverified

balena-semver, currently at version 4.0.18, provides a collection of Balena-specific utility methods for working with semantic versions. While it parses and adheres to standard semver strings, its key differentiator is its ability to handle Balena OS version formats, such as 'Resin OS vX.Y.Z'. The package maintains a frequent release cadence, primarily issuing patch updates as seen with numerous recent v4.0.x releases. This module is explicitly noted as a low-level utility intended for internal Balena components and is generally not recommended for direct use by end-users; instead, the Balena SDK is suggested for most applications. It ships with TypeScript types, facilitating its use in modern JavaScript and TypeScript projects. The package requires Node.js versions `^20.12.0 || >= 22.0.0`.

serialization

npm install balena-semver

github ↗package ↗

INSTALL

IMPORT

SIG · BALENA-SEMVER

balena-semver

serializationjavascriptv4.0.18

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

compare

✓ import { compare } from 'balena-semver';

✗ const compare = require('balena-semver').compare;

Primary way to compare two Balena-specific or standard semver strings.

satisfies

✓ import { satisfies } from 'balena-semver';

✗ const satisfies = require('balena-semver').satisfies;

Checks if a version satisfies a given range, handling Balena-specific formats.

major

✓ import { major } from 'balena-semver';

✗ const { major } = require('balena-semver');

Extracts the major version from a semver string, including Balena OS variants.

Demonstrates basic usage including comparing different version formats, satisfying ranges, and extracting version components.

import { compare, satisfies, major, prerelease, parse } from 'balena-semver'; const versionA = 'Resin OS v2.0.2+rev2'; const versionB = '2.0.5'; const versionC = '1.16.0'; const versionD = 'Resin OS 1.16.0'; const versionE = '1.2.3-beta.1'; console.log(`Comparing '${versionA}' and '${versionB}': ${compare(versionA, versionB)}`); // Expected: 1 (versionA is greater, custom parsing applies) console.log(`'${versionB}' satisfies '>=2.0.0 <2.1.0': ${satisfies(versionB, '>=2.0.0 <2.1.0')}`); // Expected: true console.log(`Major version of '${versionA}': ${major(versionA)}`); // Expected: 2 console.log(`Prerelease of '${versionE}': ${prerelease(versionE)}`); // Expected: ['beta', 1] const parsedVersion = parse(versionD); if (parsedVersion) { console.log(`Parsed version of '${versionD}': Major=${parsedVersion.major}, Minor=${parsedVersion.minor}, Patch=${parsedVersion.patch}`); } else { console.log(`Failed to parse '${versionD}'.`); } // Example of sorting versions const versions = ['2.0.0', 'Resin OS 1.16.0', '1.2.3', 'Resin OS v2.0.2+rev2', '2.0.0-beta']; versions.sort(compare); console.log('Sorted versions (ascending):', versions);

Debug

Known issues

gotchaThis module is a low-level utility primarily designed for Balena's internal components. Direct use by end-users is discouraged, and the Balena SDK is recommended for most applications.

fix

Consider using the higher-level Balena SDK for application development unless you explicitly require these specific, low-level semver utilities.

affects: >=1.0.0

breakingThe package's `engines` field specifies Node.js `^20.12.0 || >= 22.0.0`. Using older Node.js versions is unsupported and may lead to unexpected behavior or runtime errors.

fix

Ensure your project uses Node.js version 20.12.0 or higher, or Node.js 22.0.0 or higher, to maintain compatibility and stability.

affects: >=4.0.0

gotchaWhen submitting versions in Balena Cloud via `balena.yml`, including a 'v' prefix (e.g., `version: 'v1.2.3'`) can cause the Balena semver validator to fail, potentially resulting in '0.0.0' versions appearing on the dashboard.

fix

Remove any 'v' prefixes from version strings in `balena.yml` (e.g., use `version: '1.2.3'` instead of `version: 'v1.2.3'`).

affects: >=4.0.0

gotchaSemantic Versioning build metadata (e.g., the `+dev.abc123` part in `1.2.3+dev.abc123`) is not considered for uniqueness rules in Balena Cloud releases. Subsequent pushes of the exact same major.minor.patch will result in a `+revN` suffix being automatically appended by the backend to ensure uniqueness.

fix

Be aware that build metadata is purely informational and does not affect release uniqueness or comparison logic within the Balena ecosystem's versioning enforcement.

affects: >=4.0.0

Errors

Common errors & fixes

Error: Invalid Version: v1.2.3

Attempting to parse or validate a version string that includes a 'v' prefix, which is not strictly compliant with the internal Balena semver validation, especially in contexts like `balena.yml`.

fix

Ensure version strings do not contain a 'v' prefix. Use '1.2.3' instead of 'v1.2.3'.

TypeError: Cannot read properties of undefined (reading 'major')

Attempting to access properties of a `null` return value from a `balena-semver` function (e.g., `parse`, `major`) when an invalid or unparsable version string was provided.

fix

Always check for `null` or `undefined` return values when calling `balena-semver` functions that can fail parsing, such as `parse(version)` or `major(version)`. Handle cases where the input version string is not a valid semantic version or Balena-specific version.

Upgrade

Version history

4.0.18latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

23 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/balena-io-modules/balena-semver ↗

packagehttps://www.npmjs.com/package/balena-semver ↗