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.
import * as Progress from "gizlang/progress";Types
Kind
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
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:i64kind:stringlabel:stringdone:i64total:i64unit:stringtext:stringelapsed:i64
Work
type Work = { id: i64; label: string; unit: string; total: i64; began: i64; }Work in progress: what begin gives, to advance and to end.
id:i64label:stringunit:stringtotal:i64began:i64
Sink
type Sink = (e: Event) => voidWhere the events of a World go.
Functions
to
function to(sink: Sink): voidSends the events of this World to sink from now on.
Effects: fail, write, io, alloc.
none
function none(): WorkA work that shows nothing, for code that says its work only to some readers.
Effects: fail, io, alloc.
begin
function begin(label: string, total: i64 = 0, unit: string = ""): WorkWork label begins ("downloading model.safetensors"): total of unit ("bytes", or "" for a count) when known.
Effects: fail, read, write, console, io, alloc.
say
function say(line: string): voidA line that stays, of no work: what a tool found or chose.
Effects: fail, read, write, console, io, alloc.
bytesText
function bytesText(n: i64): stringn bytes as a person reads them: "2.8 GB", "34 MB".
Effects: fail, alloc.
timeText
function timeText(milliseconds: i64): stringA time as a person reads it: "47 s", "3 min 05 s".
Effects: fail, alloc.
amount
function amount(e: Event): stringHow 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
function format(e: Event): stringAn 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
function live(): boolWhether standard error is a terminal that redraws a line; else it is a log.
Effects: fail, read, write, console, io, alloc.
close
function close(): voidEnds 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
function terminal(e: Event, name: string = ""): voidShows 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
function Work.advance(self: Work, done: i64, total: i64 = -1): voidThe 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
function Work.done(self: Work, text: string = ""): voidThe 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
function Work.failed(self: Work, text: string = ""): voidThe work failed; text stays as its line.
Effects: fail, read, write, console, io, alloc.
Work.seconds
function Work.seconds(self: Work): i64The seconds since the work began.
Effects: fail, io, alloc.
Work.took
function Work.took(self: Work): stringThe 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.