clo/sitegen

WIP: rework progress #48

Closed

clo wants to merge 5 commits from wip/progress into master

clo commented

2025-10-16 01:51:39 -07:00

Owner

resolves #47.
resolves #40.
should try #34

this PR reworks log and progress, and adds many more treats to make that a reality.

progress

node signaling is done by providing a progress.Root to every node,
dispatching events to it when the node changes. the root is connected to
an observer to construct a UI out of it. this commit adds two built in
observers:

attachToScreen binds a root to a TTY screen (via the log.Widget API).
the primary use of this is to implement the top level progress.start.

encodeStream converts these events into a ReadableStream. by
batching events together, the stream contents remain small, that way the
code that constructs progress nodes do not have to worry about calling
many setters at once, it gets debounced be the serializer. a server may:

const root = new progress.Root();
doActionWithProgress(root satisfies progress.Ref)
  .then(
    (result) => root.end({ success: true, result }),
    (error) => root.end({ success: false, error })
  );
if (req.headers.get("Accept").includes("application/x-clover-progress"))
  return new Response(encodeStream(root))
// to support non-streaming clients
const result = await root.once("end");
return result.success ? ... : ...;

and decodeStream on the client:

const output = document.getElementById("output");
const res = await fetch(...);
if (!res.ok) throw ...;
const root = progress.decodeStream(res.body);
output.innerHTML = progress.formatHtml(root.active);
root.on("change", () => {
  output.innerHTML = progress.formatHtml(root.active);
});
const result = await root.once("end");
output.innerText = JSON.stringify(result);

this feature is something that my work is interested in using. while
progress.ts will not be the home of a React hook -- it's trivial to
implement

resolves #47. resolves #40. should try #34 this PR reworks log and progress, and adds many more treats to make that a reality. ## progress node signaling is done by providing a `progress.Root` to every node, dispatching events to it when the node changes. the root is connected to an observer to construct a UI out of it. this commit adds two built in observers: `attachToScreen` binds a root to a TTY screen (via the log.Widget API). the primary use of this is to implement the top level `progress.start`. `encodeStream` converts these events into a `ReadableStream`. by batching events together, the stream contents remain small, that way the code that constructs progress nodes do not have to worry about calling many setters at once, it gets debounced be the serializer. a server may: ```tsx const root = new progress.Root(); doActionWithProgress(root satisfies progress.Ref) .then( (result) => root.end({ success: true, result }), (error) => root.end({ success: false, error }) ); if (req.headers.get("Accept").includes("application/x-clover-progress")) return new Response(encodeStream(root)) // to support non-streaming clients const result = await root.once("end"); return result.success ? ... : ...; ``` and `decodeStream` on the client: ```tsx const output = document.getElementById("output"); const res = await fetch(...); if (!res.ok) throw ...; const root = progress.decodeStream(res.body); output.innerHTML = progress.formatHtml(root.active); root.on("change", () => { output.innerHTML = progress.formatHtml(root.active); }); const result = await root.once("end"); output.innerText = JSON.stringify(result); ``` this feature is something that my work is interested in using. while `progress.ts` will not be the home of a React hook -- it's trivial to implement

clo added 2 commits

2025-10-16 01:51:39 -07:00