effect-facet-unstable-reactivity-asyncresult

name: effect-facet-unstable-reactivity-asyncresult description: Guidance for facet effect/unstable/reactivity/AsyncResult focused on APIs like map, fail, and failure. Load after effect-skill-router when this facet is the primary owner.

Effect Facet unstable/reactivity/AsyncResult

Owned scope

• Owns only effect/unstable/reactivity/AsyncResult.
• Parent module: effect/unstable/reactivity.
• Source anchor: packages/effect/src/unstable/reactivity/AsyncResult.ts.

What it is for

• Module-specific APIs and usage patterns for Effect programs.

API quick reference

• map
• fail
• failure
• Failure
• flatMap
• fromExit
• getOrElse
• getOrThrow
• failureWithPrevious
• failWithPrevious
• fromExitWithPrevious
• isFailure
• isInitial
• isSuccess
• isWaiting
• isNotInitial
• all
• isAsyncResult
• Full API list: references/api-reference.md

How to use it

• Start with constructor-style APIs to build values/services before composing operations.
• Prefer pipe-based composition to keep transformations explicit and testable.
• Treat stateful APIs as synchronization boundaries and keep updates atomic.
• Keep runtime/execute APIs at edges; compose pure transformations before execution.
• Assume unstable APIs can evolve quickly; isolate usage behind thin local adapters.

Starter example

import { AsyncResult } from "effect/unstable/reactivity/AsyncResult";

const value = AsyncResult.fromExit();
const next = AsyncResult.map(value);

Common pitfalls

• Concurrency helpers can hide ordering/cancellation behavior; test interruption and race paths.
• Unstable module contracts may change; avoid coupling core app logic directly to experimental details.

Not covered here

• Sibling facets under the same parent are out of scope:
  • effect-facet-unstable-reactivity-atom (effect/unstable/reactivity/Atom)
  • effect-facet-unstable-reactivity-atomhttpapi (effect/unstable/reactivity/AtomHttpApi)
  • effect-facet-unstable-reactivity-atomref (effect/unstable/reactivity/AtomRef)
  • effect-facet-unstable-reactivity-atomregistry (effect/unstable/reactivity/AtomRegistry)
  • effect-facet-unstable-reactivity-atomrpc (effect/unstable/reactivity/AtomRpc)
  • effect-facet-unstable-reactivity-hydration (effect/unstable/reactivity/Hydration)
  • effect-facet-unstable-reactivity-reactivity (effect/unstable/reactivity/Reactivity)
• Parent module ownership belongs to effect-module-unstable-reactivity.

Escalate to

• effect-module-unstable-reactivity for parent module-wide workflows.
• effect-skill-router for cross-module routing and ownership checks.

Reference anchors

• Facet source: packages/effect/src/unstable/reactivity/AsyncResult.ts
• Parent tests: packages/effect/test/reactivity/AsyncResult.test.ts
• Parent tests: packages/effect/test/reactivity/Atom.test.ts
• API details: references/api-reference.md
• Usage notes: references/usage-reference.md
• Ownership mapping: references/owner.md