Skip to content

docs: cover #54 and #55 in the v1.2.5 notes and README #56

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Shinrai merged 1 commit into from
Oct 4, 2026
Merged

docs: cover #54 and #55 in the v1.2.5 notes and README #56

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ The custom variants (`TA`, `TB`, `IA`) live in the variant `111` namespace, so t
### Latest: v1.2.5 (October 2026)

- **`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)).
- **Real TypeScript types**: `UUID` used to resolve to `any`. The package and its subpaths now ship accurate declarations, with optional generator options and `toBuffer()` typed as `Buffer` in Node projects and `Uint8Array` in browser and bundler projects ([#55](https://github.com/CLDMV/uuid/pull/55)). The repository also gains its Apache-2.0 `LICENSE` file ([#54](https://github.com/CLDMV/uuid/pull/54)).
- [View full v1.2.5 Changelog](https://github.com/CLDMV/uuid/blob/master/docs/changelog/v1/v1.2.5.md)

### Recent Releases
Expand Down Expand Up @@ -1101,9 +1102,9 @@ Contributions to the specification and implementation are welcome! This project

## 📄 License

[![npm license]][npm_license_url]
[![GitHub license]][github_license_url] [![npm license]][npm_license_url]

Apache-2.0 © Shinrai / CLDMV
Apache-2.0 © Shinrai / CLDMV. See [LICENSE](https://github.com/CLDMV/uuid/blob/master/LICENSE) for the full text.

This specification and implementation are provided for RFC standardization consideration.

Expand Down Expand Up @@ -1138,6 +1139,8 @@ Made with ❤️ by [CLDMV](https://cldmv.net)
[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
[github license]: https://img.shields.io/github/license/CLDMV/uuid.svg?style=for-the-badge&logo=github&logoColor=white&labelColor=181717
[github_license_url]: https://github.com/CLDMV/uuid/blob/HEAD/LICENSE
[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
Expand Down
25 changes: 24 additions & 1 deletion docs/changelog/v1/v1.2.5.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,9 @@

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.
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.

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.

---

Expand All @@ -29,6 +31,26 @@ ESM consumers see no change in behavior. The exported names (`default`, `UUID`,

`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](https://github.com/CLDMV/uuid/pull/55), fixes [#51](https://github.com/CLDMV/uuid/issues/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`.

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](https://github.com/CLDMV/uuid/pull/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.
Expand All @@ -40,4 +62,5 @@ ESM consumers see no change in behavior. The exported names (`default`, `UUID`,
## 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()`.
Loading