saeeol 1.3.0 → 1.3.1

package/src/boxes/diff-apply.ts

@@ -0,0 +1,53 @@
+/**
+ * diff-apply.ts — Parse and apply unified diffs
+ * Inspired by Continue.dev edit pipeline (Apache-2.0)
+ * Deps: none
+ */
+
+export interface DiffHunk {
+  oldStart: number; oldCount: number
+  newStart: number; newCount: number
+  lines: string[]
+}
+
+export function parseUnifiedDiff(diff: string): DiffHunk[] {
+  const hunks: DiffHunk[] = []
+  let current: DiffHunk | null = null
+  for (const line of diff.split("\n")) {
+    const m = line.match(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/)
+    if (m) {
+      if (current) hunks.push(current)
+      current = {
+        oldStart: parseInt(m[1]), oldCount: parseInt(m[2] ?? "1"),
+        newStart: parseInt(m[3]), newCount: parseInt(m[4] ?? "1"),
+        lines: [],
+      }
+    } else if (current && (line.startsWith("+") || line.startsWith("-") || line.startsWith(" ") || line === "")) {
+      current.lines.push(line)
+    }
+  }
+  if (current) hunks.push(current)
+  return hunks
+}
+
+export function applyDiff(source: string, hunks: DiffHunk[]): string {
+  const lines = source.split("\n")
+  let offset = 0
+  for (const h of hunks) {
+    const start = h.oldStart - 1 + offset
+    const oldLines: string[] = []
+    const newLines: string[] = []
+    for (const l of h.lines) {
+      if (l.startsWith("-")) oldLines.push(l.slice(1))
+      else if (l.startsWith("+")) newLines.push(l.slice(1))
+      else { oldLines.push(l.slice(1)); newLines.push(l.slice(1)) }
+    }
+    lines.splice(start, oldLines.length, ...newLines)
+    offset += newLines.length - oldLines.length
+  }
+  return lines.join("\n")
+}
+
+export function applyUnifiedDiff(source: string, diff: string): string {
+  return applyDiff(source, parseUnifiedDiff(diff))
+}

package/src/boxes/disposable.ts

@@ -0,0 +1,13 @@
+/**
+ * disposable.ts — Wrap cleanup fn as Disposable + AsyncDisposable
+ * Zero deps.
+ *
+ * const d = disposable(() => console.log("cleaned"))
+ * using d = disposable(() => cleanup())
+ */
+export function disposable(fn: () => void | Promise<void>): AsyncDisposable & Disposable {
+  return {
+    [Symbol.dispose]() { void fn() },
+    [Symbol.asyncDispose]() { return Promise.resolve(fn()) },
+  }
+}

package/src/boxes/err.ts

@@ -0,0 +1,34 @@
+/**
+ * err.ts — Universal error message extraction
+ * Zero deps.
+ *
+ * msg(new Error("fail")) → "fail"
+ * msg({ message: "bad" }) → "bad"
+ */
+export function isObj(v: unknown): v is Record<string, unknown> {
+  return !!v && typeof v === "object" && !Array.isArray(v)
+}
+
+export function msg(e: unknown): string {
+  if (e instanceof Error) {
+    if (e.message) return e.message
+    if (e.name) return e.name
+  }
+  if (isObj(e)) {
+    if (typeof e.message === "string" && e.message) return e.message
+    if (isObj(e.data) && typeof e.data.message === "string" && e.data.message) return e.data.message
+  }
+  const s = String(e)
+  if (s && s !== "[object Object]") return s
+  const f = fmt(e)
+  if (f && f !== "{}") return f
+  return "unknown error"
+}
+
+export function fmt(e: unknown): string {
+  if (e instanceof Error) return e.stack ?? `${e.name}: ${e.message}`
+  if (typeof e === "object" && e !== null) {
+    try { return JSON.stringify(e, null, 2) } catch { return "Unexpected error (unserializable)" }
+  }
+  return String(e)
+}

