Walkthrough

The PR removes the uuid dependency and centralizes UUID generation by adding RandomGenerator.uuidv4() (native crypto with fallback) and a PlatformTools.generateUuid() wrapper, then updates call sites and templates to use the new wrapper.

Changes

Sequence Diagram(s)

sequenceDiagram
    participant CallSite as Call Site
    participant PT as PlatformTools
    participant RG as RandomGenerator
    participant Crypto as Native Crypto APIs

    CallSite->>PT: generateUuid()
    PT->>RG: uuidv4()
    alt Node.js crypto.randomUUID available
        RG->>Crypto: crypto.randomUUID()
        Crypto-->>RG: uuid
    else globalThis.crypto.randomUUID available
        RG->>Crypto: globalThis.crypto.randomUUID()
        Crypto-->>RG: uuid
    else Fallback: getRandomValues
        RG->>Crypto: crypto.getRandomValues(16)
        Crypto-->>RG: bytes
        RG->>RG: apply RFC4122 version/variant mask & format
    end
    RG-->>PT: uuid string
    PT-->>CallSite: uuid string

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

• Pay attention to RandomGenerator.uuidv4(): bit masking, endianness, and formatting for RFC 4122 compliance.
• Verify PlatformTools implementations (Node and Browser template) call correct module paths and avoid dynamic-require pitfalls.
• Confirm all call sites no longer import uuid and package.json removal is consistent with code.
• Run tests that exercise UUID generation paths (Node vs. browser/fallback).

Suggested reviewers

• sgarner

Poem

🐰 I hopped through bytes and cleared a thread,
crypto whispers where uuid once led.
A tidy seed from platform's tune,
IDs born beneath the moon. ✨

Pre-merge checks and finishing touches

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

@alumni
Oops, I'll try to change it that no breaking changes occur. Thanks for comment.

@alumni
Thanks for the feedback! I'd appreciate your review to confirm this approach is correct.

Changes Made

Platform Compatibility

• Added multi-level fallback for UUID generation:
• Primary: crypto.randomUUID() (Node.js, modern browsers)
• Fallback 1: crypto.getRandomValues() (older browsers, React Native)
• Fallback 2: Math.random() (last resort)

Updated both Node and Browser PlatformTools implementations

SHA-1 Breaking Change

• Approach taken: Use RandomGenerator.sha1() on ALL platforms instead of native crypto
• Reason: Avoids breaking existing database constraint names
• Trade-off: Keeps the whitespace handling behavior (encodeURIComponent) for consistency

Please let me know if this direction is acceptable or if you'd prefer a different approach.

So first of all, if there's any breaking change, we would like to do this in the next major version of TypeORM, which is developed in the next branch (instead of master).

The Crypto WebAPI (crypto.randomUUID()) should work in nodejs/browsers (at least in recent versions of NodeJS). However, it may not work on every platform, so it would be great if we implemented our own UUIDv4 function. Not sure why crypto.getRandomValues() and Math.random() would be needed. Later edit: Ah, I see Math.random is used for the UUID generation. But that will no longer be a UUIDv4. I'd rather copy the implementation from the uuid library to maintain compatibility.

We could add a uuidv4 function to RandomGenerator that calls the native implementation if it exists and falls back to the custom implementation otherwise.

For SHA1, we can't use native crypto since it's async, so we can use our own implementation. Our implementation has a bug with certain characters (missing unescape in src/util/RandomGenerator.ts:44 IIRC). So sha.js/native crypto and our implementation have different output when some special characters are in the input. If we fix our implementation we might generate a lot of migrations for e.g. check constraints. If we don't, we might generate migrations everywhere else.

I think the UUIDv4 change is not breaking, but the SHA1 will be.

@alumni
Thank you for the detailed feedback! I've updated the implementation based on your review

Changes Made

UUID Implementation

• Moved UUID generation to RandomGenerator.uuidv4() as suggested
• Native crypto.randomUUID() is used when available
• Fallback to crypto.getRandomValues() with proper RFC 4122 implementation
• Removed Math.random() fallback - now throws error instead (as you noted, Math.random would not be RFC 4122 compliant)
• Successfully removed uuid dependency

SHA1 Scope Reduction

• Reverted all SHA1-related changes from this PR

Should I update the PR title to reflect the reduced scope (e.g., "refactor: replace uuid with native Crypto API")? Or keep the current title and clarify in comments?

And, May I proceed with creating a PR targeting the next branch for SHA1 removal?
If I could be, Are there any specific guidelines or considerations I should be aware of when contributing to the next major version?

Looking forward to your feedback!

@mag123c a few more things: the lockfile needs updating after sha.js was added back. Also the PR title should be updated.

