# gizlang/progress

what long work is doing, said in one way by every part of a program. Code that waits for seconds (a download, a conversion, a build, a wait for a lock) begins a Work, advances it and ends it; it never writes to the terminal itself. The events go to the sink of the World (`to`), which is the terminal when none is set: - On a terminal the work in progress is one line that redraws in place: a spinner, the label, a bar with the amount, the rate and the time left, and the time it has taken. A thread of its own draws it, so it moves while the World computes. The line goes away when the work ends, and the text the work ends with stays as one line (of a work of a second or more, or one that failed). - In a log (standard error is a file or a pipe, TERM is dumb, or GIZLANG_PROGRESS=plain) each work is one line when it begins and one when it ends with a text. Nothing redraws. A program with its own readers (an app whose page shows the work) sets a sink and gives each event to them (`format`), and to `terminal` as well when its terminal is to show it too.

```gizlang
import * as Progress from "gizlang/progress";
```

## Types

### `Kind`

```gizlang
type Kind = "begin" | "advance" | "done" | "failed" | "note"
```

What an event says of its work: it began, it came further, it ended well ("done") or not ("failed"); "note" is a
line of no work.

### `Event`

```gizlang
type Event = { work: i64; kind: Kind; label: string; done: i64; total: i64; unit: string; text: string; elapsed: i64; }
```

One event of work `work` (0: a note): its label, how far it is (`done` of `total`; a total of 0 is not known) in
`unit` ("bytes", or "" for a count), the text it ends with or the note's line, and the milliseconds since it
began.

- `work`: `i64`
- `kind`: `string`
- `label`: `string`
- `done`: `i64`
- `total`: `i64`
- `unit`: `string`
- `text`: `string`
- `elapsed`: `i64`

### `Work`

```gizlang
type Work = { id: i64; label: string; unit: string; total: i64; began: i64; }
```

Work in progress: what `begin` gives, to advance and to end.

- `id`: `i64`
- `label`: `string`
- `unit`: `string`
- `total`: `i64`
- `began`: `i64`

### `Sink`

```gizlang
type Sink = (e: Event) => void
```

Where the events of a World go.

## Functions

### `to`

```gizlang
function to(sink: Sink): void
```

Sends the events of this World to `sink` from now on.

Effects: fail, write, io, alloc.

### `none`

```gizlang
function none(): Work
```

A work that shows nothing, for code that says its work only to some readers.

Effects: fail, io, alloc.

### `begin`

```gizlang
function begin(label: string, total: i64 = 0, unit: string = ""): Work
```

Work `label` begins ("downloading model.safetensors"): `total` of `unit` ("bytes", or "" for a count) when known.

Effects: fail, read, write, console, io, alloc.

### `say`

```gizlang
function say(line: string): void
```

A line that stays, of no work: what a tool found or chose.

Effects: fail, read, write, console, io, alloc.

### `bytesText`

```gizlang
function bytesText(n: i64): string
```

`n` bytes as a person reads them: "2.8 GB", "34 MB".

Effects: fail, alloc.

### `timeText`

```gizlang
function timeText(milliseconds: i64): string
```

A time as a person reads it: "47 s", "3 min 05 s".

Effects: fail, alloc.

### `amount`

```gizlang
function amount(e: Event): string
```

How far an event's work is, without its label: "1.2 of 2.8 GB · 43%", "120 of 400", or "" when it has no amount.

Effects: fail, alloc.

### `format`

```gizlang
function format(e: Event): string
```

An event as one line of text for any reader (a page, a log): the label and how far it is, or the text it ends
with.

Effects: fail, alloc.

### `live`

```gizlang
function live(): bool
```

Whether standard error is a terminal that redraws a line; else it is a log.

Effects: fail, read, write, console, io, alloc.

### `close`

```gizlang
function close(): void
```

Ends every work this World shows on the terminal, with no line: before the process ends or becomes another
program, whose output starts on a clean line.

Effects: fail, read, write, console, io, alloc.

### `terminal`

```gizlang
function terminal(e: Event, name: string = ""): void
```

Shows an event on standard error, as the head of this module says: the sink of a World that sets none. `name`, when
given, begins each line that stays ("giz: ..."), as a tool names itself.

Effects: fail, read, write, console, io, alloc.

## Methods

### `Work.advance`

```gizlang
function Work.advance(self: Work, done: i64, total: i64 = -1): void
```

The work has come to `done` (of `total` when it is given). Call it as often as the work steps: a redraw is made at
most every 50 ms.

Effects: fail, read, write, console, io, alloc.

### `Work.done`

```gizlang
function Work.done(self: Work, text: string = ""): void
```

The work ended well. `text` stays as its line ("built the web library unit in 11 s"); "" keeps none.

Effects: fail, read, write, console, io, alloc.

### `Work.failed`

```gizlang
function Work.failed(self: Work, text: string = ""): void
```

The work failed; `text` stays as its line.

Effects: fail, read, write, console, io, alloc.

### `Work.seconds`

```gizlang
function Work.seconds(self: Work): i64
```

The seconds since the work began.

Effects: fail, io, alloc.

### `Work.took`

```gizlang
function Work.took(self: Work): string
```

The time since the work began as a person reads it ("11 s", "3 min 05 s"), for the text it ends with.

Effects: fail, io, alloc.

