Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Abierto
  • ¿Algo no está bien?
#10,196 0 comentarios 0 reacciones 1 asignado Ver en GitHub

Los mantenedores suelen responder en 1 día

@effect-bot ya está trabajando en esto.

Desde el 30/10/2026.

  • #10197 de @effect-bot — abierto

Evaluación

Este issue todavía no se ha evaluado.

Descripción

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

Lenguaje dominante
TypeScript
Estrellas
16.7k
Forks
808
Merge medio
10 h 17 min
PR fusionados (30 d)
850

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de Effect-TS/effect

Todos los issues de Effect-TS/effect

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.