[email protected]: crypto declarations require a global CryptoKey type, breaking Node-only type-checks with @types/node 22 and 24

Chiusa
  • Qualcosa non va?
#10,196 0 commenti 0 reazioni 1 assegnatario Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

@effect-bot ci sta già lavorando.

Dal 30/10/2026.

  • #10197 di @effect-bot — aperta

Valutazione

Questa issue non è ancora stata valutata.

Descrizione

bug
What version of Effect is running?

4.1.0, also main at 0b4cfbc. Not reproducible with 4.0.7

What steps can reproduce the bug?

Any effect import fails to type-check with @types/node 22 or 24, no DOM library and skipLibCheck: false. This is the configuration from #8745 and #10115, with older Node types. #10116 fixes JsonWebKey but leaves these errors

Create these files in an otherwise empty directory

package.json:

{
  "private": true,
  "type": "module",
  "dependencies": {
    "effect": "4.1.0"
  },
  "devDependencies": {
    "@types/node": "24.19.2",
    "typescript": "7.0.2"
  }
}

tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2024",
    "module": "NodeNext",
    "lib": ["ES2024"],
    "types": ["node"],
    "strict": true,
    "noEmit": true
  },
  "include": ["src/**/*.ts"]
}

src/repro.ts:

import type * as Effect from "effect/Effect"

export type Probe = Effect.Effect<void>

Run:

pnpm install
pnpm exec tsc --project tsconfig.json

On 4.1.0 this also fails with TypeScript 6.0.3 and 5.9.3. Tested on Node.js 24.22.1

What is the expected behavior?

The import type-checks with Node's declarations, as it does on 4.0.7

Effect's README lists Node.js 22.19 or newer as supported and no DOM requirement, so @types/node 22 and 24 are expected to work

What do you see instead?
node_modules/.pnpm/[email protected]/node_modules/effect/dist/crypto/Aead.d.ts(306,81): error TS2749: 'CryptoKey' refers to a value, but is being used as a type here. Did you mean 'typeof CryptoKey'?

The same error appears at Cipher.d.ts(219,84), KeyAgreement.d.ts(291,94), KeyAgreement.d.ts(306,93), KeyWrap.d.ts(341,80), KeyWrap.d.ts(357,92), KeyWrap.d.ts(372,91), Mac.d.ts(232,84), Signature.d.ts(415,94) and Signature.d.ts(430,93). 4.1.0 also reports the JsonWebKey error from #10115

Effect @types/node Result, with TypeScript 7.0.2
4.0.7 24.19.2 Passes
4.1.0 24.19.2 10 CryptoKey errors and the JsonWebKey error
main at 0b4cfbc, from pkg.pr.new 22.20.5 10 errors, TS2304 Cannot find name 'CryptoKey'
main at 0b4cfbc, from pkg.pr.new 24.19.2 10 CryptoKey errors
main at 0b4cfbc, from pkg.pr.new 25.9.9 Passes
main at 0b4cfbc, from pkg.pr.new 26.6.6 Passes

The fromCryptoKey, privateKeyFromCryptoKey and publicKeyFromCryptoKey constructors take the global CryptoKey type. TypeScript's DOM library declares it. @types/node 24 declares a global CryptoKey value and a webcrypto.CryptoKey type inside node:crypto, but no global type

The error occurs with Effect alone, without using any crypto API. Adding DOM to lib, enabling skipLibCheck, or the workaround below makes the reproduction pass

Additional information

The root package.json uses @types/node ^26.6.5 and the base tsconfig enables skipLibCheck, so checks in this repository would not show these errors. check.yml does run a Node 24 job for @effect/platform-node

This differs from #9785, which covered specific entry points such as effect/rpc and @effect/platform-node. Here every effect import fails, as in #8745 and #10115

Proposed fix

Declare the shape these constructors accept, as #10116 did for JsonWebKey:

export interface CryptoKeyLike {
  readonly algorithm: { readonly name: string }
  readonly extractable: boolean
  readonly type: "private" | "public" | "secret"
  readonly usages: ReadonlyArray<string>
}

A standalone check passes the key type that crypto.subtle.exportKey accepts into a function taking this interface. It passes with @types/node 22, 24 and 26, each with Node types only, DOM types only and both, under strict and exactOptionalPropertyTypes with TypeScript 7.0.2

Deriving the type with (typeof CryptoKey)["prototype"], the approach from #8838, passes the same check with @types/node 24 and 26. It fails with 22, which has no global CryptoKey

Neither change has been tested inside Effect's own build or test suite

Current workaround

Adding this file under src/ makes the reproduction pass on 4.1.0 with @types/node 24.19.2:

import type { JsonWebKey as NodeJsonWebKey, webcrypto } from "node:crypto"

declare global {
  interface CryptoKey extends webcrypto.CryptoKey {}
  interface JsonWebKey extends NodeJsonWebKey {}
}

[!NOTE]
Posted by Claude Opus 5.5 on behalf of the author

Lingua principale
TypeScript
Stelle
16.7k
Fork
808
Merge medio
10h 15m
PR unite (30g)
845

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di Effect-TS/effect

Tutte le issue di Effect-TS/effect

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.