@young1lin/dsh-ui-gitworkbench 0.1.0

package/src/client/stage-tree.ts

@@ -0,0 +1,178 @@
+/**
+ * Tick state for the commit tree.
+ *
+ * IDEA presents a commit as a set of ticks rather than as a staging area, and
+ * the drawer follows it: a tick IS `git add`, applied immediately, so what the
+ * box shows and what `git status` reports can never drift apart. Nothing here
+ * decides that policy — this module only answers what a tick looks like and
+ * what clicking one should do, which is the part with rules worth testing.
+ *
+ * The one thing IDEA's model cannot say, and this one can, is a file that is
+ * staged AND edited again: part of it would go into the commit and part would
+ * not. That is not "ticked", and calling it ticked would make the box lie about
+ * what it is about to commit. It is the same indeterminate state a directory
+ * has when only some of its files are ticked, and it resolves the same way.
+ */
+
+export type CheckState = 'on' | 'off' | 'partial'
+
+/** The index/worktree pair from git's porcelain XY columns. */
+export interface StageFlags {
+  readonly staged?: boolean
+  readonly unstaged?: boolean
+}
+
+/**
+ * One file's tick.
+ * @param file - the file's stage flags; both may be true at once.
+ */
+export function fileCheckState(file: StageFlags): CheckState {
+  if (file.staged !== true) return 'off'
+  return file.unstaged === true ? 'partial' : 'on'
+}
+
+/**
+ * Roll descendant ticks up to the directory that holds them.
+ *
+ * Mixed children are indeterminate however lopsided the mix: one ticked file
+ * among two hundred is still "some of this directory", and rounding it to off
+ * would hide a file from the commit set the user is looking at.
+ * @param states - every descendant's tick, files and subdirectories alike.
+ */
+export function rollUp(states: Iterable<CheckState>): CheckState {
+  let seenOn = false
+  let seenOff = false
+  for (const state of states) {
+    if (state === 'partial') return 'partial'
+    if (state === 'on') seenOn = true
+    else seenOff = true
+    if (seenOn && seenOff) return 'partial'
+  }
+  return seenOn ? 'on' : 'off'
+}
+
+/** What a tick does to the index. */
+export type TickAction = 'stage' | 'unstage'
+
+/** One queued click: a path, and what the click asked to do with it. */
+export interface Tick {
+  readonly path: string
+  readonly action: TickAction
+}
+
+/**
+ * What clicking a tick in this state means.
+ *
+ * Indeterminate stages rather than unstages: a half-ticked box invites you to
+ * finish it, and the destructive reading (throw away what is already staged)
+ * is not what a click on a checkbox should ever do.
+ * @param state - the tick's current state.
+ */
+export function nextAction(state: CheckState): TickAction {
+  return state === 'on' ? 'unstage' : 'stage'
+}
+
+/**
+ * The paths an action actually has to touch.
+ *
+ * Staging skips what is already fully staged and unstaging skips what was never
+ * staged, so ticking a directory of two hundred files sends git only the ones
+ * that change — and an action with nothing to do sends nothing at all.
+ * @param files - the files under the tick that was clicked.
+ * @param action - from {@link nextAction}.
+ */
+export function pathsFor<T extends StageFlags & { readonly path: string }>(
+  files: readonly T[],
+  action: TickAction,
+): string[] {
+  return files
+    .filter(file => action === 'stage' ? file.unstaged === true : file.staged === true)
+    .map(file => file.path)
+}
+
+/**
+ * The stage flags a tick leaves behind the moment it is clicked, rather than
+ * the moment git confirms it.
+ * @param action - from {@link nextAction}.
+ */
+export function tickedFlags(action: TickAction): { staged: boolean; unstaged: boolean } {
+  return action === 'stage' ? { staged: true, unstaged: false } : { staged: false, unstaged: true }
+}
+
+/**
+ * The fetched files with the ticks still awaiting git laid over them.
+ *
+ * The overlay is what makes a tick feel instant: it answers "what did I just
+ * click" instead of waiting for the refetch to answer it. Entries the payload
+ * does not list are left alone — the payload is the authority on what exists,
+ * and a tick for a path it does not carry is settled, not painted onto nothing.
+ *
+ * Returns the very same array when the overlay changes nothing: the tree
+ * re-renders on this value, and a fresh array every poll would throw its
+ * memoisation away.
+ * @param files - the files the newest payload reported.
+ * @param pending - ticks clicked since the payload last confirmed one.
+ */
+export function withPendingTicks<T extends StageFlags & { readonly path: string }>(
+  files: readonly T[],
+  pending: ReadonlyMap<string, TickAction>,
+): readonly T[] {
+  if (pending.size === 0) return files
+  let touched = false
+  const shown = files.map(file => {
+    const action = pending.get(file.path)
+    if (action === undefined) return file
+    touched = true
+    return { ...file, ...tickedFlags(action) }
+  })
+  return touched ? shown : files
+}
+
+/**
+ * Which pending ticks the newest payload has confirmed, and which may be
+ * dropped from the overlay.
+ *
+ * A stage is settled once the payload shows the file staged — a newer edit on
+ * top does not undo the add, and demanding full-flag agreement would freeze
+ * the overlay over a file the agent is still editing, hiding the very edit the
+ * payload came to report. An unstage settles once the index no longer holds
+ * the file. A path the payload no longer lists at all was committed or
+ * reverted elsewhere, and counts as settled too, or its tick would stick
+ * forever.
+ * @param files - the files the newest payload reported.
+ * @param pending - ticks clicked since the payload last confirmed one.
+ */
+export function settledTicks<T extends StageFlags & { readonly path: string }>(
+  files: readonly T[],
+  pending: ReadonlyMap<string, TickAction>,
+): ReadonlyMap<string, TickAction> {
+  const flagsByPath = new Map(files.map(file => [file.path, file]))
+  const settled = new Map<string, TickAction>()
+  for (const [path, action] of pending) {
+    const file = flagsByPath.get(path)
+    const staged = file?.staged === true
+    if (file === undefined || (action === 'stage' ? staged : !staged)) settled.set(path, action)
+  }
+  return settled
+}
+
+/**
+ * The next git call the queue owes: every tick that shares the first entry's
+ * action, gathered however late it arrived.
+ *
+ * One action per call, always — `git add` and `git restore --staged` in one
+ * invocation is not a command git accepts. Batched by action rather than by
+ * contiguity, so a tick that arrived between two of the same kind does not
+ * split them into two spawns.
+ * @param queue - clicked ticks not yet handed to git.
+ * @returns the batch to run, or null when the queue is empty.
+ */
+export function nextBatch(queue: readonly Tick[]): { action: TickAction; paths: string[] } | null {
+  const first = queue[0]
+  if (first === undefined) return null
+  const paths: string[] = []
+  for (const tick of queue) {
+    if (tick.action === first.action) paths.push(tick.path)
+  }
+  return { action: first.action, paths }
+}

