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

Set helpers.

All helpers return readonly sets for safety. Native Set methods like `add()`
and `delete()` mutate the original — use [addToSet](https://evolu.dev/docs/api-reference/common/Set/functions/addToSet) and
[deleteFromSet](https://evolu.dev/docs/api-reference/common/Set/functions/deleteFromSet) instead for immutable operations that return new sets.

Use [isNonEmptySet](https://evolu.dev/docs/api-reference/common/Set/functions/isNonEmptySet) to narrow to [NonEmptyReadonlySet](https://evolu.dev/docs/api-reference/common/Set/type-aliases/NonEmptyReadonlySet) before
calling functions like [firstInSet](https://evolu.dev/docs/api-reference/common/Set/functions/firstInSet) that require a non-empty set.

### Composing immutable and native operations

```ts
import {
  addToSet,
  assertEqual,
  deleteFromSet,
  filterSet,
  firstInSet,
  isNonEmptySet,
  mapSet,
} from "@evolu/common";

const values = addToSet(new Set([1, 2]), 3);
const withoutOne = deleteFromSet(values, 1);
const doubled = mapSet(withoutOne, (x) => x * 2);
const atLeastFour = filterSet(doubled, (x) => x >= 4);

// Evolu's readonly results compose with native Set operations.
const union = atLeastFour.union(new Set([6, 8]));
const intersection = union.intersection(new Set([4, 6, 8, 10]));
const difference = intersection.difference(new Set([4]));

if (!isNonEmptySet(difference)) throw new Error("Expected values");
assertEqual(firstInSet(difference), 6);
```

## Types

| Type Alias                                                                                 | Description                                                         |
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
| [NonEmptyReadonlySet](https://evolu.dev/docs/api-reference/common/Set/type-aliases/NonEmptyReadonlySet) | A readonly set with at least one element (branded for type safety). |

## Constants

| Variable                                                          | Description            |
| ----------------------------------------------------------------- | ---------------------- |
| [emptySet](https://evolu.dev/docs/api-reference/common/Set/variables/emptySet) | An empty readonly set. |

## Constructors

| Function                                                            | Description                           |
| ------------------------------------------------------------------- | ------------------------------------- |
| [createSet](https://evolu.dev/docs/api-reference/common/Set/functions/createSet) | Creates a readonly set from an array. |

## Type guards

| Function                                                                    | Description                                                                                                                                      |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| [isNonEmptySet](https://evolu.dev/docs/api-reference/common/Set/functions/isNonEmptySet) | Checks if a set is non-empty and narrows its type to [NonEmptyReadonlySet](https://evolu.dev/docs/api-reference/common/Set/type-aliases/NonEmptyReadonlySet). |

## Transformations

| Function                                                                    | Description                                                                           |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| [addToSet](https://evolu.dev/docs/api-reference/common/Set/functions/addToSet)           | Returns a new readonly set with an item added.                                        |
| [deleteFromSet](https://evolu.dev/docs/api-reference/common/Set/functions/deleteFromSet) | Returns a new readonly set with an item removed.                                      |
| [filterSet](https://evolu.dev/docs/api-reference/common/Set/functions/filterSet)         | Filters a set using a predicate or refinement function, returning a new readonly set. |
| [mapSet](https://evolu.dev/docs/api-reference/common/Set/functions/mapSet)               | Maps a set using a mapper function, returning a new readonly set.                     |

## Accessors

| Function                                                              | Description                                                        |
| --------------------------------------------------------------------- | ------------------------------------------------------------------ |
| [firstInSet](https://evolu.dev/docs/api-reference/common/Set/functions/firstInSet) | Returns the first element of a non-empty set (by insertion order). |