# flagstaff/loop

> Every export of flagstaff/loop, with its signature and doc comment: hoist, manualClock, plus 5 types.

Source: https://flagstaff.interlace.tools/docs/api/loop

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

The frame loop (R1). `hoist()` raises a component, `update()` changes its state, `lower()`
takes it down and leaves the static line behind. Which of the four projections runs is the
output policy's decision (`roundel/policy`), read once from the runtime; this file never
looks at a stream's `isTTY` or an environment variable itself (U2).

```ts
import { hoist, manualClock } from 'flagstaff/loop';
```

## Functions

### hoist

Hoist a component in its initial state. Pass `{ json: true }` when the run was asked for `--json`.

```ts
function hoist<S>(component: Component<S>, rt: Runtime, initial: S, opts?: ModeOptions): Hoisted<S>;
```

| Parameter | Type |
| :-- | :-- |
| `component` | `Component<S>` |
| `rt` | `Runtime` |
| `initial` | `S` |
| `opts` (optional) | `ModeOptions` |

**Returns** `Hoisted<S>`

### manualClock

A clock that moves only when told (R9): the same frames every run, so a spinner snapshots.

```ts
function manualClock(start?: number): ManualClock;
```

| Parameter | Type |
| :-- | :-- |
| `start` (optional) | `number` |

**Returns** `ManualClock`

## Interfaces

### Clock

Time as the loop sees it: burgee's `Runtime.clock` satisfies it, so does `manualClock()`.

```ts
interface Clock {
    now(): number;
    schedule(fn: () => void, ms: number): () => void;
}
```

### Hoisted

```ts
interface Hoisted<S> {
    readonly mode: OutputMode;
    update(state: S): void;
    /** Lower the flag: the final state's static projection is what stays on screen. */
    lower(state?: S): void;
}
```

### ManualClock

```ts
interface ManualClock extends Clock {
    /** Advance by `ms`, running every callback that falls due, earliest first. */
    tick(ms: number): void;
}
```

### Runtime

What the loop needs from the world: the policy's slice plus the two streams and a clock.

```ts
interface Runtime extends PolicyRuntime {
    stdout: Writer;
    stderr: Writer;
    clock: Clock;
}
```

### Writer

```ts
interface Writer {
    write(chunk: string): unknown;
}
```