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