package/src/client/themes.ts

@@ -0,0 +1,181 @@
+/**
+ * The drawer's theme model: which palettes exist, which one a given appearance
+ * setting resolves to, and how the two styling scopes combine.
+ *
+ * Kept apart from the panel so it carries no CSS-module or React import, which
+ * is what lets `tests/theme-palettes.test.ts` hold the families here and the
+ * palettes in `GitWorkbenchPanel.module.css` to each other. Every family named here
+ * MUST have both an `-dark` and an `-light` palette in that stylesheet: a
+ * missing one leaves the drawer with no `--gs-*` token defined at all, which
+ * renders as unstyled black-on-white rather than as a visible error.
+ */
+
+/**
+ * Colour mode. `system` follows the host app (dsh writes `body[data-ds-dark-theme]`
+ * when its resolved palette is dark); `light` / `dark` pin the drawer even if
+ * dsh itself is the other scheme.
+ */
+export type ColorMode = 'system' | 'light' | 'dark'
+
+/** Theme family. Each supplies a light and a dark palette. */
+export type ThemeFamily = 'github' | 'idea' | 'vscode' | 'one' | 'solarized' | 'nord' | 'cyberpunk'
+
+export const COLOR_MODES: readonly ColorMode[] = ['system', 'light', 'dark']
+
+/** One family's menu entry. */
+export interface ThemeFamilyOption {
+  readonly id: ThemeFamily
+  readonly label: string
+  /** Ground, accent, and add colour — the three the swatch previews. */
+  readonly swatch: readonly [string, string, string]
+}
+
+/** Families in menu order, each with the colours that preview it. */
+export const THEME_FAMILIES: readonly ThemeFamilyOption[] = [
+  { id: 'github', label: 'GitHub', swatch: ['#0d1117', '#58a6ff', '#3fb950'] },
+  { id: 'idea', label: 'IntelliJ IDEA', swatch: ['#1e1f22', '#3574f0', '#5fad65'] },
+  { id: 'vscode', label: 'VS Code', swatch: ['#1e1e1e', '#0098ff', '#89d185'] },
+  { id: 'one', label: 'One', swatch: ['#282c34', '#61afef', '#98c379'] },
+  { id: 'solarized', label: 'Solarized', swatch: ['#002b36', '#268bd2', '#859900'] },
+  { id: 'nord', label: 'Nord', swatch: ['#2e3440', '#88c0d0', '#a3be8c'] },
+  { id: 'cyberpunk', label: 'Cyberpunk', swatch: ['#0b0417', '#00f0ff', '#ff2e88'] },
+]
+
+/** Persisted appearance choice. */
+export interface Appearance {
+  readonly mode: ColorMode
+  readonly family: ThemeFamily
+}
+
+/** Follow the host app, in the default palette. */
+export const DEFAULT_APPEARANCE: Appearance = { mode: 'system', family: 'github' }
+
+/**
+ * Narrow a stored value to an appearance choice.
+ * @param value - value read back from storage, written by any earlier build.
+ * @returns whether it names a mode and family this build still has.
+ */
+export function isAppearance(value: unknown): value is Appearance {
+  if (typeof value !== 'object' || value === null) return false
+  const { mode, family } = value as Partial<Appearance>
+  return COLOR_MODES.some(known => known === mode)
+    && THEME_FAMILIES.some(known => known.id === family)
+}
+
+/**
+ * Body attribute dsh's ThemePresenter toggles for the active palette.
+ * This plugin reads it rather than `prefers-color-scheme`: a plugin follows
+ * the host, not the computer.
+ */
+export const DSH_DARK_ATTR = 'data-ds-dark-theme'
+
+/**
+ * Whether dsh's resolved palette is currently dark.
+ * @param body - `document.body`, or a stand-in in tests.
+ */
+export function hostSchemeDark(body: { hasAttribute(name: string): boolean }): boolean {
+  return body.hasAttribute(DSH_DARK_ATTR)
+}
+
+/**
+ * Resolve the palette to paint with.
+ * @param appearance - the user's stored choice.
+ * @param hostDark - whether dsh's resolved palette is currently dark.
+ * @returns the `data-gs-theme` value naming one palette.
+ */
+export function resolveTheme(appearance: Appearance, hostDark: boolean): string {
+  const dark = appearance.mode === 'system' ? hostDark : appearance.mode === 'dark'
+  return `${appearance.family}-${dark ? 'dark' : 'light'}`
+}
+
+/* ---------------------------- custom styling ---------------------------- */
+
+/**
+ * One scope's styling, mirroring the host's `StyleEntry`.
+ *
+ * The client never has to validate these: the host sanitizes on both read and
+ * write, so a value that reaches here is already in range and the image is
+ * already known to be a base64 `data:` URL safe to interpolate into `url()`.
+ */
+export interface StyleEntry {
+  readonly css: string
+  readonly image: string
+  readonly blur: number
+  readonly veil: number
+}
+
+/** Which scope an edit applies to. */
+export type StyleScope = 'project' | 'global'
+
+export const STYLE_SCOPES: readonly StyleScope[] = ['project', 'global']
+
+/** What the host reports for a directory: each scope, unresolved. */
+export interface StyleSettings {
+  readonly project: StyleEntry | null
+  readonly global: StyleEntry | null
+  /** Repository root the project scope is keyed by; null outside a repository. */
+  readonly repoRoot: string | null
+}
+
+/** An entry with nothing set — what an unconfigured scope opens on. */
+export const DEFAULT_STYLE: StyleEntry = { css: '', image: '', blur: 18, veil: 78 }
+
+/** Top of the blur slider. Must match the host's own cap, which clamps to it. */
+export const STYLE_BLUR_MAX = 60
+
+/** Nothing configured in either scope. */
+export const EMPTY_SETTINGS: StyleSettings = { project: null, global: null, repoRoot: null }
+
+/**
+ * The background image actually shown.
+ *
+ * An image is not composable, so the project's replaces the global one outright
+ * rather than merging field by field — the blur and veil that were tuned for one
+ * photograph say nothing about another.
+ * @param settings - both scopes.
+ * @returns the winning entry's background, or null when neither sets an image.
+ */
+export function effectiveBackground(settings: StyleSettings): StyleEntry | null {
+  for (const entry of [settings.project, settings.global]) {
+    if (entry !== null && entry.image.length > 0) return entry
+  }
+  return null
+}
+
+/**
+ * The custom CSS actually applied.
+ *
+ * Both scopes apply, global first, so the project's rules win ties by cascade
+ * order while a global rule the project does not mention still holds. That is
+ * what CSS already does with two stylesheets, and it is more useful than an
+ * override: a global rule can set the type scale for every project while one
+ * project recolours its accent.
+ * @param settings - both scopes.
+ * @returns the concatenated stylesheet, empty when neither scope sets any.
+ */
+export function effectiveCss(settings: StyleSettings): string {
+  const parts: string[] = []
+  for (const entry of [settings.global, settings.project]) {
+    if (entry !== null && entry.css.trim().length > 0) parts.push(entry.css)
+  }
+  return parts.join('\n')
+}
+
+/**
+ * @param settings - both scopes.
+ * @param scope - the scope being edited.
+ * @returns that scope's entry, or the defaults when it has none yet.
+ */
+export function entryFor(settings: StyleSettings, scope: StyleScope): StyleEntry {
+  return (scope === 'project' ? settings.project : settings.global) ?? DEFAULT_STYLE
+}
+
+/**
+ * @param settings - both scopes.
+ * @param scope - the scope that changed.
+ * @param entry - its new value.
+ * @returns settings with that scope replaced.
+ */
+export function withScope(settings: StyleSettings, scope: StyleScope, entry: StyleEntry): StyleSettings {
+  return scope === 'project' ? { ...settings, project: entry } : { ...settings, global: entry }
+}

