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 @@
11/**
2 * Least-recently-used cache.
23 * This module is intended to be imported via the main class.
34 *
45 * import { Lru } from '@clo/lib/Lru';
......@@ -12,19 +13,19 @@
1213interface Options<K, V> {
1314 capacity: number;
1415 /**
15 * Decide how many units of size each entry takes.
16 * decide how many units of size each entry takes.
1617 * For example, accessing `.byteLength` of a Buffer.
1718 */
1819 sizeFn?: (value: V, key: K) => number;
19 /** Called when `set` or `ensureUnusedCapacity` removes items. */
20 /** called when `set` or `ensureUnusedCapacity` removes items. */
2021 evict?: (value: V, key: K) => void;
21 /** Called when anything removes items. */
22 /** called when anything removes items. */
2223 delete?: (value: V, key: K) => void;
2324}
2425
2526/**
26 * 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. This
27 * a Least-recently-used cache has a set capacity, removing the oldest item
28 * when trying to insert an item that would exceed such capacity. this
2829 * implementation supports variable sized items, eviction callbacks, entry
2930 * locking, and JSON-compatible serialization.
3031 *
......@@ -32,9 +33,9 @@ interface Options<K, V> {
3233 */
3334export class Lru<K, V> extends Map<K, V> {
3435 #order = new Map<K, Order<K>>();
35 /** The most recently used */
36 /** the most recently used */
3637 #head: K | none = none;
37 /** The least recently used */
38 /** the least recently used */
3839 #tail: K | none = none;
3940 #used: number = 0;
4041 #locked: number = 0;
......@@ -119,7 +120,7 @@ export class Lru<K, V> extends Map<K, V> {
119120 return this;
120121 }
121122
122 /** Prevent an item from being automatically evicted */
123 /** prevent an item from being automatically evicted */
123124 lock(key: K): ts.Dispose {
124125 const order = this.#order.get(key);
125126 if (!order) throw new Error(`Key ${key} not in Lru`);
......@@ -131,7 +132,7 @@ export class Lru<K, V> extends Map<K, V> {
131132 });
132133 }
133134
134 /** Evict items until there are `unused` capacity slots. */
135 /** evict items until there are `unused` capacity slots. */
135136 ensureUnusedCapacity(unused: number) {
136137 const uc = this.unlockedCapacity;
137138 if (unused > uc) {
......@@ -171,7 +172,7 @@ export class Lru<K, V> extends Map<K, V> {
171172 this.#used -= needed - remain;
172173 }
173174
174 /** Unlink an entry without removing it. */
175 /** unlink an entry without removing it. */
175176 #evict(key: K) {
176177 const entry = this.#order.get(key);
177178 if (!entry) return null;
......@@ -243,7 +244,7 @@ export class Lru<K, V> extends Map<K, V> {
243244 }
244245}
245246
246/** The first item is the most recently used. */
247/** the first item is the most recently used. */
247248type Serialized<K, V> = Array<[K, V, number]>;
248249
249250interface SerializeOptions<IK, IV, OK = IK, OV = IV> {
......@@ -252,13 +253,13 @@ interface SerializeOptions<IK, IV, OK = IK, OV = IV> {
252253}
253254
254255type Order<K> = [
255 /** Number of units computed at insertion time. */
256 /** number of units computed at insertion time. */
256257 size: number,
257 /** Towards most recently used */
258 /** towards most recently used */
258259 before: K | none,
259 /** Towards least recently used */
260 /** towards least recently used */
260261 after: K | none,
261 /** Locking prevents automatic eviction */
262 /** locking prevents automatic eviction */
262263 locks: number,
263264];
264265
lib/render.ts+4-4
......@@ -22,16 +22,16 @@
2222 * @module
2323 */
2424
25/* convert a UI description into a string synchronously.
26 * optional `context` argument pre-populates render context. */
25/** convert a UI description into a string synchronously.
26 * optional `context` argument pre-populates render context. */
2727export function sync(node: Node, contexts?: ContextValue[]): Result {
2828 const state = init(false, contexts ?? []);
2929 const resolved = resolveNode(state, node);
3030 return { text: stringifyNode(resolved), context: state.context };
3131}
3232
33/* convert a UI description into a string asynchronously.
34 * optional `context` argument pre-populates render context. */
33/** convert a UI description into a string asynchronously.
34 * optional `context` argument pre-populates render context. */
3535export function async(node: Node, contexts?: ContextValue[]): Promise<Result> {
3636 const state = init(true, contexts ?? []);
3737 const resolved = resolveNode(state, node);
lib/ts.ts+4
......@@ -1,6 +1,10 @@
11export type Timer = ReturnType<typeof setTimeout>;
22export 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 */
48export interface VoidFunction {
59 (): void;
610}