chore: add the Apache-2.0 LICENSE file - #54
Merged
Merged
Conversation
package.json declares Apache-2.0 and lists LICENSE in `files`, but the repository never had the file, so GitHub detected no license and the published package shipped without the license text.
cldmv-bot
Bot
added
the
! chore → next
Shinrai
approved these changes
Oct 4, 2026
This was referenced Oct 4, 2026
Shinrai
added a commit
that referenced
this pull request
Oct 4, 2026
cldmv-bot Bot
added a commit
that referenced
this pull request
Oct 5, 2026
# @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.
It also gives TypeScript users real types for the first time: `UUID` used to resolve to `any`, and it is now fully typed, with `Buffer` returns in Node projects and `Uint8Array` returns in browser and bundler projects. The repository finally carries the Apache-2.0 `LICENSE` file that `package.json` has always declared. The dev toolchain moves to `@cldmv/fix-headers` 2.2.0 and `@cldmv/configs` 1.2.4, and `@types/node` is added for the new type tests.
ESM consumers see no change in runtime 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](#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](#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.
## 🔷 TypeScript
### Accurate type declarations for the package and its subpaths ([#55](#55), fixes [#51](#51))
`types/index.d.mts` imports from `@cldmv/uuid/main`, but `./main` had no `types` condition, so TypeScript could not find its declarations and `UUID` was typed `any`. `skipLibCheck` hid the error. `./main`, `./rng`, `./bytes` and `./hash` now all have `types` conditions, and the generated declarations were fixed in the source JSDoc so they compile with `strict` and `skipLibCheck: false`:
- The options argument of `v1`, `v4`, `v6`, `v7` and `v8` is optional and typed (`UUID.v4()` used to be a compile error once the types resolved). Passing `buf` returns that same buffer, typed as whatever you passed in; otherwise the methods return a `string`.
- `TA`/`TB` timestamps and `entropy` arguments are optional, and `getRegistry()`'s `IssuerRegistry` type resolves.
- `toBuffer()` returns `Buffer` in Node projects (`module`/`moduleResolution` `node16`/`nodenext` with `@types/node`) and `Uint8Array` in browser and bundler projects, chosen through a private `#bytes-type` import. The package never forces Node's globals into a project: without `@types/node` the type falls back to `Uint8Array`. The two alias declarations behind it live in a new `typings/` folder (`typings/bytes.d.mts` and `typings/bytes-node.d.mts`), which is added to the package's `files` and selected through a new `imports` entry in `package.json`.
A new `npm run test:types` check (run by `npm test` and `npm run coverage`) packs the package, installs it into a throwaway consumer and compiles it under `nodenext` and `bundler` resolution, including the README's TypeScript example.
---
## 📄 License
The repository now includes the Apache-2.0 `LICENSE` file ([#54](#54)). `package.json` has always declared Apache-2.0 and listed `LICENSE` in `files`, but the file was missing, so GitHub showed no license and the published package shipped without the license text.
---
## 📚 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.
## 🔧 Dependencies
All changes are dev-only and none ships in the package. The package still has no runtime dependencies.
- `@cldmv/fix-headers` `^2.1.2` → `^2.2.0`, resolved to 2.2.0. The range was first raised to `^2.1.4` ([#57](#57)) and then to `^2.2.0` ([#59](#59)). Version 2.1.4 no longer writes a JavaScript comment into JSON or Markdown files, processes every repeated `--input`, and never walks dependency folders such as `node_modules`. Version 2.2.0 changes `@Last modified by` only when a file's content was edited, so header-only rewrites keep the recorded editor.
- `@cldmv/configs` `^1.2.1` → `^1.2.4`, resolved to 1.2.4. The shared fix-headers config now sets `forceAuthorUpdate` and `forceLastModifiedAuthorUpdate` to false ([#59](#59)).
- `@types/node` `^26.6.4` added (resolved to 26.6.4, with its transitive `undici-types` 8.9.0). The type-check suite uses it to prove that `toBuffer()` returns `Buffer` in a Node project ([#55](#55)).
- No file headers were restamped: the fix-headers and configs bump PRs change only `package.json` and the lockfile, and the published package is unaffected.
---
## Upgrade notes
- No breaking changes. ESM imports behave exactly as in v1.2.4.
- TypeScript projects that relied on `UUID` being `any` may now see real type errors in their own code; those are calls the types previously failed to check.
- 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()`.
<details>
<summary>👥 Contributors</summary>
- @Shinrai
</details>
---
<!-- coverage-start -->
| Metric | Coverage |
|--------|----------|
| Statements | 85.7% |
| Branches | 84.9% |
| Functions | 92.5% |
| Lines | 85.4% |
*Avg: **87.1%** · `2782926` · Node lts/**
<!-- coverage-end -->
<!-- co-authors -->
Co-authored-by: Shinrai <Shinrai@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
🚀 What's Changed
💥 Breaking Changes
No breaking changes
✨ Features
No new features
🐛 Bug Fixes
No bug fixes
📦 Dependencies
No dependency updates
🔧 Other Changes
👥 Contributors