Skip to content

EFF-809: Add platform Crypto service#2180

Merged
tim-smart merged 12 commits into
mainfrom
platform-crypto
May 18, 2026
Merged

EFF-809: Add platform Crypto service#2180
tim-smart merged 12 commits into
mainfrom
platform-crypto

Conversation

@IMax153

@IMax153 IMax153 commented May 13, 2026

Copy link
Copy Markdown
Member

Summary

  • Add a platform-agnostic Crypto service with random bytes, UUIDv4/UUIDv7 generation, random helpers, and digest operations.
  • Add Node, Bun, and Browser platform layers plus service aggregate wiring.
  • Remove Random.nextUUIDv4 and document/test the new Crypto service replacement.
  • Address review feedback by making DigestAlgorithm a string literal union and moving derived random helpers / UUIDv4 onto the Crypto service via Crypto.make.
  • Address follow-up feedback by adding Crypto.randomUUIDv7, derived from platform randomBytes(16) and Clock.currentTimeMillis for the UUIDv7 timestamp.
  • Keep Node digests on node:crypto createHash and use Web Crypto digest algorithm strings directly in the browser implementation.

Verification

  • pnpm lint-fix
  • pnpm codegen (ran; unrelated generated barrel churn was restored, with focused Crypto barrel docs kept)
  • pnpm test packages/effect/test/Crypto.test.ts packages/effect/test/Random.test.ts packages/platform-browser/test/BrowserCrypto.test.ts packages/platform-node/test/NodeCrypto.test.ts
  • pnpm check:tsgo
  • cd packages/effect && pnpm docgen

@changeset-bot

changeset-bot Bot commented May 13, 2026

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 5f5e452

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 27 packages
Name Type
effect Patch
@effect/platform-node Patch
@effect/platform-node-shared Patch
@effect/platform-bun Patch
@effect/platform-browser Patch
@effect/opentelemetry Patch
@effect/vitest Patch
@effect/ai-anthropic Patch
@effect/ai-openai-compat Patch
@effect/ai-openai Patch
@effect/ai-openrouter Patch
@effect/atom-react Patch
@effect/atom-solid Patch
@effect/atom-vue Patch
@effect/sql-clickhouse Patch
@effect/sql-d1 Patch
@effect/sql-libsql Patch
@effect/sql-mssql Patch
@effect/sql-mysql2 Patch
@effect/sql-pg Patch
@effect/sql-pglite Patch
@effect/sql-sqlite-bun Patch
@effect/sql-sqlite-do Patch
@effect/sql-sqlite-node Patch
@effect/sql-sqlite-react-native Patch
@effect/sql-sqlite-wasm Patch
@effect/openapi-generator Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@github-actions

github-actions Bot commented May 13, 2026

Copy link
Copy Markdown
Contributor

Bundle Size Analysis

File Name Current Size Previous Size Difference
basic.ts 6.72 KB 6.72 KB 0.00 KB (0.00%)
batching.ts 9.22 KB 9.22 KB 0.00 KB (0.00%)
brand.ts 6.20 KB 6.20 KB 0.00 KB (0.00%)
cache.ts 9.70 KB 9.70 KB 0.00 KB (0.00%)
config.ts 18.40 KB 18.40 KB 0.00 KB (0.00%)
differ.ts 16.85 KB 16.85 KB 0.00 KB (0.00%)
http-client.ts 20.20 KB 20.20 KB 0.00 KB (0.00%)
logger.ts 10.18 KB 10.18 KB 0.00 KB (0.00%)
metric.ts 8.56 KB 8.56 KB 0.00 KB (0.00%)
optic.ts 7.37 KB 7.37 KB 0.00 KB (0.00%)
pubsub.ts 13.80 KB 13.80 KB 0.00 KB (0.00%)
queue.ts 11.08 KB 11.08 KB 0.00 KB (0.00%)
schedule.ts 10.08 KB 10.08 KB 0.00 KB (0.00%)
schema-representation-roundtrip.ts 26.17 KB 26.17 KB 0.00 KB (0.00%)
schema-string-transformation.ts 12.59 KB 12.59 KB 0.00 KB (0.00%)
schema-string.ts 10.34 KB 10.34 KB 0.00 KB (0.00%)
schema-template-literal.ts 13.94 KB 13.94 KB 0.00 KB (0.00%)
schema-toArbitraryLazy.ts 18.44 KB 18.44 KB 0.00 KB (0.00%)
schema-toCodeDocument.ts 21.12 KB 21.12 KB 0.00 KB (0.00%)
schema-toCodecJson.ts 17.66 KB 17.66 KB 0.00 KB (0.00%)
schema-toEquivalence.ts 17.61 KB 17.61 KB 0.00 KB (0.00%)
schema-toFormatter.ts 17.44 KB 17.44 KB 0.00 KB (0.00%)
schema-toJsonSchemaDocument.ts 19.96 KB 19.96 KB 0.00 KB (0.00%)
schema-toRepresentation.ts 18.00 KB 18.00 KB 0.00 KB (0.00%)
schema.ts 17.05 KB 17.05 KB 0.00 KB (0.00%)
stm.ts 11.95 KB 11.95 KB 0.00 KB (0.00%)
stream.ts 9.25 KB 9.25 KB 0.00 KB (0.00%)

@github-actions

github-actions Bot commented May 13, 2026

Copy link
Copy Markdown
Contributor

📊 JSDoc Documentation Analysis

📈 Current Analysis Results
Analyzing 137 TypeScript files in packages/effect/src/ (including schema and config subdirectories)...

============================================================
         EFFECT JSDOC ANALYSIS REPORT
============================================================