package/src/client/worktree-view.ts

@@ -0,0 +1,193 @@
+/**
+ * Worktree facts the drawer header renders, as plain functions.
+ *
+ * These live outside GitWorkbenchPanel.tsx so they can be tested: importing the
+ * panel pulls a CSS module and React, which a node test environment cannot
+ * load. The parameter types are structural for the same reason — naming
+ * `WorktreeEntry` would import the panel back in.
+ */
+
+/** Separator-agnostic form: forward slashes, no trailing separator. */
+function normalize(path: string): string {
+  return path.replace(/\\/g, '/').replace(/\/+$/, '')
+}
+
+/**
+ * Whether two paths name the same place.
+ *
+ * `git worktree list` reports forward slashes while the session cwd arrives
+ * with the platform's own, so a raw comparison reads every Windows worktree as
+ * a different directory from itself. A missing side is never equal to anything
+ * — the drawer asks this to decide which row is active, and "unknown" must not
+ * light one up.
+ */
+export function samePath(a: string | null | undefined, b: string | null | undefined): boolean {
+  if (a === null || a === undefined || b === null || b === undefined) return false
+  return normalize(a) === normalize(b)
+}
+
+/**
+ * Which worktree the panel is reading.
+ *
+ * The pin is drawer-local by construction, not by remembering to clear it: with
+ * the drawer shut there is no way to see which worktree is pinned, change it,
+ * or even know one is. State nobody can perceive or reach should not be able to
+ * change what they see.
+ *
+ * Letting it survive a close is what produced a session card reading `main`
+ * with a `fixture-03` worktree badge beside it — the branch came from the
+ * pinned repository and the badge from the session's binding, so one row was
+ * quietly describing two different places. Reopening always discarded the pin
+ * anyway, so nothing was being preserved for anyone.
+ *
+ * @param open - whether the drawer is showing.
+ * @param sourcePath - the worktree pinned in the drawer, or null to follow the session.
+ * @param sessionPath - the session's own worktree: its binding, else its cwd.
+ * @returns the path every fetch and the header card should be about.
+ */
+export function viewedPath(
+  open: boolean,
+  sourcePath: string | null,
+  sessionPath: string | undefined,
+): string | undefined {
+  return open ? sourcePath ?? sessionPath : sessionPath
+}
+
+/**
+ * Whether the cheap closed-drawer binding probe should be on a timer.
+ *
+ * With the drawer shut, nothing re-read the session's binding: the fetch that
+ * carries it is keyed on the session id, the session cwd and `open`, and
+ * `worktree_enter` changes none of those — dsh's `session.header.cwd` is
+ * immutable, so the binding is the plugin's own state and the sessions store
+ * never mentions it. The 3-15s poll that would have caught it starts at
+ * `if (!open) return`. So the chip went on saying `main` after the agent had
+ * entered a worktree, and only opening the drawer — the one act that flips
+ * `open` — brought it up to date.
+ *
+ * The gate is narrow on purpose. A binding can only move from inside a turn
+ * (`worktree_enter` and `worktree_exit` are agent tools), so an idle session has
+ * nothing to watch; and this panel is mounted in EVERY session header, so a
+ * timer that runs while nothing can change is a per-header cost for no answer.
+ *
+ * @param open - whether the drawer is showing; open has its own poll.
+ * @param agentRunning - whether the session's agent has a turn in flight.
+ */
+export function probesClosedBinding(open: boolean, agentRunning: boolean | undefined): boolean {
+  return !open && agentRunning === true
+}
+
+/**
+ * Whether a binding probe disagrees with the binding the chip is showing.
+ *
+ * The probe is `gitWorkbench/sessionWorktree`, which reads the bindings JSON and
+ * spawns no git at all — that is what makes it affordable on a timer. It cannot
+ * replace the status fetch (no worktree list, no branches, so no picker and no
+ * badge), so it is used as a change DETECTOR: while the answer holds, the poll
+ * costs one file read; the moment it moves, one full `worktreeStatus` refetch
+ * repaints everything at once.
+ *
+ * Paths are compared through {@link samePath} rather than raw. Both sides come
+ * from the same file today, but a raw `!==` here would turn one separator
+ * difference into a `worktree list` + `branch` pair every three seconds behind
+ * a chip that was already correct.
+ *
+ * @param probe - what the bindings file says now; null fields mean unbound.
+ * @param shown - the binding the panel currently renders, or null when unbound.
+ */
+export function bindingChanged(
+  probe: { readonly worktreePath: string | null; readonly name: string | null },
+  shown: { readonly worktreePath: string; readonly name: string } | null,
+): boolean {
+  const probed = probe?.worktreePath ?? null
+  const rendered = shown?.worktreePath ?? null
+  // Enter and exit both land here: one side has a path and the other does not.
+  if (probed === null || rendered === null) return probed !== rendered
+  if (!samePath(probed, rendered)) return true
+  // Same directory, different name — a re-enter can reuse the path, and the
+  // name is what the badge prints.
+  return (probe.name ?? '') !== (shown?.name ?? '')
+}
+
+/**
+ * Whether a view should say "pending" rather than show what it has.
+ *
+ * There are two different loads behind one flag. A worktree SWITCH empties the
+ * file list first, so there is genuinely nothing to state and a confident
+ * `+0 −1` would be wrong. An ordinary REFRESH — which every tick performs, via
+ * `git add` and a refetch — runs over data that is still on screen and still
+ * correct; the numbers are about to be replaced by nearly identical ones.
+ *
+ * Blanking on the raw flag treated those the same, so every tick swapped the
+ * header totals for a `—` and back. Measured at 400ms, which is precisely the
+ * duration that reads as a flicker rather than as a load.
+ *
+ * The file tree already had this rule inline. Duplicating it in the header is
+ * how the header got it wrong, so it lives here now and both read it.
+ *
+ * @param loading - whether a fetch for this view is in flight.
+ * @param fileCount - how many files the view is currently able to show.
+ */
+export function showsPending(loading: boolean, fileCount: number): boolean {
+  return loading && fileCount === 0
+}
+
+/**
+ * Whether a worktree's badge would only repeat the branch chip beside it.
+ *
+ * dsh derives one from the other — `branchFor` in `src/worktree.ts` turns the
+ * name `demo` into the branch `wt/demo` — so for every worktree dsh made, the
+ * session card was printing the same word twice, once as `wt/fixture-03` and
+ * once as a `fixture-03` badge next to it. A worktree made outside dsh has no
+ * such relation, and there the badge is the only thing naming the directory.
+ *
+ * @param branch - the branch checked out there.
+ * @param name - the worktree's name, as the binding records it.
+ */
+export function badgeRepeatsBranch(branch: string, name: string): boolean {
+  return branch.length > 0 && branch === `wt/${name}`
+}
+
+/**
+ * Split a name into a shrinkable head and the last segment.
+ *
+ * Ref names are path-shaped too (`feature/nested/deep/some-fix`, and git spells
+ * them `refs/heads/...` underneath), so branches elide by the same rule as
+ * directories: the leaf is what distinguishes siblings, so the leaf is what
+ * survives.
+ *
+ * The header shows the whole path but has to give way to the totals beside it,
+ * and truncating from the right would eat exactly the segment that tells two
+ * worktrees apart. So the head ellipsises and the tail never does.
+ *
+ * Separators are preserved as they arrived: the path is shown to a human who
+ * recognises their own machine's spelling, not fed back to git.
+ *
+ * @param path - an absolute or relative path, possibly with a trailing separator.
+ * @returns the directory part including its trailing separator, and the last segment.
+ */
+export function splitPath(path: string): { head: string; tail: string } {
+  const trimmed = path.replace(/[/\\]+$/, '')
+  if (trimmed.length === 0) return { head: '', tail: path }
+  const cut = Math.max(trimmed.lastIndexOf('/'), trimmed.lastIndexOf('\\'))
+  if (cut < 0) return { head: '', tail: trimmed }
+  return { head: trimmed.slice(0, cut + 1), tail: trimmed.slice(cut + 1) }
+}
+
+/**
+ * The branch checked out at a worktree, from the list already in hand.
+ *
+ * This is what lets a source switch repaint the header immediately. The stats
+ * fetch that follows takes a `git status` and a numstat — seconds on a large
+ * repository — and until it lands the panel used to claim `(no branch)`, which
+ * is not a slower answer but a wrong one.
+ *
+ * @returns the branch, or an empty string when the path is unknown or the
+ *   worktree is detached — both of which genuinely have no branch to name.
+ */
+export function branchOfWorktree(
+  path: string | null | undefined,
+  worktrees: readonly { readonly path: string; readonly branch: string }[],
+): string {
+  return worktrees.find(entry => samePath(entry.path, path))?.branch ?? ''
+}

