Wrdn Effect Typed Errors

You fix one family of patterns: untyped JavaScript error handling in Effect code.

The preferred boundary is typed Schema.TaggedError / Data.TaggedError values in the Effect error channel. Construct the tagged error directly at the failure site unless a helper performs real classification or normalization.

Trace before changing

1. Identify the boundary. Is this Effect domain code, React UI code, a third-party callback, or plain test/tooling code?
2. Find the existing domain errors. Check nearby errors.ts, Schema.TaggedError, Data.TaggedError, and API .addError(...) declarations before adding a new class.
3. Decide whether a new error is needed. Add a new tagged error only if callers have a distinct recovery path, HTTP status, UI affordance, retry policy, or telemetry classification.
4. Preserve failure semantics. If the old code failed, the new code should fail in the Effect error channel. Do not replace thrown failures with fallback values like false, null, undefined, [], or "unknown" unless the existing contract already treats that condition as non-fatal.
5. Preserve the typed channel. Do not convert typed failures into Error, thrown exceptions, String(error), or .message reads from unknown values.
6. Recognize real boundaries. Runtime workers, Vite/CLI tooling, callback APIs, and third-party interfaces may have to throw, catch, or reject at the boundary. Do not contort those files into fake Effect shapes. Keep the boundary idiom when it is contained and immediately wrapped into an Effect error channel, stable IPC envelope, or test/tooling result.
7. Do not hide construction behind trivial helpers. Inline new DomainError(...) unless the helper branches on input or maps an external error format into a domain error.

Preserve behavior first

The lint rule is about where the failure lives, not whether the operation should still fail.

Bad fix: this removes the lint finding by silently changing invalid input into a non-match.

case "in":
  if (!Array.isArray(value)) return false;
  return value.some((v) => cmp(lhs, v));

Good fix: keep the invalid input as a failure, but make it typed.

case "in":
  if (!Array.isArray(value)) {
    return Effect.fail(
      new StorageError({ message: "Value must be an array", cause: clause }),
    );
  }
  return Effect.succeed(value.some((v) => cmp(lhs, v)));

When the containing helper was synchronous, make the helper return Effect.Effect<Success, DomainError> and thread that through callers. Do not collapse the error into a success value to avoid changing call sites.

Boundary exceptions

The lint rule is not a mandate to make every file Effect-shaped. It is acceptable to keep try/catch, throw, new Error, .catch, or String(error) at a true adapter boundary when all of these are true:

• the surrounding API is inherently throwing, callback-based, Promise-based, process/IPC-based, or plain JS tooling
• the untyped behavior is contained to the boundary function or module
• control is immediately translated into a typed Effect failure, stable IPC payload, stable test assertion, or deliberately best-effort cleanup
• the suppression is narrow and explains the boundary

Repo Effect API compatibility

Use the APIs that exist in this repo's pinned Effect runtime:

• Use Effect.callback for callback adapters. Do not use Effect.async.
• Use Effect.andThen or Effect.gen sequencing. Do not use Effect.zipRight.
• Use Effect.timeoutOrElse or Effect.timeoutOption. Do not use Effect.timeoutFail.

These are not style preferences; the unavailable APIs fail at typecheck or runtime.

Good boundary suppression:

// oxlint-disable-next-line executor/no-try-catch-or-throw -- boundary: JSON.parse feeds stable IPC failure envelope
try {
  const message = JSON.parse(line);
  handleHostMessage(message);
} catch (error) {
  writeIpcMessage({ type: "failed", error: formatBoundaryError(error) });
}

Bad boundary fix: do not replace natural boundary code with fake thenables, fake error objects, promise chains that emulate try/catch, or broad helper machinery solely to make lint pass.

return makeRejectedThenable(makeErrorLike("Tool path missing"));

For Effect domain code, fix the code. For boundary code, either wrap once with Effect.try / Effect.tryPromise at the entry point or use a narrow suppression with a reason.

Fix shapes

Throw / new Error

Bad:

throw new Error("Missing source");

Good in Effect.gen:

return yield * new SourceNotFoundError({ sourceId });

Good in combinators:

Effect.fail(new SourceNotFoundError({ sourceId }));

If a third-party interface requires throwing, keep the throw at the adapter edge only and convert back into a typed failure as soon as control returns to Effect. Prefer a narrow oxlint-disable-next-line with a boundary: reason over code contortions.

Effect.fail inside generators

Prefer yielding the error directly in generator code:

return yield * new SourceNotFoundError({ sourceId });

Do not write:

return yield * Effect.fail(new SourceNotFoundError({ sourceId }));

Use Effect.fail(...) in non-generator combinator code:

Effect.flatMap(
  source,
  Option.match({
    onNone: () => Effect.fail(new SourceNotFoundError({ sourceId })),
    onSome: Effect.succeed,
  }),
);

Promise.catch / Promise.reject

Bad:

await client.close().catch(() => {});
return Promise.reject(new Error("failed"));

Good:

Effect.tryPromise({
  try: () => client.close(),
  catch: (cause) => new ClientCloseError({ cause }),
});

If the failure is intentionally ignored:

Effect.ignore(
  Effect.tryPromise({
    try: () => client.close(),
    catch: (cause) => new ClientCloseError({ cause }),
  }),
);

Effect die / orDie escape hatches

Bad in domain code:

program.pipe(Effect.orDie);
Effect.die(error);

Good:

program.pipe(Effect.mapError((cause) => new DomainError({ message: "Operation failed", cause })));

Effect.die, Effect.dieMessage, Effect.orDie, and Effect.orDieWith turn typed failures into defects. Use them only at a true runtime boundary where the host cannot represent typed failures, and keep that usage behind a narrow lint suppression with a boundary: reason. Do not use orDie to avoid threading an error type through normal Effect code.

try/catch

Bad:

try {
  return JSON.parse(text);
} catch (cause) {
  return new ParseError({ message: String(cause) });
}

Good for schema-backed input:

Schema.decodeUnknownEffect(Schema.fromJsonString(InputSchema))(text).pipe(
  Effect.mapError(() => new ParseError({ message: "Failed to parse input" })),
);

Good for non-schema throwing APIs:

Effect.try({
  try: () => new URL(value),
  catch: (cause) => new UrlParseError({ value, cause }),
});