📊 SUMMARY STATISTICS
------------------------------
Total files analyzed: 137
Total exported members: 4324
Missing @example: 4315 (99.8%)
Missing @category: 397 (9.2%)

🎯 TOP FILES NEEDING ATTENTION
----------------------------------------
1. Schema.ts
   📝 520 missing examples, 🏷️  203 missing categories
   📦 520 total exports
2. Effect.ts
   📝 253 missing examples, 🏷️  0 missing categories
   📦 253 total exports
3. Stream.ts
   📝 240 missing examples, 🏷️  0 missing categories
   📦 240 total exports
4. Channel.ts
   📝 152 missing examples, 🏷️  0 missing categories
   📦 152 total exports
5. Array.ts
   📝 140 missing examples, 🏷️  0 missing categories
   📦 140 total exports
6. DateTime.ts
   📝 108 missing examples, 🏷️  0 missing categories
   📦 108 total exports
7. SchemaRepresentation.ts
   📝 96 missing examples, 🏷️  12 missing categories
   📦 96 total exports
8. SchemaAST.ts
   📝 77 missing examples, 🏷️  21 missing categories
   📦 77 total exports
9. Chunk.ts
   📝 86 missing examples, 🏷️  0 missing categories
   📦 86 total exports
10. Sink.ts
   📝 81 missing examples, 🏷️  2 missing categories
   📦 81 total exports
11. Cause.ts
   📝 79 missing examples, 🏷️  2 missing categories
   📦 79 total exports
12. Graph.ts
   📝 80 missing examples, 🏷️  0 missing categories
   📦 80 total exports
13. SchemaTransformation.ts
   📝 43 missing examples, 🏷️  31 missing categories
   📦 43 total exports
14. Option.ts
   📝 67 missing examples, 🏷️  1 missing categories
   📦 67 total exports
15. String.ts
   📝 63 missing examples, 🏷️  1 missing categories
   📦 63 total exports

✅ PERFECTLY DOCUMENTED FILES
-----------------------------------
   index.ts (0 exports)

🔍 SAMPLE MISSING ITEMS FROM Schema.ts
-----------------------------------
   Optionality (type, line 150): missing example, category
   Mutability (type, line 159): missing example, category
   ConstructorDefault (type, line 169): missing example, category
   MakeOptions (interface, line 183): missing example, category
   Bottom (interface, line 211): missing example, category
   declareConstructor (interface, line 271): missing example
   declareConstructor (function, line 335): missing example
   declare (interface, line 362): missing example
   declare (function, line 395): missing example
   revealBottom (function, line 435): missing example, category

📋 BREAKDOWN BY EXPORT TYPE
-----------------------------------
const: 2983 missing examples, 114 missing categories
interface: 482 missing examples, 91 missing categories
type: 353 missing examples, 78 missing categories
function: 359 missing examples, 88 missing categories
namespace: 72 missing examples, 26 missing categories
class: 66 missing examples, 0 missing categories

📈 DOCUMENTATION PROGRESS
------------------------------
Examples: 9/4324 (0.2% complete)
Categories: 3927/4324 (90.8% complete)

============================================================
Analysis complete! 4712 items need attention.
============================================================

📄 Detailed results saved to: jsdoc-analysis-results.json

This comment is automatically updated on each push. View the analysis script for details.

Comment thread packages/platform-browser/src/BrowserCrypto.ts Outdated
Comment thread packages/platform-browser/src/BrowserCrypto.ts Outdated
Comment thread packages/platform-node-shared/src/NodeCrypto.ts Outdated
Comment thread packages/platform-node-shared/src/NodeCrypto.ts Outdated
@erlangxk

Copy link
Copy Markdown

nodejs/node#62553

https://www.postgresql.org/docs/current/release-18.html, it supports UUIDv7 too.

is it possible to include UUIDv7 generation?

@tim-smart tim-smart changed the title Add platform Crypto service EFF-809: Add platform Crypto service May 18, 2026
Comment thread packages/effect/src/Crypto.ts Outdated
Comment thread packages/effect/src/Crypto.ts Outdated
Comment thread packages/effect/src/Crypto.ts Outdated
@IMax153

IMax153 commented May 18, 2026

Copy link
Copy Markdown
Member Author

@tim-smart another thing I was thinking about in this PR is we should make sure that the JSDocs line up with the range of random numbers generated and keep that consistent in the crypto service.

For example, Random.next says it generates between 0 (inclusive) and 1 (inclusive), which is incorrect since I believe Math.random() generates in the half-open range [0, 1).

Also, I think the nextDoubleUnsafe impl for NodeCrypto can be simplified to:

const nextDoubleUnsafe = (): number => {
  const array = new Uint32Array(1)
  NodeCrypto.getRandomValues(array)
  return array[0] / (0xFFFFFFFF + 1)
}

In addition, the nextIntUnsafe method could be simplified to the following:

function getSecureRandomNumber() {
  const buffer = crypto.randomBytes(4)
  return buffer.readUInt32BE(0)
} 

but that would imply a random range of 0 to 2^32 - 1, which is different than the range that Random.nextInt produces right now (-9007199254740991 to 9007199254740991).

In summary, I think we first need to standardize the random ranges we are targeting and then we can bring all the methods into sync and clean them up. @tim-smart lmk what you think.

tim-smart
tim-smart previously approved these changes May 18, 2026
@tim-smart tim-smart enabled auto-merge (squash) May 18, 2026 22:41
@tim-smart tim-smart merged commit 0176eaf into main May 18, 2026
14 of 15 checks passed
@tim-smart tim-smart deleted the platform-crypto branch May 18, 2026 22:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants