From 8fac76acda0a130871d8375ca29729159d3290ce Mon Sep 17 00:00:00 2001 From: Shinrai Date: Sat, 3 Oct 2026 16:46:55 -0700 Subject: [PATCH 1/2] docs(changelog): backfill v1.2.4 and correct the v1.2.3 release month --- docs/changelog/v1/v1.2.3.md | 2 +- docs/changelog/v1/v1.2.4.md | 41 +++++++++++++++++++++++++++++++++++++ 2 files changed, 42 insertions(+), 1 deletion(-) create mode 100644 docs/changelog/v1/v1.2.4.md diff --git a/docs/changelog/v1/v1.2.3.md b/docs/changelog/v1/v1.2.3.md index 6f078c2..13292ec 100644 --- a/docs/changelog/v1/v1.2.3.md +++ b/docs/changelog/v1/v1.2.3.md @@ -1,6 +1,6 @@ # @cldmv/uuid v1.2.3 Changelog -**Release Date**: September 2026 +**Release Date**: October 2026 **Release Type**: Patch **Branch**: `release/1.2.3` diff --git a/docs/changelog/v1/v1.2.4.md b/docs/changelog/v1/v1.2.4.md new file mode 100644 index 0000000..e3f63ca --- /dev/null +++ b/docs/changelog/v1/v1.2.4.md @@ -0,0 +1,41 @@ +# @cldmv/uuid v1.2.4 Changelog + +**Release Date**: October 2026 +**Release Type**: Patch + +--- + +## Overview + +v1.2.4 changes only development tooling and CI. **No runtime code changed.** The shipped `index.mjs`, `index.cjs`, `dist/` and `types/` files differ from v1.2.3 only in their file-header comments (and the regenerated type source maps that follow from them), so UUID generation, parsing and the public API behave exactly as before. + +The release moves header maintenance onto the shared CLDMV `@cldmv/fix-headers` configuration, makes the required PR check report a real result on in-repo PRs, and bumps the test runner. + +--- + +## ๐Ÿ”ง CI & tooling + +### Shared fix-headers configuration ([#46](https://github.com/CLDMV/uuid/pull/46)) + +`npm run fix:headers` now runs the `fix-headers` CLI directly against a checked-in `.configs/fix-headers.json`, which extends `@cldmv/configs/fix-headers.json`. The local `tools/fix-headers.mjs` wrapper and its `tools/lib/header-config.mjs` folder list are gone. Running the shared config once rewrote the file headers across the repository into the uniform CLDMV format, which is why almost every file shows a header-only change in this release. + +### Run the in-repo PR mirror job instead of skipping it ([#47](https://github.com/CLDMV/uuid/pull/47)) + +On a PR opened from a branch in this repository, the push run reports `โœ… Required PR Check` for the commit, so the `pull_request` run's copy of the job used to be skipped. A skipped job counts as passing for a required check, which could let a PR look mergeable before its tests finished. The mirror job in `ci.yml` now always runs and exits early with a note when the push run owns the status, so it never reports as skipped. + +## ๐Ÿ”ง Dependencies + +All dev-only; the package still has no runtime dependencies. + +- `@cldmv/fix-headers` 1.3.12 โ†’ 2.1.2, plus `@cldmv/configs` 1.2.1 added for the shared config (dev; [#46](https://github.com/CLDMV/uuid/pull/46)) +- `@cldmv/vitest-runner` 1.2.0 โ†’ 1.5.1 (dev; [#44](https://github.com/CLDMV/uuid/pull/44)) + +## ๐Ÿ“š Documentation + +- **NEW:** [docs/changelog/v1/v1.2.4.md](./v1.2.4.md): this changelog, added after the release. + +--- + +## Upgrade notes + +- No breaking changes. This is a drop-in replacement for v1.2.3, and no runtime code changed. From 50e3d6fd769bdb62641474734288c9bd3b774f9d Mon Sep 17 00:00:00 2001 From: Shinrai Date: Sat, 3 Oct 2026 16:49:02 -0700 Subject: [PATCH 2/2] docs: add v1.2.5 release notes and restructure the README --- README.md | 192 ++++++++++++++++++++++++------------ docs/changelog/v1/v1.2.5.md | 43 ++++++++ 2 files changed, 173 insertions(+), 62 deletions(-) create mode 100644 docs/changelog/v1/v1.2.5.md diff --git a/README.md b/README.md index 7a0f582..e973d0d 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,50 @@ # @cldmv/uuid -Extended UUID specification designed for RFC inclusion, formally extending RFC 4122/9562 with custom variant structures for issuer-based identification and enhanced timestamp variants. +**@cldmv/uuid** is an extended UUID specification designed for RFC inclusion. It formally extends RFC 4122/9562 with custom variant structures for issuer-based identification and enhanced timestamp variants, and ships a complete implementation of the standard RFC UUID versions alongside it. -[![npm version]][npm_version_url] [![npm downloads]][npm_downloads_url] [![GitHub downloads]][github_downloads_url] [![Last commit]][last_commit_url] [![npm last update]][npm_last_update_url] [![Coverage]][coverage_url] +The custom variants (`TA`, `TB`, `IA`) live in the variant `111` namespace, so they never collide with standard RFC UUIDs, and the same `UUID` class parses, validates and inspects both. The package has no runtime dependencies and runs in Node.js and in browser bundles. + +> _RFC-ready custom UUID variants, with every standard RFC UUID version included._ + +[![npm version]][npm_version_url] [![npm downloads]][npm_downloads_url] [![GitHub downloads]][github_downloads_url] [![Last commit]][last_commit_url] [![npm last update]][npm_last_update_url] [![coverage]][coverage_url] [![Contributors]][contributors_url] [![Sponsor shinrai]][sponsor_url] +--- + ## โœจ What's New -### Latest: v1.2.3 (September 2026) +### Latest: v1.2.5 (October 2026) -- **Release tooling only, no runtime change**: the CI and release workflows now match the `CLDMV/.github` v4.29.2 templates. That adds an approval-gated release merge that keeps the curated release notes, SLSA build provenance for published releases, auto-merge for member PRs and automatic recovery for stuck Dependabot PRs ([#37](https://github.com/CLDMV/uuid/pull/37)). A new bundle-size check tracks the published `index.mjs` / `index.cjs` / `dist/` files ([#38](https://github.com/CLDMV/uuid/pull/38)). The shipped code is the same as in v1.2.2. -- [View full v1.2.3 Changelog](https://github.com/CLDMV/uuid/blob/master/docs/changelog/v1/v1.2.3.md) +- **`require()` works**: the CommonJS entry failed to load in every earlier release, because the ESM entry it wraps used top-level `await`, which Node's synchronous `require(esm)` rejects with `ERR_REQUIRE_ASYNC_MODULE`. The entry no longer uses top-level `await`, so `require("@cldmv/uuid")` now returns the same `UUID` object as `import` on Node.js ^20.19.0 or >=22.12.0, and older versions get a clear error that points to `import()`. ESM behavior and the exported names are unchanged ([#50](https://github.com/CLDMV/uuid/pull/50)). +- [View full v1.2.5 Changelog](https://github.com/CLDMV/uuid/blob/master/docs/changelog/v1/v1.2.5.md) ### Recent Releases +- **v1.2.4** (October 2026): dev tooling only, moves header maintenance to the shared CLDMV fix-headers config and stops the in-repo PR mirror check from reporting as skipped, no runtime change ([#46](https://github.com/CLDMV/uuid/pull/46), [#47](https://github.com/CLDMV/uuid/pull/47)) ([Changelog](https://github.com/CLDMV/uuid/blob/master/docs/changelog/v1/v1.2.4.md)) +- **v1.2.3** (October 2026): release tooling only, syncs the workflows with the `CLDMV/.github` v4.29.2 templates and adds a bundle-size check, no runtime change ([#37](https://github.com/CLDMV/uuid/pull/37), [#38](https://github.com/CLDMV/uuid/pull/38)) ([Changelog](https://github.com/CLDMV/uuid/blob/master/docs/changelog/v1/v1.2.3.md)) - **v1.2.2** (September 2026): dev-only bump of `@cldmv/fix-headers` from 1.3.9 to 1.3.11, no runtime change ([#31](https://github.com/CLDMV/uuid/pull/31)) ([Changelog](https://github.com/CLDMV/uuid/blob/master/docs/changelog/v1/v1.2.2.md)) - **v1.2.1** (September 2026): CI only, passes `BOT_NAME` / `BOT_EMAIL` to the v4 release and feature-PR workflows, no runtime change ([#27](https://github.com/CLDMV/uuid/pull/27)) ([Changelog](https://github.com/CLDMV/uuid/blob/master/docs/changelog/v1/v1.2.1.md)) -- **v1.2.0** (August 2026): UUID generation no longer imports any Node built-ins, so browser bundlers can use it without polyfills ([#23](https://github.com/CLDMV/uuid/pull/23)) ([Changelog](https://github.com/CLDMV/uuid/blob/master/docs/changelog/v1/v1.2.0.md)) -- **v1.1.7** (August 2026): exposes `./package.json` in the `exports` map ([#18](https://github.com/CLDMV/uuid/pull/18)) ([Changelog](https://github.com/CLDMV/uuid/blob/master/docs/changelog/v1/v1.1.7.md)) ๐Ÿ“š **For complete version history and detailed release notes, see the [docs/changelog/](https://github.com/CLDMV/uuid/tree/master/docs/changelog/) folder.** --- -## Overview +## ๐Ÿš€ Key Features + +- ๐Ÿ†• **RFC-Ready Specification**: Extended variant (111) with formal bit layout and entropy analysis +- ๐Ÿ”ง **Issuer Variant**: 10-bit ID space (0-1023) with categorized allocation (Technology, Open Source, Reserved) +- โฑ๏ธ **Timestamp Variants**: Signed 70-bit timestamps (TA=seconds, TB=milliseconds) with negative timestamp support +- ๐ŸŽฏ **Type-Safe**: ESM-first with complete TypeScript definitions +- โšก **High Performance**: Optimized bit manipulation, 90K+ UUIDs/sec +- ๐Ÿ”’ **Collision-Resistant**: Cryptographic entropy sources with validation +- ๐Ÿ“ฆ **Zero Dependencies**: No external runtime dependencies +- ๐Ÿงช **Thoroughly Tested**: 170+ tests covering all specification requirements +- โœ… **Bonus: RFC Support**: Complete v1/v3/v4/v5/v6/v7 implementation included + +--- + +## ๐Ÿ“– Specification Overview This library implements a **new UUID specification** that formally extends the RFC 4122/9562 namespace with: @@ -36,25 +56,24 @@ This library implements a **new UUID specification** that formally extends the R The specification is designed for formal RFC submission and includes comprehensive implementation details, entropy requirements, and collision resistance analysis. -## Features +--- -- ๐Ÿ†• **RFC-Ready Specification**: Extended variant (111) with formal bit layout and entropy analysis -- ๐Ÿ”ง **Issuer Variant**: 10-bit ID space (0-1023) with categorized allocation (Technology, Open Source, Reserved) -- โฑ๏ธ **Timestamp Variants**: Signed 70-bit timestamps (TA=seconds, TB=milliseconds) with negative timestamp support -- ๐ŸŽฏ **Type-Safe**: ESM-first with complete TypeScript definitions -- โšก **High Performance**: Optimized bit manipulation, 90K+ UUIDs/sec -- ๐Ÿ”’ **Collision-Resistant**: Cryptographic entropy sources with validation -- ๐Ÿ“ฆ **Zero Dependencies**: No external runtime dependencies -- ๐Ÿงช **Thoroughly Tested**: 170+ tests covering all specification requirements -- โœ… **Bonus: RFC Support**: Complete v1/v3/v4/v5/v6/v7 implementation included +## ๐Ÿ“ฆ Installation + +### Requirements + +- **ESM (`import`)**: Node.js v16.12.0 or higher (the package's `engines.node` floor), or any modern browser bundler through the `browser` export condition. +- **CommonJS (`require()`)**: Node.js ^20.19.0 or >=22.12.0. `index.cjs` loads the ESM entry through Node's synchronous `require(esm)`, which older versions don't have; on those, load the package with `import()` instead. -## Installation +### Install ```bash npm install @cldmv/uuid ``` -## Quick Start +--- + +## ๐Ÿš€ Quick Start ### Custom UUID Variants (RFC Specification) @@ -127,7 +146,16 @@ if (UUID.validateRFC(v4)) { } ``` -## Default String Representation +CommonJS works the same way on Node.js ^20.19.0 or >=22.12.0: + +```javascript +const UUID = require("@cldmv/uuid"); // also UUID.UUID, UUID.uuid, UUID.ISSUER_CATEGORIES +const id = UUID.TB(); +``` + +--- + +## ๐Ÿ”ค Default String Representation UUIDs automatically convert to strings when used in string contexts. This provides a seamless developer experience: @@ -155,7 +183,9 @@ const buffer = uuid.toBuffer(); // 2 (milliseconds) ### Standard RFC UUID Examples -### Standard RFC UUID Examples - ```javascript import { UUID } from "@cldmv/uuid"; @@ -895,7 +927,9 @@ if (UUID.validateRFC(v4)) { } ``` -## Performance +--- + +## โšก Performance The library is optimized for high-performance UUID generation with collision resistance: @@ -907,7 +941,9 @@ The library is optimized for high-performance UUID generation with collision res - **Cryptographically Secure**: Uses Node.js crypto.randomBytes() for entropy - **Proper Entropy Validation**: All generated UUIDs validated for entropy quality -## Demonstration Script +--- + +## ๐ŸŽฌ Demonstration Script See the custom UUID specification in action with a comprehensive human-readable demonstration: @@ -948,14 +984,17 @@ Timestamp Information: ISO 8601 : 2025-12-20T03:57:34.000Z ``` -## Development & Testing +--- + +## ๐Ÿงช Development & Testing ### Running Tests ```bash -npm test # Run all tests -npm run test:watch # Watch mode -npm run test:coverage # With coverage +npm test # Run all tests (Vitest suites, then the CommonJS entry tests) +npm run test:watch # Watch mode +npm run test:cjs # CommonJS entry tests only (Node's built-in test runner) +npm run coverage # With coverage ``` ### Test Coverage @@ -974,7 +1013,9 @@ npm run test:coverage # With coverage All tests pass with 100% specification compliance. -## TypeScript Support +--- + +## ๐Ÿ”ท TypeScript Support Full TypeScript definitions included for both custom and RFC UUID APIs: @@ -1001,9 +1042,13 @@ const bytes: Uint8Array = UUID.parse(v4); const rfcVersion: number | null = UUID.version(v4); ``` -## Specification Documentation +--- + +## ๐Ÿ“š Documentation -The complete formal specification is available in [uuid-spec.md](uuid-spec.md), including: +### Specification + +The complete formal specification is available in [uuid-spec.md](https://github.com/CLDMV/uuid/blob/master/uuid-spec.md), including: - Detailed bit layout diagrams - Entropy requirement calculations (Birthday Bound analysis) @@ -1013,42 +1058,54 @@ The complete formal specification is available in [uuid-spec.md](uuid-spec.md), - Collision resistance proofs - RFC submission rationale -## License +### Changelog -Apache-2.0 ยฉ [CLDMV](https://github.com/CLDMV) +- **[Changelog](https://github.com/CLDMV/uuid/tree/master/docs/changelog/)**: per-version release notes for every release since v1.0.0 -This specification and implementation are provided for RFC standardization consideration. +### Related Projects & Standards -## Contributing +- **[RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122)** - Original UUID specification +- **[RFC 9562](https://datatracker.ietf.org/doc/html/rfc9562)** - Updated UUID specification with v6, v7, v8 +- **[uuid](https://www.npmjs.com/package/uuid)** - Standard RFC 4122 UUID implementation (Node.js) +- **[ulid](https://www.npmjs.com/package/ulid)** - Universally Unique Lexicographically Sortable Identifier + +This specification extends the RFC namespace with custom variant 111, maintaining full compatibility with existing RFC 4122/9562 UUIDs. + +[![CodeFactor]][codefactor_url] [![OpenSSF Scorecard]][ossf_scorecard_url] [![npms.io score]][npms_url] [![npm unpacked size]][npm_size_url] [![Repo size]][repo_size_url] + +--- + +## ๐Ÿค Contributing Contributions to the specification and implementation are welcome! This project aims for RFC standardization, so contributions should maintain: - **Specification Compliance**: All changes must align with the formal specification - **Backward Compatibility**: Immutable fields (variant, subvariant positions) cannot change - **Comprehensive Testing**: New features require corresponding test coverage -- **Documentation**: Changes to the specification must update [uuid-spec.md](uuid-spec.md) +- **Documentation**: Changes to the specification must update [uuid-spec.md](https://github.com/CLDMV/uuid/blob/master/uuid-spec.md) -Please read the contributing guidelines before submitting pull requests. +[![Contributors]][contributors_url] [![Sponsor shinrai]][sponsor_url] -## Support & Discussion +--- -- ๐Ÿ› [Report Issues](https://github.com/CLDMV/uuid/issues) -- ๐Ÿ’ฌ [Specification Discussions](https://github.com/CLDMV/uuid/discussions) -- ๐Ÿ“– [Full Specification Document](uuid-spec.md) -- ๐Ÿ’ฐ [Sponsor Development](https://github.com/sponsors/shinrai) +## ๐Ÿ”— Links -## Related Projects & Standards +- **npm**: [@cldmv/uuid](https://www.npmjs.com/package/@cldmv/uuid) +- **GitHub**: [CLDMV/uuid](https://github.com/CLDMV/uuid) +- **Issues**: [GitHub Issues](https://github.com/CLDMV/uuid/issues) +- **Specification**: [uuid-spec.md](https://github.com/CLDMV/uuid/blob/master/uuid-spec.md) +- **Changelog**: [docs/changelog/](https://github.com/CLDMV/uuid/tree/master/docs/changelog/) +- **Sponsor**: [GitHub Sponsors](https://github.com/sponsors/shinrai) -- **[RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122)** - Original UUID specification -- **[RFC 9562](https://datatracker.ietf.org/doc/html/rfc9562)** - Updated UUID specification with v6, v7, v8 -- **[uuid](https://www.npmjs.com/package/uuid)** - Standard RFC 4122 UUID implementation (Node.js) -- **[ulid](https://www.npmjs.com/package/ulid)** - Universally Unique Lexicographically Sortable Identifier +--- -This specification extends the RFC namespace with custom variant 111, maintaining full compatibility with existing RFC 4122/9562 UUIDs. +## ๐Ÿ“„ License + +[![npm license]][npm_license_url] -## Changelog +Apache-2.0 ยฉ Shinrai / CLDMV -See [docs/changelog/](https://github.com/CLDMV/uuid/tree/master/docs/changelog/) for per-version release notes covering every release since v1.0.0. +This specification and implementation are provided for RFC standardization consideration. --- @@ -1056,7 +1113,6 @@ See [docs/changelog/](https://github.com/CLDMV/uuid/tree/master/docs/changelog/) Made with โค๏ธ by [CLDMV](https://cldmv.net) - @@ -1064,14 +1120,26 @@ Made with โค๏ธ by [CLDMV](https://cldmv.net) [npm version]: https://img.shields.io/npm/v/%40cldmv%2Fuuid.svg?style=for-the-badge&logo=npm&logoColor=white&labelColor=CB3837 [npm_version_url]: https://www.npmjs.com/package/@cldmv/uuid -[npm downloads]: https://img.shields.io/npm/dm/%40cldmv%2Fuuid.svg?style=for-the-badge&logo=npm&logoColor=white&labelColor=CB3837 -[npm_downloads_url]: https://www.npmjs.com/package/@cldmv/uuid -[github downloads]: https://img.shields.io/github/downloads/CLDMV/uuid/total?style=for-the-badge&logo=github&logoColor=white&labelColor=181717 -[github_downloads_url]: https://github.com/CLDMV/uuid/releases [last commit]: https://img.shields.io/github/last-commit/CLDMV/uuid?style=for-the-badge&logo=github&logoColor=white&labelColor=181717 [last_commit_url]: https://github.com/CLDMV/uuid/commits [npm last update]: https://img.shields.io/npm/last-update/%40cldmv%2Fuuid?style=for-the-badge&logo=npm&logoColor=white&labelColor=CB3837 [npm_last_update_url]: https://www.npmjs.com/package/@cldmv/uuid +[codefactor]: https://img.shields.io/codefactor/grade/github/CLDMV/uuid?style=for-the-badge&logo=codefactor&logoColor=white&labelColor=F44A6A +[codefactor_url]: https://www.codefactor.io/repository/github/cldmv/uuid +[openssf scorecard]: https://img.shields.io/ossf-scorecard/github.com/CLDMV/uuid?style=for-the-badge&label=OpenSSF%20Scorecard +[ossf_scorecard_url]: https://scorecard.dev/viewer/?uri=github.com/CLDMV/uuid +[npms.io score]: https://img.shields.io/npms-io/final-score/%40cldmv%2Fuuid?style=for-the-badge&logo=npms&logoColor=white&labelColor=0B5D57 +[npms_url]: https://npms.io/search?q=%40cldmv%2Fuuid +[npm downloads]: https://img.shields.io/npm/dm/%40cldmv%2Fuuid.svg?style=for-the-badge&logo=npm&logoColor=white&labelColor=CB3837 +[npm_downloads_url]: https://www.npmjs.com/package/@cldmv/uuid +[github downloads]: https://img.shields.io/github/downloads/CLDMV/uuid/total?style=for-the-badge&logo=github&logoColor=white&labelColor=181717 +[github_downloads_url]: https://github.com/CLDMV/uuid/releases +[npm unpacked size]: https://img.shields.io/npm/unpacked-size/%40cldmv%2Fuuid.svg?style=for-the-badge&logo=npm&logoColor=white&labelColor=CB3837 +[npm_size_url]: https://www.npmjs.com/package/@cldmv/uuid +[repo size]: https://img.shields.io/github/repo-size/CLDMV/uuid?style=for-the-badge&logo=github&logoColor=white&labelColor=181717 +[repo_size_url]: https://github.com/CLDMV/uuid +[npm license]: https://img.shields.io/npm/l/%40cldmv%2Fuuid.svg?style=for-the-badge&logo=npm&logoColor=white&labelColor=CB3837 +[npm_license_url]: https://www.npmjs.com/package/@cldmv/uuid [coverage]: https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2FCLDMV%2Fuuid%2Fbadges%2Fcoverage.json&style=for-the-badge&logo=vitest&logoColor=white [coverage_url]: https://github.com/CLDMV/uuid/blob/badges/coverage.json [contributors]: https://img.shields.io/github/contributors/CLDMV/uuid.svg?style=for-the-badge&logo=github&logoColor=white&labelColor=181717 diff --git a/docs/changelog/v1/v1.2.5.md b/docs/changelog/v1/v1.2.5.md new file mode 100644 index 0000000..6a41b1d --- /dev/null +++ b/docs/changelog/v1/v1.2.5.md @@ -0,0 +1,43 @@ +# @cldmv/uuid v1.2.5 Changelog + +**Release Date**: October 2026 +**Release Type**: Patch +**Branch**: `release/1.2.5` + +--- + +## Overview + +v1.2.5 makes `require("@cldmv/uuid")` work. The CommonJS entry has failed to load in every release up to and including v1.2.4, because the ESM entry it wraps used top-level `await`. This release removes the top-level `await`, so `require()` returns the same `UUID` object that `import` does on any Node.js version with synchronous `require(esm)`, and fails with a clear message on versions without it. + +ESM consumers see no change in behavior. The exported names (`default`, `UUID`, `uuid`, `ISSUER_CATEGORIES`) and their values are the same as in v1.2.4. + +--- + +## ๐Ÿ› Bug Fixes + +### Load the CommonJS entry without top-level await ([#50](https://github.com/CLDMV/uuid/pull/50)) + +`index.cjs` loads `index.mjs` through Node's synchronous `require(esm)`. Node rejects any module graph that contains top-level `await` there, and `index.mjs` had two: one around the optional `devcheck.mjs` import and one for `await import("@cldmv/uuid/main")`. So on Node.js versions with `require(esm)`, `require("@cldmv/uuid")` threw `ERR_REQUIRE_ASYNC_MODULE`, and on older versions it threw `ERR_REQUIRE_ESM`. Either way, no CommonJS consumer could load the package. + +- `index.mjs` now imports `@cldmv/uuid/main` statically, and the optional development check runs inside an async function rather than at the top level. `devcheck.mjs` exists only in a source checkout and has never been published, so its import is still allowed to fail. +- `index.cjs` calls `require("./index.mjs")` directly instead of going through `createRequire`. +- On a Node.js version without `require(esm)` (anything before 20.19.0, or 22.0.0 to 22.11.x), `index.cjs` now throws an `ERR_REQUIRE_ESM` error whose message names the supported versions and points to `import()` instead. +- A new `tests/cjs/entry.test.cjs` suite runs under Node's own test runner, since Vitest loads files through its own module runner and can't show how a plain `require()` behaves. It checks that `require()` returns the same objects as `import` and that the error message appears when `require(esm)` is turned off. `npm test` and `npm run coverage` both run it through the new `test:cjs` script. + +### Export the default from the named export list ([#50](https://github.com/CLDMV/uuid/pull/50)) + +`tsc` emitted `export default UUID;` above the declaration it referred to in `types/index.d.mts`, which CodeQL flags as `js/use-before-declaration`. The entry now exports a single list (`export { UUID as default, UUID, UUID as uuid, ISSUER_CATEGORIES }`), so the generated declaration file imports `UUID` and `ISSUER_CATEGORIES` from `@cldmv/uuid/main` first and then re-exports them. The exported types are unchanged. + +## ๐Ÿ“š Documentation + +- **NEW:** [docs/changelog/v1/v1.2.5.md](./v1.2.5.md): this changelog. +- **NEW:** backfilled [v1.2.4](./v1.2.4.md), and corrected the [v1.2.3](./v1.2.3.md) release month to October 2026. +- README restructured to the standard CLDMV layout, with a new Requirements section that states the `require()` Node.js floor. + +--- + +## Upgrade notes + +- No breaking changes. ESM imports behave exactly as in v1.2.4. +- CommonJS consumers can now use `const UUID = require("@cldmv/uuid")` (with `UUID.UUID`, `UUID.uuid` and `UUID.ISSUER_CATEGORIES` as properties). This needs Node.js ^20.19.0 or >=22.12.0. On older Node.js versions, load the package with `import()`.