From 131f2ece72fc724a7f0b67206851365a79a0c6b0 Mon Sep 17 00:00:00 2001 From: Shinrai Date: Sat, 3 Oct 2026 18:45:55 -0700 Subject: [PATCH] docs: cover #54 and #55 in the v1.2.5 notes and README The LICENSE file and the TypeScript declaration fix merged into next ahead of the v1.2.5 notes but were not described. Add both to the changelog and the What's New block, and show the GitHub license badge now that the file exists. --- README.md | 7 +++++-- docs/changelog/v1/v1.2.5.md | 25 ++++++++++++++++++++++++- 2 files changed, 29 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index dd39940..2fe4a8d 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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. @@ -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 diff --git a/docs/changelog/v1/v1.2.5.md b/docs/changelog/v1/v1.2.5.md index 6a41b1d..7da58b0 100644 --- a/docs/changelog/v1/v1.2.5.md +++ b/docs/changelog/v1/v1.2.5.md @@ -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. --- @@ -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. @@ -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()`.