Registry / devops / build-number-generator

build-number-generator

library3.0.0jsnpmunverified

build-number-generator is a utility that creates unique, human-readable build numbers for software projects. These nine-digit integers encode the build date (YYMMDD) and a count of two-minute intervals after midnight (CCC), ensuring uniqueness for builds at least two minutes apart. The current stable version is 3.0.0, released on 2025-06-26. The package offers both a command-line interface and an API for programmatic use in Node.js, Deno, and web browsers, supporting ESM, CJS, and UMD formats. Key differentiators include its no-dependency footprint, tiny size, and the ability to infer the build time directly from the number without external storage, making it suitable for CI/CD environments. It ships with full TypeScript types.

devops serialization

npm install build-number-generator

github ↗package ↗

INSTALL

IMPORT

SIG · BUILD-NUMBER-GENER

build-number-generator

devopsjavascriptv3.0.0

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.

generate

✓ import { generate } from 'build-number-generator'

✗ const generate = require('build-number-generator')

ESM is the primary export since v2.0.0, CJS is available but direct require() is discouraged for newer Node.js versions. v3.x explicitly requires Node.js >=18.

parse

✓ import { parse } from 'build-number-generator'

✗ import parse from 'build-number-generator'

This is a named export; a default import is not provided for the core functions.

validate

✓ import { validate } from 'build-number-generator'

Used to check if a string is a valid build number generated by this library.

This quickstart demonstrates generating a new build number, combining it with a product version, and then parsing a build number back into a human-readable date. It also shows error handling for invalid build numbers.

import { generate, parse } from 'build-number-generator'; async function runBuildProcess() { const productVersion = '1.2.3'; const buildNumber = generate(); console.log(`Generated build number: ${buildNumber}`); console.log(`Full version string: ${productVersion}.${buildNumber}`); const parsedDate = parse(buildNumber); console.log(`Build number ${buildNumber} corresponds to: ${parsedDate.toDateString()} ${parsedDate.toLocaleTimeString()}`); const invalidBuildNumber = '12345'; // Too short try { parse(invalidBuildNumber); } catch (error: any) { console.log(`Attempted to parse invalid build number '${invalidBuildNumber}': ${error.message}`); } } runBuildProcess();

build-number-generator --version

Debug

Known issues

breakingVersion 3.0.0 introduced a breaking change by upgrading dependencies and raising the minimum supported Node.js version. It now requires Node.js >=18.

fix

Ensure your project runs on Node.js 18 or newer. If you must use older Node.js versions, consider pinning to `build-number-generator@^2.0.0` or `^1.0.0` depending on your specific Node.js version requirements (e.g., v1.x for Node.js < 14.8).

affects: >=3.0.0

breakingVersion 2.0.0 removed the `commander` dependency and modernized the project, aligning with newer Node.js features. This also implicitly raised the minimum Node.js version requirement for full compatibility (specifically for ESM and some internal modernizations).

fix

Upgrade your Node.js environment to at least version 14.8, or preferably 16+. If using Node.js < 14.8, you must stick to `build-number-generator@^1.0.0`.

affects: >=2.0.0 <3.0.0

gotchaThe `build-number-generator` CLI tool (`buildnumgen`) changed its CJS export paths and bin script paths in patch versions of v2.0.x (e.g., v2.0.3). While generally transparent, this could affect some very specific build setups or older package managers resolving paths explicitly.

fix

For CLI usage, ensure global installation or verify that your local `node_modules/.bin` symlinks are correctly resolving. For programmatic CJS usage, stick to named exports or use ESM where possible.

affects: >=2.0.0 <2.0.4

gotchaTypeScript types for the package were initially missing or incorrectly included in published packages in early v2.x releases (e.g., v2.0.1, v2.0.2). This was corrected in later patch versions.

fix

If experiencing TypeScript errors with `build-number-generator@2.x`, upgrade to `build-number-generator@^2.0.4` or later to ensure correct type definitions are included and referenced in `package.json` exports.

affects: >=2.0.0 <2.0.4

gotchaThe generated build numbers are unique per a two-minute interval. If your CI/CD pipeline performs multiple builds within the same two-minute window, they will receive the *same* build number. This is by design.

fix

Factor this design choice into your versioning strategy. If sub-two-minute uniqueness is critical, append an additional unique identifier (e.g., commit hash, incrementing counter) to the generated build number, or ensure builds are spaced out.

affects: *

Errors

Common errors & fixes

Error: Cannot find module 'build-number-generator'

Attempting to `require()` or `import` the package without it being installed, or with a Node.js version that does not support its module format.

fix

Ensure the package is installed (`npm install build-number-generator`). If using Node.js < 14.8, you must use version 1.x. For Node.js >=18, use version 3.x and ensure you're using `import` statements for ESM.

TypeError: generate is not a function

Incorrect import statement, often trying to use CommonJS `require` syntax (`const generate = require('build-number-generator')`) when the package is primarily ESM, or attempting a default import when only named exports are provided.

fix

Use named ESM imports: `import { generate } from 'build-number-generator';`. If you are stuck on an older Node.js version requiring CJS, verify `package.json` `exports` or ensure you are using a compatible package version (e.g., v1.x).

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

Attempting to call `.toDateString()` on the result of `parse()` when `parse()` received an invalid build number and threw an error, which was not caught.

fix

Always wrap calls to `parse()` in a `try...catch` block, or validate the build number first using `validate()` before parsing, especially if the input is user-supplied or external.

Error: build number 'YYYYMMDDCCC' does not comply with the 'YYYYMMDDCCC' format

The string passed to `parse()` or `validate()` does not match the expected 9-digit BCD format.

fix

Ensure the input string is exactly 9 digits long and conforms to the YYMMDDCCC pattern (e.g., `240419123` for April 19, 2024). This error also occurs if the numeric value exceeds `235929999`.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/prantlf/build-number-generator ↗

packagehttps://www.npmjs.com/package/build-number-generator ↗