# atom.io/foundations/future

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

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

`Future` is a `Promise` whose pending value can be replaced.

It gives callers a stable promise reference while allowing the producer to replace the
async work that should resolve it.

### replace pending work
Source: docs/source/exhibits/foundations/future/replace-pending-work.ts

```ts
import { Future } from "atom.io/foundations/future"

const slow = new Promise<string>((resolve) => {
	setTimeout(() => {
		resolve(`slow`)
	}, 1000)
})

const result = new Future(slow)

result.use(Promise.resolve(`fast`))

const text = await result
```

In the example, `result` starts by following the slow promise. Calling `use` replaces
that pending work with a faster promise. `await result` resolves to `"fast"`, and the
later slow result is ignored.

## package contents

<table-wrapper>

| Export | Description |
| --- | --- |
| `Future` | A `Promise` subclass whose active pending work can be replaced. |
| `new Future(executorOrPromise)` | Construct a `Future` from a promise or from a promise executor. |
| `Future.prototype.use(value)` | Replace the active pending work with a promise, or resolve immediately with a direct value. |
| `Future.prototype.done` | Starts as `false` and becomes `true` when the active promise settles. |

</table-wrapper>

Construct a `Future` from a promise or from a promise executor.

### constructor
Source: docs/source/exhibits/foundations/future/constructor.ts

```ts
import { Future } from "atom.io/foundations/future"

const fromPromise = new Future(Promise.resolve(1))

const fromExecutor = new Future<number>((resolve) => {
	resolve(1)
})
```