package/src/boxes/human.ts

@@ -0,0 +1,47 @@
+/**
+ * human.ts — Human-readable formatting: duration, numbers, dates, truncate, plural
+ * Zero deps.
+ *
+ * duration(150000) → "2m 30s"
+ * compact(1500) → "1.5K"
+ * truncate("hello world", 8) → "hello w…"
+ */
+export function title(s: string) { return s.replace(/\b\w/g, c => c.toUpperCase()) }
+
+export function time(ms: number) { return new Date(ms).toLocaleTimeString(undefined, { timeStyle: "short" }) }
+
+export function datetime(ms: number) { return `${time(ms)} · ${new Date(ms).toLocaleDateString()}` }
+
+export function compact(n: number): string {
+  if (n >= 1_000_000) return (n / 1_000_000).toFixed(1) + "M"
+  if (n >= 1000) return (n / 1000).toFixed(1) + "K"
+  return n.toString()
+}
+
+export function duration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`
+  if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`
+  if (ms < 3_600_000) return `${Math.floor(ms / 60_000)}m ${Math.floor((ms % 60_000) / 1000)}s`
+  if (ms < 86_400_000) return `${Math.floor(ms / 3_600_000)}h ${Math.floor((ms % 3_600_000) / 60_000)}m`
+  return `${Math.floor(ms / 3_600_000)}h`
+}
+
+export function truncate(s: string, len: number): string { return s.length <= len ? s : s.slice(0, len - 1) + "…" }
+
+export function truncateMid(s: string, max = 35): string {
+  if (s.length <= max) return s
+  const pre = Math.ceil((max - 1) / 2)
+  const suf = Math.floor((max - 1) / 2)
+  return s.slice(0, pre) + "…" + s.slice(-suf)
+}
+
+export function plural(n: number, one: string, many: string): string { return (n === 1 ? one : many).replace("{}", String(n)) }
+
+export function secsDuration(s: number): string {
+  if (s <= 0) return ""
+  if (s < 60) return `${s}s`
+  if (s < 3600) { const m = Math.floor(s / 60); const r = s % 60; return r > 0 ? `${m}m ${r}s` : `${m}m` }
+  if (s < 86400) { const h = Math.floor(s / 3600); const r = Math.floor((s % 3600) / 60); return r > 0 ? `${h}h ${r}m` : `${h}h` }
+  if (s < 604800) { const d = Math.floor(s / 86400); return d === 1 ? "~1 day" : `~${d} days` }
+  const w = Math.floor(s / 604800); return w === 1 ? "~1 week" : `~${w} weeks`
+}

package/src/boxes/iife.ts

@@ -0,0 +1,9 @@
+/**
+ * iife.ts — Immediately-invoked function expression
+ * Zero deps.
+ *
+ * const x = iife(() => compute())
+ */
+export function iife<T>(fn: () => T) {
+  return fn()
+}

package/src/boxes/latch.ts

@@ -0,0 +1,8 @@
+export function latch() {
+  let resolve: () => void
+  const p = new Promise<void>((r) => { resolve = r })
+  return {
+    trip() { resolve() },
+    wait() { return p },
+  }
+}

package/src/boxes/memory.ts

