GizStack
View .mdOpen in ChatGPTOpen in Claude

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.