package/src/commit-cache.ts

@@ -0,0 +1,69 @@
+/**
+ * Bounded store for payloads addressed by a git object name.
+ *
+ * A commit hash names content that cannot change, so a hit stays valid for the
+ * life of the process and there is nothing to invalidate — capacity is the only
+ * reason an entry ever leaves. That is the whole distinction from working-tree
+ * data, which must never be cached because the next keystroke can change it.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/commit-cache
+ */
+
+/**
+ * Compose a cache key from its parts.
+ *
+ * The separator is a unit separator, which cannot occur in a filesystem path, a
+ * git object name, or a repository-relative filename. No two distinct part
+ * lists can therefore produce the same key.
+ * @param parts - key components, most general first.
+ * @returns the composed key.
+ */
+export function cacheKey(...parts: readonly string[]): string {
+  return parts.join('\x1f')
+}
+
+/**
+ * Fixed-capacity map with least-recently-used eviction.
+ *
+ * A Map iterates in insertion order, so re-inserting an entry on every hit
+ * makes insertion order the recency order and the first key the least recently
+ * used one. No timestamps, no separate list.
+ */
+export class CommitPayloadCache<V> {
+  private readonly entries = new Map<string, V>()
+
+  /** @param capacity - entries kept resident; the least recently used is dropped past it. */
+  constructor(private readonly capacity: number) {}
+
+  /** How many entries are resident. */
+  get size(): number {
+    return this.entries.size
+  }
+
+  /**
+   * Read an entry, marking it most recently used.
+   * @param key - cache key.
+   * @returns the stored payload, or undefined when the key is absent.
+   */
+  get(key: string): V | undefined {
+    const hit = this.entries.get(key)
+    if (hit === undefined) return undefined
+    this.entries.delete(key)
+    this.entries.set(key, hit)
+    return hit
+  }
+
+  /**
+   * Store an entry as most recently used, evicting past capacity.
+   * @param key - cache key.
+   * @param value - payload to store, replacing any existing entry for the key.
+   */
+  set(key: string, value: V): void {
+    this.entries.delete(key)
+    this.entries.set(key, value)
+    if (this.entries.size > this.capacity) {
+      const oldest = this.entries.keys().next()
+      if (!oldest.done) this.entries.delete(oldest.value)
+    }
+  }
+}