Docs that contradict the code: MCP.md's adapter list, RcMap capacity eviction, `disableChecks`, an unbounded "max attempts" retry example, the `@effect/vitest` logging example, and names v4 does not have

Cerrado
  • ¿Algo no está bien?
#9,374 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Ya se ha fusionado un pull request relacionado.

  • #9406 de @effect-bot — fusionado

Evaluación

Dificultad
3/5
Tiempo estimado
1-2 días
Aptitud para principiantes
45/100
Tipo de issue
Documentación
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
react, typescript
Área
documentation, testing

Línea de trabajo

This is ten separate doc corrections, each naming its file and line range, so split them up and take one first: the disableChecks JSDoc in src/Schema.ts or the forkDetach JSDoc in src/Effect.ts. Check each claim against the cited code before editing, since the issue links pin 4.0.5. Done means each listed wording is corrected in its own file, and for the item 4 retry example, the attempt bound is verified under TestClock. Items 1 and 4 also touch packages/effect/MCP.md and ai-docs/src/06_schedule/10_schedules.ts.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

What is the type of issue?

Documentation is incorrect, Documentation is missing

What is the issue?

These docs in 4.0.5 disagree with the code. #9331 did not touch them, and each is unchanged on main (c9a1e72). Links are pinned to the 4.0.5 tag.

Behaviour described wrongly

  1. MCP.md lists three protocol adapters (MCP.md#L82-L83): "This release supports McpProtocol.v2024_11_05, McpProtocol.v2025_03_26, and McpProtocol.v2025_06_18."

    • McpProtocol also exports v2025_11_25 and v2026_07_28 (McpProtocol.ts#L211-L254).
    • layerStdio and layerHttp accept any of the five (McpServer.ts#L1520, #L1657), and ProtocolAdapters.test.ts builds layerHttp with all five.
    • layerHttpRequestScoped accepts only v2026_07_28 (#L1713-L1715), which the sentence leaves out.
    • The same paragraph (MCP.md#L88-L89) says logs go to stderr through Logger.consolePretty({ stderr: true }). #8074 removed that option (Logger.ts#L823-L829). #8079 then moved the example to Layer.succeed(Logger.LogToStderr, true) (MCP.md#L64-L65), but left this sentence.
    • Fix: list all five adapters, note that layerHttpRequestScoped accepts only v2026_07_28, and name Logger.LogToStderr.

  2. RcMap's module header (RcMap.ts#L6-L8) says that when the last scope for a key closes, the resource can be "removed by capacity limits".

    • Capacity evicts nothing. Once the map is full, get for a new key fails with ExceededCapacityError (#L358-L361), and idle entries count toward the limit.
    • Example: with capacity: 1 and idleTimeToLive: "1 hour", borrow and release "a", then get "b". The get fails with ExceededCapacityError, and "a" is neither removed nor released.
    • Fix: "…released, kept alive for its idle time to live, or removed by invalidate. capacity caps how many keys are held, idle ones included; once it is reached, get for a new key fails with ExceededCapacityError."

  3. disableChecks is described as disabling validation: "to skip validation" (Schema.ts#L126), "Whether to disable validation for the schema" (#L142), and, in the Class Gotchas, "skips constructor validation" (#L16054).

    • It skips only checks. Types and structure are still parsed.
      • Schema.Int.make(1.5, { disableChecks: true }) returns 1.5.
      • Schema.Int.make("a" as any, { disableChecks: true }) throws "Schema validation failed".
      • So does a Class constructor given a string for a Schema.Int field.
    • ParseOptions already states this precisely (SchemaAST.ts#L492-L493).
    • The first two sentences predate the rename from disableValidation in Effect-TS/effect-smol#1842. That rename made construction parse with checks off, instead of skipping parsing.
    • Fix: "skips the schema's checks (filters such as isInt); constructor defaults still apply, and input of the wrong type or shape is still rejected."

  4. ai-docs productionRetrySchedule (10_schedules.ts#L8-L18) is commented "capped exponential backoff with jitter and max attempts". loadUserWithRetry refers to "exhausting the schedule" (#L47-L48).

    • Nothing bounds the attempts. Schedule.min continues while either schedule does, and neither exponential nor spaced ends, so Schedule.while(retryable) is the only stop.
    • Against an always-retryable HttpError under TestClock, it makes about 8,650 attempts in 24 hours and keeps going.
    • The file ships in the package and is linked from its AGENTS.md.
    • Fix: add Schedule.upTo({ times: 5 }) after Schedule.jittered (6 attempts, then the error), or wrap the schedule in Schedule.max([…, Schedule.recurs(5)]), as #L75-L81 does. Putting Schedule.recurs(5) inside the min array does not bound it.

  5. @effect/vitest's README Logging example (README.md#L291-L297) says an it.effect test that provides Logger.layer([Logger.consolePretty()]) displays its log, and the intro (#L277) offers a custom logger for this. It does not: it.effect provides TestConsole (internal.ts#L59), so the line lands in TestConsole.logLines.

    • Fix: use it.live, or provide Effect.provideService(Console.Console, globalThis.console).

  6. Effect.forkDetach (Effect.ts#L8894-L8896) says the fiber is "attached to the global scope". v4 has no global scope: a detached fiber has no parent and no scope.

    • Fix: "Forks the effect into a new fiber with no parent and no scope. It keeps running after the forking fiber ends, until it completes or is interrupted through its handle."

Names v4 does not have

  1. Effect.forkChild (Effect.ts#L8755-L8756) suggests "higher-level methods, such as raceWith, zipPar". Neither exists in v4.

    • Fix: point to Effect.race, Effect.raceFirst, or Effect.all with concurrency.
    • The Sink.raceWith migration note (effect__Sink.yaml#L177, rendered into v3-to-v4.md) also suggests "Effect.raceWith on the run effects".
    • The Sink.raceBoth note (effect__Sink.yaml#L174) suggests Effect.raceBoth, which v4 does not have either. Effect.race or Effect.raceFirst fits both notes.

  2. Effect.runFork's example (Effect.ts#L9054-L9060) annotates program as Effect<number, never, never> and the fiber as RuntimeFiber<number, never>.

    • program ends in Effect.as("done"), so it is Effect<string, never, never>.
    • runFork returns Fiber<string, never> (#L9070).

Behaviour not documented

  1. ManagedRuntime.make keeps a failed layer build for its lifetime (ManagedRuntime.ts#L316-L330): every later run fails with the first build error and the layer is never rebuilt, so one transient failure on first use disables a long-lived runtime. Its docs (#L245-L246) cover only success.

    • Fix: say so, and point to retrying inside the layer.

  2. useAtomSet and useAtom with mode: "promise" or "promiseExit" (Hooks.ts#L185-L194) settle with the atom's next result, not their own write's. When writes to one Atom.fn overlap, the first promise gets the second run's result (concurrent: true: both get the first's). Solid and Vue match.

  • Fix: a Gotchas note on the setter.
Where did you find it?

JSDoc in the effect 4.0.5 sources, plus packages/effect/MCP.md, packages/vitest/README.md, ai-docs/ and migration/ (links above). Each line is the same on main at c9a1e72.

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

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.