@@ -0,0 +1,198 @@
+/**
+ * memory.ts — File-based persistent memory with typed taxonomy
+ * Deps: Node built-ins (os, path, fs/promises)
+ * Ported from Claude Code memdir/
+ */
+
+import { homedir } from "os"
+import { join, normalize, sep, basename } from "path"
+import { mkdir, readFile, writeFile, readdir, stat } from "fs/promises"
+
+// ── Types ──────────────────────────────────────────
+
+export const MEMORY_TYPES = ["user", "feedback", "project", "reference"] as const
+export type MemoryType = (typeof MEMORY_TYPES)[number]
+
+export function parseMemoryType(raw: unknown): MemoryType | undefined {
+  if (typeof raw !== "string") return undefined
+  return MEMORY_TYPES.find(t => t === raw)
+}
+
+export interface MemoryHeader {
+  filename: string
+  filePath: string
+  mtimeMs: number
+  description: string | null
+  type: MemoryType | undefined
+}
+
+// ── Age ────────────────────────────────────────────
+
+export function memoryAgeDays(mtimeMs: number): number {
+  return Math.max(0, Math.floor((Date.now() - mtimeMs) / 86_400_000))
+}
+
+export function memoryAge(mtimeMs: number): string {
+  const d = memoryAgeDays(mtimeMs)
+  if (d === 0) return "today"
+  if (d === 1) return "yesterday"
+  return `${d} days ago`
+}
+
+export function memoryFreshnessText(mtimeMs: number): string {
+  const d = memoryAgeDays(mtimeMs)
+  if (d <= 1) return ""
+  return `This memory is ${d} days old. Memories are point-in-time observations, not live state — verify against current code before asserting as fact.`
+}
+
+// ── Paths ──────────────────────────────────────────
+
+export const MAX_ENTRYPOINT_LINES = 200
+export const MAX_ENTRYPOINT_BYTES = 25_000
+
+export function getMemoryBaseDir(): string {
+  return process.env.KILO_MEMORY_DIR ?? join(homedir(), ".config", "saeeol")
+}
+
+export function getMemoryDir(projectRoot: string): string {
+  if (process.env.KILO_MEMORY_DIR) return process.env.KILO_MEMORY_DIR
+  return join(getMemoryBaseDir(), "projects", sanitize(projectRoot), "memory") + sep
+}
+
+export function getMemoryEntrypoint(projectRoot: string): string {
+  return join(getMemoryDir(projectRoot), "MEMORY.md")
+}
+
+export function isMemoryPath(absolutePath: string, projectRoot: string): boolean {
+  return normalize(absolutePath).startsWith(getMemoryDir(projectRoot))
+}
+
+function sanitize(p: string): string {
+  return p.replace(/[<>:"|?*]/g, "_").replace(/[/\\]+/g, "_")
+}
+
+// ── Scan ───────────────────────────────────────────
+
+const MAX_MEMORY_FILES = 200
+const FM_MAX_LINES = 30
+
+export async function scanMemoryFiles(dir: string): Promise<MemoryHeader[]> {
+  try {
+    const entries = await readdir(dir, { recursive: true })
+    const mds = entries.filter(
+      (f): f is string => typeof f === "string" && f.endsWith(".md") && basename(f) !== "MEMORY.md",
+    )
+    if (mds.length === 0) return []
+    const results = await Promise.allSettled(mds.map(async (rel): Promise<MemoryHeader> => {
+      const fp = join(dir, rel)
+      const s = await stat(fp)
+      const { description, type } = await parseFrontmatter(fp)
+      return { filename: rel, filePath: fp, mtimeMs: s.mtimeMs, description, type }
+    }))
+    return results
+      .filter((r): r is PromiseFulfilledResult<MemoryHeader> => r.status === "fulfilled")
+      .map(r => r.value)
+      .sort((a, b) => b.mtimeMs - a.mtimeMs)
+      .slice(0, MAX_MEMORY_FILES)
+  } catch { return [] }
+}
+
+export function formatMemoryManifest(memories: MemoryHeader[]): string {
+  return memories.map(m => {
+    const tag = m.type ? `[${m.type}] ` : ""
+    const ts = new Date(m.mtimeMs).toISOString()
+    return m.description ? `- ${tag}${m.filename} (${ts}): ${m.description}` : `- ${tag}${m.filename} (${ts})`
+  }).join("\n")
+}
+
+async function parseFrontmatter(
+  filePath: string,
+): Promise<{ description: string | null; type: MemoryType | undefined }> {
+  try {
+    const raw = await readFile(filePath, "utf-8")
+    const lines = raw.split("\n").slice(0, FM_MAX_LINES)
+    const acc = lines.reduce(
+      (s, line) => {
+        if (s.done) return s
+        if (line.trim() === "---") { if (s.inFm) return { ...s, done: true }; return { ...s, inFm: true } }
+        if (!s.inFm) return s
+        const desc = line.match(/^description:\s*(.+)$/i)?.[1]
+        const typ = line.match(/^type:\s*(.+)$/i)?.[1]
+        return { ...s, desc: desc ?? s.desc, typeRaw: typ ?? s.typeRaw }
+      },
+      { inFm: false, done: false, desc: null as string | null, typeRaw: undefined as string | undefined },
+    )
+    return { description: acc.desc, type: parseMemoryType(acc.typeRaw) }
+  } catch { return { description: null, type: undefined } }
+}
+
+// ── Entrypoint I/O ─────────────────────────────────
+
+export function truncateEntrypoint(raw: string): { content: string; wasTruncated: boolean } {
+  const trimmed = raw.trim()
+  const lines = trimmed.split("\n")
+  const wasLine = lines.length > MAX_ENTRYPOINT_LINES
+  const wasByte = trimmed.length > MAX_ENTRYPOINT_BYTES
+  if (!wasLine && !wasByte) return { content: trimmed, wasTruncated: false }
+  const afterLine = wasLine ? lines.slice(0, MAX_ENTRYPOINT_LINES).join("\n") : trimmed
+  const final = afterLine.length > MAX_ENTRYPOINT_BYTES
+    ? (() => { const cut = afterLine.lastIndexOf("\n", MAX_ENTRYPOINT_BYTES); return afterLine.slice(0, cut > 0 ? cut : MAX_ENTRYPOINT_BYTES) })()
+    : afterLine
+  return { content: final + "\n\n> WARNING: MEMORY.md was truncated. Keep entries concise.", wasTruncated: true }
+}
+
+export async function readEntrypoint(projectRoot: string): Promise<string> {
+  try { return await readFile(getMemoryEntrypoint(projectRoot), "utf-8") }
+  catch { return "" }
+}
+
+export async function writeEntrypoint(projectRoot: string, content: string): Promise<void> {
+  const { content: final } = truncateEntrypoint(content)
+  await writeFile(getMemoryEntrypoint(projectRoot), final, "utf-8")
+}
+
+export async function ensureDir(projectRoot: string): Promise<string> {
+  const dir = getMemoryDir(projectRoot)
+  try { await mkdir(dir, { recursive: true }) } catch { /* exists */ }
+  return dir
+}
+
+// ── Prompt builder ─────────────────────────────────
+
+const TYPES_SECTION = [
+  "## Types of memory", "",
+  "There are several discrete types of memory you can store:", "",
+  "<types>",
+  '<type><name>user</name><description>User preferences, role, and knowledge.</description><when_to_save>When you learn about the user\'s role, preferences, or knowledge.</when_to_save></type>',
+  '<type><name>feedback</name><description>Guidance about how to approach work — both corrections and confirmed approaches.</description><when_to_save>When the user corrects or confirms your approach.</when_to_save></type>',
+  '<type><name>project</name><description>Ongoing work, goals, bugs, or incidents not derivable from code.</description><when_to_save>When you learn who is doing what, why, or by when.</when_to_save></type>',
+  '<type><name>reference</name><description>Pointers to external systems and resources.</description><when_to_save>When you learn about external resources and their purpose.</when_to_save></type>',
+  "</types>", "",
+]
+
+export async function buildPrompt(projectRoot: string): Promise<string> {
+  const dir = getMemoryDir(projectRoot)
+  const ep = await readEntrypoint(projectRoot)
+  const lines = [
+    "# auto memory", "",
+    `You have a persistent memory system at \`${dir}\`. Write to it directly.`,
+    "", "Build up this memory so future conversations have context about the user, their preferences, and project decisions.",
+    "", ...TYPES_SECTION,
+    "## What NOT to save in memory", "",
+    "- Code patterns, architecture, file paths — derivable from current project state.",
+    "- Git history — `git log` / `git blame` are authoritative.",
+    "- Debugging solutions — the fix is in the code.",
+    "- Ephemeral task details: in-progress work, temporary state.", "",
+    "## When to access memories",
+    "- When memories seem relevant to the user's request.",
+    "- When the user explicitly asks you to recall something.",
+    "- Memory records can become stale. Verify against current state before asserting as fact.", "",
+  ]
+  const epContent = ep.trim() ? truncateEntrypoint(ep).content : "Your MEMORY.md is currently empty."
+  lines.push("## MEMORY.md", "", epContent)
+  return lines.join("\n")
+}
+
+export async function scan(projectRoot: string) {
+  return scanMemoryFiles(getMemoryDir(projectRoot))
+}

package/src/boxes/net.ts

@@ -0,0 +1,16 @@
+/**
+ * net.ts — Network status checks
+ * Zero deps.
+ *
+ * online() → true/false
+ * proxied() → true/false
+ */
+export function online(): boolean {
+  const n = globalThis.navigator
+  if (!n || typeof n.onLine !== "boolean") return true
+  return n.onLine
+}
+
+export function proxied(): boolean {
+  return !!(process.env.HTTP_PROXY || process.env.HTTPS_PROXY || process.env.http_proxy || process.env.https_proxy)
+}

package/src/boxes/plural.ts

@@ -0,0 +1,4 @@
+export function plural(n: number, one: string, many: string): string {
+  const tpl = n === 1 ? one : many
+  return tpl.replace("{}", String(n))
+}

package/src/boxes/puny.ts

@@ -0,0 +1,21 @@
+/**
+ * puny.ts — Normalize IDN/Unicode URLs to punycode ASCII (anti-homograph)
+ * Zero deps. Uses URL built-in.
+ *
+ * norm("https://аpitest.com/path") → "https://xn--pitest-2nf.com/path"
+ */
+export function norm(text: string): string {
+  return text.replace(/https?:\/\/\S+/g, (match) => {
+    const stripped = match.replace(/[.,!?;:)"'\]>]+$/, "")
+    const tail = match.slice(stripped.length)
+    try {
+      const u = new URL(stripped)
+      const after = stripped.indexOf("//") + 2
+      const slash = stripped.indexOf("/", after)
+      const raw = slash === -1 ? stripped.slice(after) : stripped.slice(after, slash)
+      const host = raw.includes(":") ? raw.slice(0, raw.indexOf(":")) : raw
+      if (host === u.hostname) return match
+      return stripped.replace(host, u.hostname) + tail
+    } catch { return match }
+  })
+}

package/src/boxes/retry.ts

@@ -0,0 +1,49 @@
+import { expDelay } from "./schedule"
+
+const TRANSIENT = [
+  "load failed",
+  "network connection was lost",
+  "network request failed",
+  "failed to fetch",
+  "econnreset",
+  "econnrefused",
+  "etimedout",
+  "socket hang up",
+]
+
+function isTransient(err: unknown): boolean {
+  if (!err) return false
+  const msg = String(err instanceof Error ? err.message : err).toLowerCase()
+  return TRANSIENT.some((t) => msg.includes(t))
+}
+
+export interface RetryOpts {
+  attempts?: number
+  delay?: number
+  factor?: number
+  maxDelay?: number
+  retryIf?: (err: unknown) => boolean
+}
+
+export async function retry<T>(
+  fn: () => Promise<T>,
+  opts: RetryOpts = {},
+): Promise<T> {
+  const {
+    attempts = 3,
+    delay = 500,
+    factor = 2,
+    maxDelay = 10_000,
+    retryIf = isTransient,
+  } = opts
+  let last: unknown
+  for (let i = 0; i < attempts; i++) {
+    try { return await fn() } catch (err) {
+      last = err
+      if (i === attempts - 1 || !retryIf(err)) throw err
+      const wait = Math.min(expDelay(delay, i, factor), maxDelay)
+      await new Promise((r) => setTimeout(r, wait))
+    }
+  }
+  throw last
+}

package/src/boxes/rwlock.ts

@@ -0,0 +1,41 @@
+/**
+ * rwlock.ts — Readers-writer lock map (writer priority, no starvation)
+ * Zero deps.
+ *
+ * using r = await rwlock.read("key")
+ * using w = await rwlock.write("key")
+ */
+const map = new Map<string, { r: number; w: boolean; wr: (() => void)[]; ww: (() => void)[] }>()
+
+function get(k: string) {
+  if (!map.has(k)) map.set(k, { r: 0, w: false, wr: [], ww: [] })
+  return map.get(k)!
+}
+
+function drain(k: string) {
+  const l = map.get(k)
+  if (!l || l.w || l.r > 0) return
+  if (l.ww.length > 0) { l.ww.shift()!(); return }
+  while (l.wr.length > 0) l.wr.shift()!()
+  if (l.r === 0 && !l.w && l.wr.length === 0 && l.ww.length === 0) map.delete(k)
+}
+
+function mkRelease(k: string, mode: "r" | "w"): Disposable {
+  return { [Symbol.dispose]: () => { const l = map.get(k); if (!l) return; if (mode === "w") l.w = false; else l.r--; drain(k) } }
+}
+
+export async function read(k: string): Promise<Disposable> {
+  const l = get(k)
+  return new Promise<Disposable>((res) => {
+    if (!l.w && l.ww.length === 0) { l.r++; res(mkRelease(k, "r")) }
+    else l.wr.push(() => { l.r++; res(mkRelease(k, "r")) })
+  })
+}
+
+export async function write(k: string): Promise<Disposable> {
+  const l = get(k)
+  return new Promise<Disposable>((res) => {
+    if (!l.w && l.r === 0) { l.w = true; res(mkRelease(k, "w")) }
+    else l.ww.push(() => { l.w = true; res(mkRelease(k, "w")) })
+  })
+}

package/src/boxes/schedule.ts

@@ -0,0 +1,71 @@
+/**
+ * schedule.ts — Retry schedule patterns (exponential/fibonacci)
+ * Inspired by Effect-TS Schedule (MIT)
+ * Deps: none
+ */
+
+// ── Pure functions (stateless, safe for concurrent use) ──
+
+export function expDelay(baseMs: number, attempt: number, factor = 2): number {
+  return baseMs * Math.pow(factor, attempt)
+}
+
+export function fibDelay(oneMs: number, attempt: number): number {
+  if (attempt <= 0) return 0
+  let a = 0, b = 1
+  for (let i = 1; i < attempt; i++) { [a, b] = [b, a + b] }
+  return b * oneMs
+}
+
+// ── Stateful iterators (for retryWith / single-owner retry loops) ──
+
+export interface ScheduleStep {
+  delay: number
+  attempt: number
+  done: boolean
+}
+
+export interface ScheduleBuilder {
+  next(): ScheduleStep
+  reset(): void
+}
+
+export function exponential(baseMs: number, factor = 2, maxRetries = Infinity): ScheduleBuilder {
+  let attempt = 0
+  return {
+    next: () => {
+      if (attempt >= maxRetries) return { delay: 0, attempt, done: true }
+      const delay = expDelay(baseMs, attempt, factor)
+      return { delay, attempt: attempt++, done: false }
+    },
+    reset: () => { attempt = 0 },
+  }
+}
+
+export function fibonacci(oneMs: number, maxRetries = Infinity): ScheduleBuilder {
+  let a = 0, b = 1, attempt = 0
+  return {
+    next: () => {
+      if (attempt >= maxRetries) return { delay: 0, attempt, done: true }
+      const delay = a * oneMs; [a, b] = [b, a + b]
+      return { delay, attempt: attempt++, done: false }
+    },
+    reset: () => { a = 0; b = 1; attempt = 0 },
+  }
+}
+
+export function capDelay(maxMs: number, s: ScheduleBuilder): ScheduleBuilder {
+  return {
+    next: () => { const r = s.next(); return { ...r, delay: Math.min(r.delay, maxMs) } },
+    reset: () => { s.reset() },
+  }
+}
+
+export async function retryWith<T>(fn: (attempt: number) => Promise<T>, s: ScheduleBuilder): Promise<T> {
+  for (;;) {
+    const step = s.next()
+    if (step.done) throw new Error(`Retry exhausted after ${step.attempt} attempts`)
+    if (step.attempt > 0) await new Promise(r => setTimeout(r, step.delay))
+    try { const v = await fn(step.attempt); s.reset(); return v } catch { continue }
+  }
+}

package/src/boxes/scope.ts

@@ -0,0 +1,21 @@
+import { AsyncLocalStorage } from "async_hooks"
+
+export class NotFound extends Error {
+  constructor(public override readonly name: string) {
+    super(`no context for ${name}`)
+  }
+}
+
+export function scope<T>(label: string) {
+  const store = new AsyncLocalStorage<T>()
+  return {
+    use(): T {
+      const v = store.getStore()
+      if (!v) throw new NotFound(label)
+      return v
+    },
+    provide<R>(val: T, fn: () => R): R {
+      return store.run(val, fn)
+    },
+  }
+}

package/src/boxes/tokens.ts

@@ -0,0 +1,9 @@
+/**
+ * tokens.ts — Rough token estimator
+ * Zero deps.
+ *
+ * count("hello world") → 3
+ */
+export function count(text: string): number {
+  return Math.max(0, Math.round((text || "").length / 4))
+}

package/src/boxes/ttl-cache.ts

@@ -0,0 +1,63 @@
+/**
+ * ttl-cache.ts — Generic TTL cache with Map/WeakMap storage
+ * Ported from gemini-cli CacheService (Apache-2.0)
+ * Deps: none
+ */
+export interface CacheOpts {
+  defaultTtl?: number
+  storage?: "map" | "weakmap"
+}
+
+interface Entry<V> { value: V; ts: number; ttl?: number }
+
+export class TTLCache<K extends object | string | undefined, V> {
+  private store: Map<K, Entry<V>> | WeakMap<WeakKey, Entry<V>>
+  private defaultTtl?: number
+
+  constructor(opts: CacheOpts = {}) {
+    this.store = opts.storage === "weakmap"
+      ? new WeakMap<WeakKey, Entry<V>>()
+      : new Map<K, Entry<V>>()
+    this.defaultTtl = opts.defaultTtl
+  }
+
+  get(key: K): V | undefined {
+    const e = (this.store as any).get(key) as Entry<V> | undefined
+    if (!e) return undefined
+    const ttl = e.ttl ?? this.defaultTtl
+    if (ttl !== undefined && Date.now() - e.ts > ttl) {
+      this.delete(key)
+      return undefined
+    }
+    return e.value
+  }
+
+  set(key: K, value: V, ttl?: number): void {
+    (this.store as any).set(key, { value, ts: Date.now(), ttl })
+  }
+
+  getOrCreate(key: K, creator: () => V, ttl?: number): V {
+    const v = this.get(key)
+    if (v !== undefined) return v
+    const created = creator()
+    this.set(key, created, ttl)
+    return created
+  }
+
+  delete(key: K): void { (this.store as any).delete(key) }
+
+  clear(): void {
+    if (this.store instanceof Map) this.store.clear()
+    else throw new Error("clear() not supported on WeakMap")
+  }
+}
+
+export function createCache<K extends string | undefined, V>(
+  opts: CacheOpts & { storage: "map" },
+): TTLCache<K, V>
+export function createCache<K extends object, V>(opts?: CacheOpts): TTLCache<K, V>
+export function createCache<K extends object | string | undefined, V>(
+  opts: CacheOpts = {},
+): TTLCache<K, V> {
+  return new TTLCache<K, V>(opts)
+}