Looking at the source code of uuid, I also wonder how it worked on React Native - crypto is not available in Hermes, not even getRandomValues, so probably a good fallback would be to create the array and set each element to a random value, like react-native-uuid does in rng (and similar to what was here before). The UUIDv4 format is achieved via the bitwise & on bytes 6 and 8, I think.

@alumni Thank you for the detailed feedback on React Native/Hermes support!

Updates Made

• package-lock.json updated after restoring sha.js dependency
• Math.random() fallback added to RandomGenerator.ts for Hermes compatibility

Before implementing, I conducted research to ensure this is the optimal approach

1. Hermes crypto support

• Confirmed via Hermes issue #915 that crypto APIs are officially out of scope
• Hermes team: "This falls outside of the JavaScript specification... should be addressed at the React Native level"

2. RFC 4122 compliance

• Section 4.4 explicitly permits "randomly (or pseudo-randomly) chosen values"
• Math.random() is compliant for UUID v4 generation

3. Others

• expo-crypto uses identical Math.random() fallback

Fixed missing socks@2.8.7 dependency in package-lock.json.

The entry was accidentally removed during a previous lock update when npm pruned the optional package. Manually restored from master's lock file.

@mag123c this should be done against next branch as it's planned for 1.0. I just changed the base branch for PR. Can you solve conflicts?

@pkuczynski I think here it's a problem of how we created the tasks, we should probably create 3 of them (shajs, uuid, and buffer), not just one :P

However, if globalThis.crypto is a headache in TS with the old versions of node, we could as well do it for the next major 🤷🏻‍♂️ I think this is what I was afraid of when I added it to the next major TODO :)

I've resolved the conflicts after the base branch was changed to next

seems the lockfile needs an update so the checks run correctly :) @mag123c

PR Code Suggestions ✨

Latest suggestions up to dd2cb3c

-// Fallback for React Native/Hermes and environments without crypto support
-// Hermes (React Native's JavaScript engine) does not provide crypto APIs
-// Math.random() is permitted by RFC 4122 for UUID v4 ("pseudo-randomly")
-// This approach is also used by expo-crypto and other RN libraries
-// Note: For TypeORM's use case (DB IDs, cache IDs), uniqueness is sufficient
-for (let i = 0; i < 16; i++) {
-    randomBytes[i] = Math.floor(Math.random() * 256)
-}
+// Fallback for environments without crypto support
+// Throw error to ensure developers provide proper crypto polyfills
+throw new Error(
+    "crypto.getRandomValues() is not available. " +
+    "Please provide a crypto polyfill for your environment."
+)

Previous suggestions

-for (let i = 0; i < 16; i++) {
-    randomBytes[i] = Math.floor(Math.random() * 256)
-}
+throw new Error(
+    "Cryptographically secure random number generation is not available. " +
+    "Please ensure your environment supports crypto.getRandomValues() or crypto.randomUUID()."
+)

-for (let i = 0; i < 16; i++) {
-    randomBytes[i] = Math.floor(Math.random() * 256)
-}
+throw new Error(
+    "Cryptographically secure random number generation is not available. " +
+    "Please ensure your environment supports crypto.getRandomValues() or crypto.randomUUID()."
+)

-for (let i = 0; i < 16; i++) {
-    randomBytes[i] = Math.floor(Math.random() * 256)
-}
+throw new Error(
+    "Cryptographically secure random number generation is not available. " +
+    "UUID generation requires crypto.getRandomValues() or crypto.randomUUID()."
+)

-for (let i = 0; i < 16; i++) {
-    randomBytes[i] = Math.floor(Math.random() * 256)
-}
+throw new Error(
+    "Cryptographically secure random number generation is not available. " +
+    "UUID generation requires crypto.getRandomValues() or crypto.randomUUID(). " +
+    "This environment does not support secure random generation."
+)

-// Fallback for React Native/Hermes and environments without crypto support
-// Hermes (React Native's JavaScript engine) does not provide crypto APIs
-// Math.random() is permitted by RFC 4122 for UUID v4 ("pseudo-randomly")
-// This approach is also used by expo-crypto and other RN libraries
-// Note: For TypeORM's use case (DB IDs, cache IDs), uniqueness is sufficient
-for (let i = 0; i < 16; i++) {
-    randomBytes[i] = Math.floor(Math.random() * 256)
-}
+// Fallback for environments without crypto support
+// Throw error to ensure developers provide proper crypto polyfills
+throw new Error(
+    "crypto.getRandomValues() is not available. " +
+    "Please provide a crypto polyfill for your environment."
+)

coverage: 80.87% (-0.02%) from 80.886%
when pulling dd2cb3c on mag123c:refactor/remove-sha-uuid-deps
into e5a8afb on typeorm:master.

I think this PR is ready @alumni

I think this PR is ready @alumni

Our comments in PlatformTools were not solved entirely :P The PR is still removing the TSDoc that you recently added :P