> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lionlang.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript types and error classes

> Complete reference for EvaluateResult, ArgumentMismatchError, InvalidFunctionCallError, LionEnvironmentService, and the getService utility.

Lion's type system is built on [Effect](https://effect.website) and exposes a small set of types and tagged error classes that flow through every evaluation. Understanding these lets you handle errors precisely and compose Lion evaluation with your own Effect-based code.

## `EvaluateResult`

**From `@lionlang/core/types/evaluation`**

```typescript theme={null}
import type { EvaluateResult } from "@lionlang/core/types/evaluation";
```

The return type shared by `evaluate` and every special form handler:

```typescript theme={null}
type EvaluateResult = Effect.Effect<
  unknown,
  ParseError | ArgumentMismatchError | InvalidFunctionCallError,
  LionEnvironmentService
>
```

<ResponseField name="Success" type="unknown">
  The evaluated Lion value. The type is `unknown` because Lion expressions can
  produce any JSON-compatible value, a JavaScript function (from `lambda`), or
  any host value that was placed in the environment.
</ResponseField>

<ResponseField name="Error" type="ParseError | ArgumentMismatchError | InvalidFunctionCallError">
  A union of the three error types that can occur during evaluation. All three
  are typed so you can handle them selectively with `Effect.catchTag` or
  `Effect.catchAll`.
</ResponseField>

<ResponseField name="Requirements" type="LionEnvironmentService">
  The Effect context dependency. `evaluate` requires this service to resolve
  environment references and to support `define`. `run` fulfills this
  requirement automatically, so the Effect it returns has `never` as its
  requirements type.
</ResponseField>

***

## `ArgumentMismatchError`

**From `@lionlang/core/errors/evaluation`**

```typescript theme={null}
import { ArgumentMismatchError } from "@lionlang/core/errors/evaluation";
```

A tagged error class raised when a standard library function receives arguments of the wrong type.

```typescript theme={null}
export class ArgumentMismatchError extends Schema.TaggedError<ArgumentMismatchError>(
  "ArgumentMismatchError"
)("ArgumentMismatchError", {}) {}
```

<ResponseField name="_tag" type="&#x22;ArgumentMismatchError&#x22;">
  The discriminant tag. Use `Effect.catchTag("ArgumentMismatchError", ...)` to
  handle this error selectively.
</ResponseField>

### Handling example

```typescript theme={null}
import { Effect } from "effect";
import { run } from "@lionlang/core/evaluation/evaluate";
import { stdlib } from "@lionlang/core/modules";

const result = await Effect.runPromise(
  Effect.catchTag(
    run(["number/add", "hello", 1], stdlib),
    "ArgumentMismatchError",
    (_err) => Effect.succeed(null)
  )
);
```

***

## `InvalidFunctionCallError`

**From `@lionlang/core/errors/evaluation`**

```typescript theme={null}
import { InvalidFunctionCallError } from "@lionlang/core/errors/evaluation";
```

Raised when an array expression's head does not resolve to a callable value after evaluation.

```typescript theme={null}
export class InvalidFunctionCallError extends Schema.TaggedError<InvalidFunctionCallError>(
  "InvalidFunctionCallError"
)("InvalidFunctionCallError", { expression: LionExpressionSchema }) {}
```

<ResponseField name="_tag" type="&#x22;InvalidFunctionCallError&#x22;">
  The discriminant tag. Use `Effect.catchTag("InvalidFunctionCallError", ...)`
  to handle this error selectively.
</ResponseField>

<ResponseField name="expression" type="LionExpressionType">
  The array expression that triggered the error. Inspect this field to identify
  which expression head failed to resolve to a function.
</ResponseField>

### Handling example

```typescript theme={null}
import { Effect } from "effect";
import { run } from "@lionlang/core/evaluation/evaluate";
import { stdlib } from "@lionlang/core/modules";

const result = await Effect.runPromise(
  Effect.catchTag(
    run(["not-a-function", 1, 2], stdlib),
    "InvalidFunctionCallError",
    (err) => {
      console.error("Bad call:", JSON.stringify(err.expression));
      return Effect.succeed(null);
    }
  )
);
```

***

## `LionEnvironmentService`

**From `@lionlang/core/services/evaluation`**

```typescript theme={null}
import { LionEnvironmentService } from "@lionlang/core/services/evaluation";
```

An Effect `Context.Tag` that carries the active `Environment` through the evaluation pipeline.

```typescript theme={null}
export class LionEnvironmentService extends Context.Tag(
  "LionEnvironmentService"
)<LionEnvironmentService, Environment>() {}
```

<ResponseField name="Tag identifier" type="&#x22;LionEnvironmentService&#x22;">
  The string identifier used by Effect's context system to locate the service.
</ResponseField>

<ResponseField name="Service value" type="Environment">
  The `Environment` instance holding the mutable bindings `Ref` and,
  for inner scopes, a reference to the parent environment.
</ResponseField>

<Note>
  Callers using `run` do not need to interact with `LionEnvironmentService`
  directly — `run` provisions it automatically from the `environment` argument.
  You only need this tag when composing `evaluate` manually or writing a custom
  special form handler that needs to read or modify the environment.
</Note>

***

## `getService`

**From `@lionlang/core/services/evaluation`**

```typescript theme={null}
import { getService } from "@lionlang/core/services/evaluation";
```

A convenience utility for retrieving a typed service from the Effect context:

```typescript theme={null}
export const getService = <T, U>(context: Context.Tag<T, U>) =>
  pipe(Effect.context<T>(), Effect.map(Context.get(context)));
```

Used internally by `evaluatePrimitive` and the special form handlers to access the current `LionEnvironmentService`:

```typescript theme={null}
const environment = await Effect.runPromise(
  pipe(
    getService(LionEnvironmentService),
    Effect.provideServiceEffect(LionEnvironmentService, makeEnvironment({}))
  )
);
```