# @effectionx/scope-eval

> Evaluate operations in a scope while retaining resources across evaluations

Latest version **0.1.3** (published 2026-03-22) · MIT license · 0 weekly downloads

## Install

```sh
npm install @effectionx/scope-eval
pnpm add @effectionx/scope-eval
yarn add @effectionx/scope-eval
bun add @effectionx/scope-eval
```

## Health

**Score 65/100 (B)** — status: stable.

Positive: has types; esm support; no vulnerabilities; has provenance; high maintenance score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.1.3 |
| Published | 2026-03-22 |
| First published | 2026-02-05 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 68.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 12 |
| Author | engineering@frontside.com |
| Maintainers | frontsidejack |
| Keywords | effection, effectionx, concurrency, scope, eval, repl |

## Links

- npm: https://www.npmjs.com/package/@effectionx/scope-eval
- Repository: https://github.com/thefrontside/effectionx
- Homepage: https://github.com/thefrontside/effectionx#readme
- Issues: https://github.com/thefrontside/effectionx/issues
- npm.io page: https://npm.io/package/@effectionx/scope-eval

## Recent versions

- 0.1.3 (latest) — 2026-03-22
- 0.1.2 — 2026-02-23
- 0.1.1 — 2026-02-17
- 0.1.0 — 2026-02-05

## README

# @effectionx/scope-eval

Evaluate Effection operations in a scope while retaining resources.

---

While `Scope.run` and `Scope.spawn` can evaluate operations in isolated scopes, resources are torn down once operations return. `useEvalScope` allows you to invoke operations in an existing scope, receive the result of evaluations, while retaining resources for the lifecycle of that scope.

## Usage

### useEvalScope

Create a scope that evaluates operations and retains their resources:

```typescript
import { main, createContext } from "effection";
import { useEvalScope } from "@effectionx/scope-eval";

await main(function*() {
  const context = createContext<string>("my-context");

  const evalScope = yield* useEvalScope();

  // Context not set yet
  evalScope.scope.get(context); // => undefined

  // Evaluate an operation that sets context
  yield* evalScope.eval(function*() {
    yield* context.set("Hello World!");
  });

  // Now the context is visible via the scope
  evalScope.scope.get(context); // => "Hello World!"
});
```

### Error Handling

Operations are executed safely and return a `Result<T>`:

```typescript
import { main } from "effection";
import { useEvalScope } from "@effectionx/scope-eval";

await main(function*() {
  const evalScope = yield* useEvalScope();

  const result = yield* evalScope.eval(function*() {
    throw new Error("something went wrong");
  });

  if (result.ok) {
    console.log("Success:", result.value);
  } else {
    console.log("Error:", result.error.message);
  }
});
```

### box / unbox

Utilities for capturing operation results as values:

```typescript
import { main } from "effection";
import { box, unbox } from "@effectionx/scope-eval";

await main(function*() {
  // Capture success or error as a Result
  const result = yield* box(function*() {
    return 42;
  });

  // Extract value (throws if error)
  const value = unbox(result); // => 42
});
```

## API

### `useEvalScope(): Operation<EvalScope>`

Creates an isolated scope for evaluating operations.

Returns an `EvalScope` with:
- `scope: Scope` - The underlying Effection scope for inspecting context
- `eval<T>(op: () => Operation<T>): Operation<Result<T>>` - Evaluate an operation

### `box<T>(content: () => Operation<T>): Operation<Result<T>>`

Execute an operation and capture its result (success or error) as a `Result<T>`.

### `unbox<T>(result: Result<T>): T`

Extract the value from a `Result<T>`, throwing if it's an error.

## Use Cases

- **Testing**: Evaluate operations and inspect context/state without teardown
- **Resource retention**: Keep resources alive across multiple evaluations
- **Error boundaries**: Safely execute operations that might fail

---
_Source: https://npm.io/package/@effectionx/scope-eval · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._