1# notable changes in clover's typescript library
2
3## v8
4
5### breaking
6
7- `subprocess` is rewritten around web streams.
8- `queue.Job`'s cancellation option is renamed to `causeCancellations`.
9
10### features
11
12- new library `repl`: an interactive prompt to add to long running programs.
13- `incremental`, a foundation for incremental build tools, such as sitegen in
14 paperclover.net. a build is isolated into cache boundaries called "steps",
15 with tools to trace dependencies of each step's inputs.
16- `incremental.trackSqlite`, which makes the rows a step reads from a
17 `node:sqlite` connection inputs of that step.
18- `incremental.serve`, which serves what a graph builds, with a debugger in the
19 pages this machine asks for: each build's status, progress, and errors, and
20 the graph of its steps.
21- `stream.lines` reads a byte stream as lines of text.
22- `subprocess.launchEditor` shows a file in the editor the user has open, at a
23 line and column, ported from vite's `launch-editor`.
24- `subprocess.spawn`'s `shell` option runs a command through the system shell.
25- `subprocess`'s `progress` option hands a `progress.Ref` to a child process,
26 which becomes the global root of `progress` there. the child's global log is
27 written by the parent as well. `progress.childEnv` and `progress.attachChild`
28 are the two halves, for spawning by other means.
29- `log`
30 - widgets can now read keyboard input.
31 - finally fixes resize corruptions for long running widgets
32- `string/ansi`: add `inverse`, `resetInverse`, and `cursorHome`.
33- `meta` auto-embed will now set `twitter:url`.
34- `meta.discord` adds a Discord component embed, inline or as a link to its
35 json. Components are Discord's own json with `type` named (`"container"`,
36 `"section"`, `"text"`, ...), or a number for any other. `meta.discordProblems`
37 checks a payload against the rules that make Discord leave an embed out.
38 `meta.readTags` reads the tags of a parsed document and `meta.scrape` reads
39 them back into what they say, which the `incremental/visualization` `meta` tab
40 uses to draw the Discord and Twitter cards of a page.
41- `progress.attachToDocument` draws progress in the browser, and
42 `progress.formatHtml` renders the same markup for server rendering.
43- `ts.DeepReadonly`
44
45### fixes
46
47- `async.DedupeConcurrent` no longer causes unhandled rejections with correct
48 caller error handling.
49- `progress`: `StartOptions.messages` is no longer ignored, so a decoded stream
50 keeps the logs that a node had when it started.
51- `progress`: the byte stream keeps partial writes (`node.log.write`) apart from
52 log messages, and the terminal no longer draws a hidden top-level node.
53- `Events`: disposing a listener no longer removes the listeners added after it.
54
55## v7
56
57### features
58
59- `meta`'s auto-embed feature now sets all the twitter tags, not just thumbnail.
60 sorry i might have been dumb when doing the first version of this.
61
62### fixes
63
64- `Lru`: `delete()` and `clear()` now call the `delete` callback, as documented.
65- `http.parseRangeHeader` accepts open and suffix ranges (`500-`, `-500`),
66 clamps ranges to the resource, and returns an empty array when none of them
67 can be satisfied.
68- `http.serve` cancels the response body when the client disconnects, and a
69 failing body closes the connection instead of crashing the process.
70
71## v6
72
73### breaking
74
75- `meta` fields now distinguishes `undefined` and `null`. `null` acts as "unset"
76 and `undefined` acts as "fallthru to template".
77- rename `error` to `exception`
78
79### features
80
81- `meta`
82 - `title` can be optional for composition reasons.
83 - `embed.thumbnailAlt` sets `og:image:alt` + `twitter:image:alt`.
84 - emits `og:*` tags with `property=` instead of `name=`.
85
86## v5
87
88### breaking
89
90- `render` has been deleted because it was not being used anymore. sad day
91 because i will never get to prove how easy it is to write a stable Suspense
92 and PPR implementations in less than 300 lines each.
93 - deprecated html escaping methods moved to `string.escapeHtmlContent` and
94 `string.escapeHtmlAttr`
95- `render/meta` is moved to `meta`, with a new API for rendering tags
96 - `meta.render` is renamed to `meta.toHtml`, arguments re-ordered
97 - `meta.toTags` creates an object compatible with TanStack Router
98 - the `extra` object now takes an array of React-like elements among some
99 other supported forms.
100- `log` and `progress` have received so many bug-fix changes that it is worth
101 ensuring your application edge cases still work as expected.
102- `string.formatByteSize` formats differently.
103
104### features
105
106- new library `http`.
107- new library `math`.
108- new library `arrays`.
109- `log`
110 - many many many many rendering bug-fixes
111 - `writeError` writes to stderr with proper logic.
112 - buffering auto-flushes synchronously when it grows past 64k.
113 - custom scopes
114- `string`
115 - `formatDurationLetters` spans years to seconds, plus infinity and negatives.
116- `mime`'s database contains `.eot` for embedded opentype fonts.
117- `async.deferred`.
118- `queue.setConcurrency`.
119- `subprocess.lookupProcessOnPort`.
120- `subprocess/ffmpeg` progress handles fractional framerates (progress bug).
121- `string/ansi` gains `clearToEndOfScreen`.
122- `progress` estimation, maxHeight, and timer bug fixes.
123
124## v4
125
126### breaking
127
128- the `.ts` suffix in the module name has been dropped
129- `log`
130 - rename `writeLine` to `writeOutput` and `writeError`
131 - `startWidget` returns `null` if the host is incapable of it
132 - it also no longer takes `onChange`. call `redraw` on the returned
133 `WidgetInstance`.
134 - rename `HeadlessWidgetHost` to `WidgetHost`
135 - rename `headlessWidgetHost` to `createTerminalWidgetHost`
136 - rename `HeadlessWidgetEnv` to `TerminalWidgetHostOptions`
137 - rename `replaceGlobalDestination` to `replaceGlobalMessageDestination`
138 - rename `formatMessage` to `formatAnsiMessage`
139 - `WidgetHostOptions` now takes a `lockTerminal` function instead of
140 `writeInteractive`/`writeOutput` directly. the locking function returns an
141 interface with these functions, which better aligns with how the draw lock
142 actually works. additionally, this allows writing more accurate tty bindings
143 for non-node.js runtimes. the reason for these changes is to support
144 partially written lines, and handle when external sources desire to do the
145 same.
146 - in `getDrawLock`, new required argument `mode`, which can be set to `short`
147 or `long` to affect how synchronization works. releasing the lock requires
148 you to give some information about where the cursor was moved to.
149- `string/ansi`
150 - rename `trimToWidth` to `trimForTerminal`
151
152deprecations without removals:
153
154- `render.ts` will be deleted with no replacement. in the downstream `sitegen`
155 project, the codebase is moving to Marko after depending on both renderers.
156
157### features
158
159- you can write `log` messages without a newline. on older libraries, this will
160 show up as a newline per message since that version was not capable of
161 displaying it. but done not as a breaking change.
162- `process.{stdout,stderr}.write` is intercepted to avoid log interweaving with
163 `log.ts`/`progress.ts`. this is only done when a widget is created (for
164 example, calling `progress.start`), so patches are not applied when not
165 needed. if patching globals is undesirable, you can use an alternative widget
166 host by calling
167 `log.replaceGlobalWidgetHost(log.simpleNodeProcessWidgetHost(process))`
168- `log.startWidget` returns a `WidgetInstance`, including a mutable `fps`
169 property.
170- `progress.ts` node gains `node.log.write("word ");` to write a message without
171 a newline.
172- `async.delay` handles timers longer than 23 days and `Infinity`.
173- `Lru.revive` receives bug fixes. this function previously didn't really work.
174- `ansi` gets more cursor control constants
175
176## v3
177
178### breaking
179
180- `log` dispatching reworked
181 - delete `log/headless.ts` by moving it into `log`
182 - headless scopes now emit `log.Message` objects instead of ANSI text,
183 templating is done in the consumer of the headless logging scope.
184 - rename `HeadlessWidgetEnv.wait` to `delay`, matching `async.delay`
185- `progress` had everything besides `start` and `Node` heavily altered
186 - promote to top level namespace `lib/progress.ts`
187 - `Node.estimate` -> `Node.total`
188 - rename `.null` to `.nullNode`
189 - `.SortNode` -> `.ReadOnlyNode`
190 - `.getUnicodeBar` -> `.formatUnicodeBar`
191 - rework headless rendering story, rename `.Headless` -> `.Root`
192 - `.rootFromWidgetHost` to source from a widget host
193 - remove `.internals`, use `.Root`
194- deleted `assert.FINITE`
195
196### features
197
198- `progress` has expanded documentation and use cases.
199 - create headless nodes with `Root` (subclass of `Events`)
200 - streaming over the wire via `encodeEventStream`, `encodeEventStream`,
201 `encodeByteStream`, `encodeByteStream`. these APIs produce JSON and Binary
202 `ReadableStream`s. with work to make `log` better supported in the browser,
203 progress streams are fully consumable from within a web browser.
204 - `.attach` to display a decoded root
205 - expose `.formatAnsi` for external use
206- `log` slowly moves towards maturity
207 - add `.tee` (and `log.Scope.tee`)
208 - in Node.js, `log` will inject into `console.*` to prevent interweaving logs
209 with widget output text. this injection is enabled regardless of if widgets
210 are actually running, but do not otherwise change their behavior.
211 - `log` scopes render differently in the terminal now
212 - browser support by calling the correct `console` api to signal warnings and
213 errors correctly.
214 - fix assertion failure when creating a widget in the same frame a log message
215 is written.
216- new library `Events.ts`
217- new library `bytes.ts` (subject to being moved as it is one function)
218- new library `stream.ts`
219- new library `testing.ts`
220- `string`
221 - add `encodeUtf8` and `decodeUtf8`
222 - add `formatByteSize` and `formatBinaryByteSize` and `formatDurationLetters`,
223 all subject to change as `progress` is used more.
224- `async`
225 - add `.Cancelable` type, constructed with `.makeCancelable`
226 - add `.delay`
227- `ts`
228 - add `EmptyObject`
229 - add `Json`, `ToJson`, and `JsonValue`
230 - add `mixin`
231
232## v2
233
234### breaking
235
236- rework `log.Scope`, remove self call signature so that the `log` module
237 satisfies `log.Scope`, while adding `log` and `debug` for explicit debugging
238 logs. documentation prescribes doing `const console = log.scope("module");`.
239- remove `packaging.ts`
240- move `log/ansi.ts` into `string/ansi.ts`
241- move ansi related `string.ts` functions into `string/ansi.ts`
242
243### features
244
245- top level readme now explains general usage patterns. more docs overall.
246- new library `async.ts`
247- new library `Lru.ts`
248- new library `mime.ts`
249- new library `render.ts`, `render/jsx-runtime.ts`, `render/meta.ts`
250- new library `node.ts`
251- new library `subprocess.ts`, `subprocess/ffmpeg.ts`
252- add `string.escapeRegExp()`
253- add `stack.capture()`
254
255## v1
256
257- new library `assert.ts`
258- new library `log.ts`
259- new library `packaging.ts`
260- new library `queue.ts`
261- new library `string.ts`
262- new library `ts.ts`