[API reference](https://evolu.dev/docs/api-reference) › [@evolu/common](https://evolu.dev/docs/api-reference/common) › Option

Optional value container.

Distinguishes absence from values like `null` or `undefined`.

Use Option when the value itself can be `null` or `undefined`. For APIs where
`null` means "not found", just use `T | null` directly.

### Example

```ts
// A cache that can store any value, including null and undefined
const cache = new Map<string, Option<unknown>>();

const get = (key: string): Option<unknown> => cache.get(key) ?? none;

cache.set("a", some(null)); // Stored null
cache.set("b", some(undefined)); // Stored undefined

isSome(get("a")); // true — value is null
isSome(get("b")); // true — value is undefined
isNone(get("c")); // true — key doesn't exist
```

## Utilities

| Type Alias                                                                    | Description                                                                                                                                                           |
| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [InferOption](https://evolu.dev/docs/api-reference/common/Option/type-aliases/InferOption) | Extracts the value type from an [Option](https://evolu.dev/docs/api-reference/common/Option/type-aliases/Option) or [Some](https://evolu.dev/docs/api-reference/common/Option/interfaces/Some). |

## Functions

| Function                                                                     | Description                                                                                          |
| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| [fromNullable](https://evolu.dev/docs/api-reference/common/Option/functions/fromNullable) | Converts a nullable value to an [Option](https://evolu.dev/docs/api-reference/common/Option/type-aliases/Option). |
| [isNone](https://evolu.dev/docs/api-reference/common/Option/functions/isNone)             | Type guard for [None](https://evolu.dev/docs/api-reference/common/Option/interfaces/None).                        |
| [isSome](https://evolu.dev/docs/api-reference/common/Option/functions/isSome)             | Type guard for [Some](https://evolu.dev/docs/api-reference/common/Option/interfaces/Some).                        |
| [some](https://evolu.dev/docs/api-reference/common/Option/functions/some)                 | Creates a [Some](https://evolu.dev/docs/api-reference/common/Option/interfaces/Some).                             |

## Interfaces

| Interface                                                     | Description                                                                              |
| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| [None](https://evolu.dev/docs/api-reference/common/Option/interfaces/None) | Absent value in an [Option](https://evolu.dev/docs/api-reference/common/Option/type-aliases/Option).  |
| [Some](https://evolu.dev/docs/api-reference/common/Option/interfaces/Some) | Present value in an [Option](https://evolu.dev/docs/api-reference/common/Option/type-aliases/Option). |

## Type Aliases

| Type Alias                                                          | Description     |
| ------------------------------------------------------------------- | --------------- |
| [Option](https://evolu.dev/docs/api-reference/common/Option/type-aliases/Option) | Optional value. |

## Variables

| Variable                                                     | Description                                                                    |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------ |
| [none](https://evolu.dev/docs/api-reference/common/Option/variables/none) | Shared [None](https://evolu.dev/docs/api-reference/common/Option/interfaces/None) instance. |