# atom.io/foundations/overlays

Source: docs/source/pages/docs/foundations/overlays.mdx
URL: /docs/foundations/overlays

# <low-emphasis>atom.io</low-emphasis>/foundations/overlays

Overlays are source-backed collections. They let you stage changes over a source
`Map` or `Set` without mutating the source immediately.

For normal collection operations, treat `MapOverlay` like a `Map` and `SetOverlay` like
a `Set`. The important contract is the overlay behavior: where reads come from, how
deletions are tracked, and how iteration orders source entries relative to overlay-only
entries.

### map overlay
Source: docs/source/exhibits/foundations/overlays/map-overlay.ts

```ts
import { MapOverlay } from "atom.io/foundations/overlays"

const source = new Map([
	[`a`, 1],
	[`b`, 2],
])

const overlay = new MapOverlay(source)

overlay.set(`a`, 10)
overlay.set(`x`, 100)
overlay.delete(`b`)

Array.from(overlay) // [["a", 10], ["x", 100]]
source.get(`a`) // 1
```

## package contents

<table-wrapper>

| Export | Description |
| --- | --- |
| `MapOverlay` | A source-backed `Map`. |
| `SetOverlay` | A source-backed `Set`. |
| `new MapOverlay(source)` | Construct a `MapOverlay` from a source `Map`. |
| `MapOverlay.prototype.hasOwn(key)` | Check only the overlay's own staged map. |
| `MapOverlay.prototype.deleted` | A `Set` of source keys hidden by the overlay. |
| `MapOverlay.prototype.changed` | A `Set` of source keys whose values are staged in the overlay. |
| `new SetOverlay(source)` | Construct a `SetOverlay` from a source `Set`. |
| `SetOverlay.prototype.hasOwn(value)` | Check only the overlay's own staged set. |
| `SetOverlay.prototype.iterateOwn()` | Iterate only overlay-owned values. |
| `SetOverlay.prototype.source` | The source set backing the overlay. |
| `SetOverlay.prototype.deleted` | A `Set` of source values hidden by the overlay. |

</table-wrapper>

## source and overlay order

Visible source entries iterate first. Overlay-only entries come after them.

If a source entry is changed in the overlay, it keeps its source position while yielding
the overlay value.

If a source entry is deleted, it is skipped.

### source and overlay order
Source: docs/source/exhibits/foundations/overlays/source-and-overlay-order.ts

```ts
import { MapOverlay } from "atom.io/foundations/overlays"

const source = new Map([
	[`a`, 1],
	[`b`, 2],
])

const overlay = new MapOverlay(source)

overlay.set(`b`, 20)
overlay.set(`c`, 3)

Array.from(overlay) // [["a", 1], ["b", 20], ["c", 3]]

overlay.delete(`a`)

Array.from(overlay) // [["b", 20], ["c", 3]]
Array.from(source) // [["a", 1], ["b", 2]]
```

## clear and reinsert

Calling `clear()` hides all source entries and removes overlay-only entries.

If you then add a source-backed item again, it behaves like a fresh overlay insertion.
That means it appears after any earlier overlay-only insertions made after `clear`.

### clear and reinsert
Source: docs/source/exhibits/foundations/overlays/clear-and-reinsert.ts

```ts
import { SetOverlay } from "atom.io/foundations/overlays"

const source = new Set([`a`, `b`])
const overlay = new SetOverlay(source)

overlay.clear()
overlay.add(`x`)
overlay.add(`a`)

Array.from(overlay) // ["x", "a"]
overlay.deleted // Set { "b" }
Array.from(source) // ["a", "b"]
```