authorgravatar for git@paperclover.netclover caruso <git@paperclover.net> 2025-10-15 23:36:01-07:00
committergravatar for git@paperclover.netclover caruso <git@paperclover.net> 2026-01-14 01:08:14-08:00
logd1a62aed37dbf7c17fde800dc898d7b41ab56481
tree3c2a73392ba5fc7400aea9a562245eb3c27459b1
parent091ae47eb0350ab7692699ca2914617cb03a31e1
signature Commit is signed but in an unrecognized format.

chore(lib): adjust comments

3 files changed, 24 insertions(+), 19 deletions(-)

lib/Lru.ts+16-15
...@@ -1,4 +1,5 @@...@@ -1,4 +1,5 @@
1/**1/**
2 * Least-recently-used cache.
2 * This module is intended to be imported via the main class.3 * This module is intended to be imported via the main class.
3 *4 *
4 * import { Lru } from '@clo/lib/Lru';5 * import { Lru } from '@clo/lib/Lru';
...@@ -12,19 +13,19 @@...@@ -12,19 +13,19 @@
12interface Options<K, V> {13interface Options<K, V> {
13 capacity: number;14 capacity: number;
14 /**15 /**
15 * Decide how many units of size each entry takes.16 * decide how many units of size each entry takes.
16 * For example, accessing `.byteLength` of a Buffer.17 * For example, accessing `.byteLength` of a Buffer.
17 */18 */
18 sizeFn?: (value: V, key: K) => number;19 sizeFn?: (value: V, key: K) => number;
19 /** Called when `set` or `ensureUnusedCapacity` removes items. */20 /** called when `set` or `ensureUnusedCapacity` removes items. */
20 evict?: (value: V, key: K) => void;21 evict?: (value: V, key: K) => void;
21 /** Called when anything removes items. */22 /** called when anything removes items. */
22 delete?: (value: V, key: K) => void;23 delete?: (value: V, key: K) => void;
23}24}
2425
25/**26/**
26 * A Least-recently-used cache has a set capacity, removing the oldest item27 * a Least-recently-used cache has a set capacity, removing the oldest item
27 * when trying to insert an item that would exceed such capacity. This28 * when trying to insert an item that would exceed such capacity. this
28 * implementation supports variable sized items, eviction callbacks, entry29 * implementation supports variable sized items, eviction callbacks, entry
29 * locking, and JSON-compatible serialization.30 * locking, and JSON-compatible serialization.
30 *31 *
...@@ -32,9 +33,9 @@ interface Options<K, V> {...@@ -32,9 +33,9 @@ interface Options<K, V> {
32 */33 */
33export class Lru<K, V> extends Map<K, V> {34export class Lru<K, V> extends Map<K, V> {
34 #order = new Map<K, Order<K>>();35 #order = new Map<K, Order<K>>();
35 /** The most recently used */36 /** the most recently used */
36 #head: K | none = none;37 #head: K | none = none;
37 /** The least recently used */38 /** the least recently used */
38 #tail: K | none = none;39 #tail: K | none = none;
39 #used: number = 0;40 #used: number = 0;
40 #locked: number = 0;41 #locked: number = 0;
...@@ -119,7 +120,7 @@ export class Lru<K, V> extends Map<K, V> {...@@ -119,7 +120,7 @@ export class Lru<K, V> extends Map<K, V> {
119 return this;120 return this;
120 }121 }
121122
122 /** Prevent an item from being automatically evicted */123 /** prevent an item from being automatically evicted */
123 lock(key: K): ts.Dispose {124 lock(key: K): ts.Dispose {
124 const order = this.#order.get(key);125 const order = this.#order.get(key);
125 if (!order) throw new Error(`Key ${key} not in Lru`);126 if (!order) throw new Error(`Key ${key} not in Lru`);
...@@ -131,7 +132,7 @@ export class Lru<K, V> extends Map<K, V> {...@@ -131,7 +132,7 @@ export class Lru<K, V> extends Map<K, V> {
131 });132 });
132 }133 }
133134
134 /** Evict items until there are `unused` capacity slots. */135 /** evict items until there are `unused` capacity slots. */
135 ensureUnusedCapacity(unused: number) {136 ensureUnusedCapacity(unused: number) {
136 const uc = this.unlockedCapacity;137 const uc = this.unlockedCapacity;
137 if (unused > uc) {138 if (unused > uc) {
...@@ -171,7 +172,7 @@ export class Lru<K, V> extends Map<K, V> {...@@ -171,7 +172,7 @@ export class Lru<K, V> extends Map<K, V> {
171 this.#used -= needed - remain;172 this.#used -= needed - remain;
172 }173 }
173174
174 /** Unlink an entry without removing it. */175 /** unlink an entry without removing it. */
175 #evict(key: K) {176 #evict(key: K) {
176 const entry = this.#order.get(key);177 const entry = this.#order.get(key);
177 if (!entry) return null;178 if (!entry) return null;
...@@ -243,7 +244,7 @@ export class Lru<K, V> extends Map<K, V> {...@@ -243,7 +244,7 @@ export class Lru<K, V> extends Map<K, V> {
243 }244 }
244}245}
245246
246/** The first item is the most recently used. */247/** the first item is the most recently used. */
247type Serialized<K, V> = Array<[K, V, number]>;248type Serialized<K, V> = Array<[K, V, number]>;
248249
249interface SerializeOptions<IK, IV, OK = IK, OV = IV> {250interface SerializeOptions<IK, IV, OK = IK, OV = IV> {
...@@ -252,13 +253,13 @@ interface SerializeOptions<IK, IV, OK = IK, OV = IV> {...@@ -252,13 +253,13 @@ interface SerializeOptions<IK, IV, OK = IK, OV = IV> {
252}253}
253254
254type Order<K> = [255type Order<K> = [
255 /** Number of units computed at insertion time. */256 /** number of units computed at insertion time. */
256 size: number,257 size: number,
257 /** Towards most recently used */258 /** towards most recently used */
258 before: K | none,259 before: K | none,
259 /** Towards least recently used */260 /** towards least recently used */
260 after: K | none,261 after: K | none,
261 /** Locking prevents automatic eviction */262 /** locking prevents automatic eviction */
262 locks: number,263 locks: number,
263];264];
264265
lib/render.ts+4-4
...@@ -22,16 +22,16 @@...@@ -22,16 +22,16 @@
22 * @module22 * @module
23 */23 */
2424
25/* convert a UI description into a string synchronously.25/** convert a UI description into a string synchronously.
26 * optional `context` argument pre-populates render context. */26 * optional `context` argument pre-populates render context. */
27export function sync(node: Node, contexts?: ContextValue[]): Result {27export function sync(node: Node, contexts?: ContextValue[]): Result {
28 const state = init(false, contexts ?? []);28 const state = init(false, contexts ?? []);
29 const resolved = resolveNode(state, node);29 const resolved = resolveNode(state, node);
30 return { text: stringifyNode(resolved), context: state.context };30 return { text: stringifyNode(resolved), context: state.context };
31}31}
3232
33/* convert a UI description into a string asynchronously.33/** convert a UI description into a string asynchronously.
34 * optional `context` argument pre-populates render context. */34 * optional `context` argument pre-populates render context. */
35export function async(node: Node, contexts?: ContextValue[]): Promise<Result> {35export function async(node: Node, contexts?: ContextValue[]): Promise<Result> {
36 const state = init(true, contexts ?? []);36 const state = init(true, contexts ?? []);
37 const resolved = resolveNode(state, node);37 const resolved = resolveNode(state, node);
lib/ts.ts+4
...@@ -1,6 +1,10 @@...@@ -1,6 +1,10 @@
1export type Timer = ReturnType<typeof setTimeout>;1export type Timer = ReturnType<typeof setTimeout>;
2export type Interval = ReturnType<typeof setInterval>;2export type Interval = ReturnType<typeof setInterval>;
33
4/**
5 * redeclared here because it is only provided by `lib: ["dom"]` and not
6 * the JavaScript standard types.
7 */
4export interface VoidFunction {8export interface VoidFunction {
5 (): void;9 (): void;
6}10}