@wovin/core 0.1.35 → 0.2.0

package/src/query/divergences.ts

@@ -0,0 +1,50 @@
+import { Logger } from 'besonders-logger'
+import stringify from 'safe-stable-stringify'
+import { Applog, CidString } from '../applog/datom-types.ts'
+import { createDebugName } from '../utils/debug-name.ts'
+import { Thread } from '../thread/basic.ts'
+import { ThreadInMemory } from '../thread/writeable.ts'
+import { memoizedFn } from './memoized.ts'
+
+const { WARN, LOG, DEBUG, VERBOSE, ERROR } = Logger.setup(Logger.INFO) // eslint-disable-line no-unused-vars
+
+export interface DivergenceLeaf {
+	log: Applog
+	thread: Thread
+}
+
+export const queryDivergencesByPrev = memoizedFn('queryDivergencesByPrev', function queryConflictingByPrev(
+	sourceThread: Thread,
+) {
+	DEBUG(`queryDivergencesByPrev<${sourceThread.nameAndSizeUntracked}>`)
+	if (sourceThread.filters.includes('lastWriteWins')) WARN(`queryDivergencesByPrev on thread lastWriteWins`, sourceThread)
+
+	const logsForNode = new Map<CidString, Applog[]>()
+	const leafs = new Set<CidString>()
+	VERBOSE('all applogs:', sourceThread.applogs)
+	for (const log of sourceThread.applogs) {
+		let prevLogs
+		if (log.pv) {
+			prevLogs = log.pv && logsForNode.get(log.pv.toString())
+			leafs.delete(log.pv.toString())
+		}
+		VERBOSE('traversing log', { log, prevLogs, leafs: Array.from(leafs) })
+		logsForNode.set(log.cid, prevLogs ? [...prevLogs, log] : [log])
+		leafs.add(log.cid)
+	}
+	const divergences = Array.from(leafs).map(leafID => {
+		const thread = new ThreadInMemory(
+			createDebugName({
+				caller: 'DivergenceLeaf',
+				thread: sourceThread,
+				pattern: `leaf: ${leafID}`,
+			}),
+			logsForNode.get(leafID),
+			sourceThread.filters,
+			true,
+		)
+		return ({ log: thread.latestLog, thread })
+	})
+	// TODO: migrate to SubscribableArray for reactive updates
+	return divergences
+})

package/src/query/entity-collection.ts

@@ -0,0 +1,131 @@
+import { Logger } from 'besonders-logger'
+import { Applog, ApplogValue, DatalogQueryPattern, EntityID } from '../applog/datom-types.ts'
+import { isInitEvent, Thread } from '../thread/basic.ts'
+import { makeFilter, rollingFilter } from '../thread/filters.ts'
+import { resolveKeyMapper } from './basic.ts'
+import { memoizedFn } from './memoized.ts'
+import { SubscribableImpl } from './subscribable.ts'
+import type { Subscribable } from './subscribable.ts'
+import type { StripExplicitPrefix, StripFirstPrefix } from './attr-helpers.ts'
+
+const { DEBUG } = Logger.setup(Logger.INFO) // eslint-disable-line no-unused-vars
+
+export function liveEntityCollection<A extends string>(
+	thread: Thread, discoveryPattern: DatalogQueryPattern, liveAttributes: readonly A[],
+): Subscribable<ReadonlyMap<EntityID, Record<A, ApplogValue | null>>>
+export function liveEntityCollection<A extends string>(
+	thread: Thread, discoveryPattern: DatalogQueryPattern, liveAttributes: readonly A[],
+	opts: { stripAtPrefix: true },
+): Subscribable<ReadonlyMap<EntityID, Record<StripFirstPrefix<A>, ApplogValue | null>>>
+export function liveEntityCollection<A extends string, P extends string>(
+	thread: Thread, discoveryPattern: DatalogQueryPattern, liveAttributes: readonly A[],
+	opts: { stripAtPrefix: P },
+): Subscribable<ReadonlyMap<EntityID, Record<StripExplicitPrefix<A, P>, ApplogValue | null>>>
+export function liveEntityCollection<A extends string>(
+	thread: Thread, discoveryPattern: DatalogQueryPattern, liveAttributes: readonly A[],
+	opts: { mapKeys: (attr: A) => string },
+): Subscribable<ReadonlyMap<EntityID, Record<string, ApplogValue | null>>>
+export function liveEntityCollection<A extends string>(
+	thread: Thread, discoveryPattern: DatalogQueryPattern, liveAttributes: readonly A[],
+	opts: { stripAtPrefix?: true | string; mapKeys?: (attr: A) => string },
+): Subscribable<ReadonlyMap<EntityID, Record<string, ApplogValue | null>>>
+export function liveEntityCollection<A extends string>(
+	thread: Thread,
+	discoveryPattern: DatalogQueryPattern,
+	liveAttributes: readonly A[],
+	opts?: { stripAtPrefix?: true | string; mapKeys?: (attr: A) => string },
+): Subscribable<ReadonlyMap<EntityID, Record<string, ApplogValue | null>>> {
+	return _liveEntityCollection(thread, discoveryPattern, liveAttributes,
+		opts as { stripAtPrefix?: true | string; mapKeys?: (attr: string) => string })
+}
+
+const _liveEntityCollection = memoizedFn('liveEntityCollection',
+	function liveEntityCollection<A extends string>(
+		thread: Thread,
+		discoveryPattern: DatalogQueryPattern,
+		liveAttributes: readonly A[],
+		opts?: { stripAtPrefix?: true | string; mapKeys?: (attr: string) => string },
+	): Subscribable<ReadonlyMap<EntityID, Record<string, ApplogValue | null>>> {
+		DEBUG('liveEntityCollection', discoveryPattern, liveAttributes)
+		const discoveryAttr = discoveryPattern.at as string
+		const allAttrs = new Set([discoveryAttr, ...liveAttributes])
+		const filtered = rollingFilter(thread, { at: [...allAttrs] })
+		const isDiscoveryMatch = makeFilter(discoveryPattern)
+		const attrSet = new Set<string>(liveAttributes)
+		const key = resolveKeyMapper(opts)
+
+		const map = new Map<EntityID, Record<string, ApplogValue | null>>()
+
+		function makeRecord(entityId: EntityID): Record<string, ApplogValue | null> {
+			const record = {} as Record<string, ApplogValue | null>
+			for (const attr of liveAttributes) record[key(attr)] = null
+			// Backfill from current filtered state
+			for (const log of filtered.applogs) {
+				if (log.en === entityId && attrSet.has(log.at)) {
+					record[key(log.at)] = log.vl
+				}
+			}
+			return record
+		}
+
+		function buildFull(applogs: readonly Applog[]) {
+			map.clear()
+			for (const log of isDiscoveryMatch(applogs)) {
+				if (!map.has(log.en)) map.set(log.en, makeRecord(log.en))
+			}
+		}
+
+		function addLog(log: Applog) {
+			// Discovery match → ensure entity exists
+			if (isDiscoveryMatch([log]).length > 0 && !map.has(log.en)) {
+				map.set(log.en, makeRecord(log.en))
+				return // makeRecord already backfilled attrs
+			}
+			// Attribute match → update value
+			if (attrSet.has(log.at)) {
+				const record = map.get(log.en)
+				if (record) record[key(log.at)] = log.vl
+			}
+		}
+
+		function removeLog(log: Applog) {
+			if (isDiscoveryMatch([log]).length > 0) {
+				// Check if entity still has another discovery match
+				const stillDiscovered = filtered.applogs.some(
+					l => l.en === log.en && isDiscoveryMatch([l]).length > 0,
+				)
+				if (!stillDiscovered) {
+					map.delete(log.en)
+					return
+				}
+			}
+			if (attrSet.has(log.at)) {
+				const record = map.get(log.en)
+				if (record) {
+					// Find current value from remaining applogs
+					const current = filtered.applogs.find(l => l.en === log.en && l.at === log.at)
+					record[key(log.at)] = current?.vl ?? null
+				}
+			}
+		}
+
+		// Initial build
+		buildFull(filtered.applogs)
+
+		const result = new SubscribableImpl<ReadonlyMap<EntityID, Record<string, ApplogValue | null>>>(
+			map,
+			() => filtered.subscribe((event) => {
+				if (isInitEvent(event)) {
+					buildFull(event.init)
+				} else {
+					// Process removes before adds — LWW updates appear as remove+add in same delta
+					if (event.removed) for (const log of event.removed) removeLog(log)
+					for (const log of event.added) addLog(log)
+				}
+				result._set(map)
+			}, 'derived'),
+			{ equals: false },
+		)
+		return result
+	},
+)

package/src/query/liveFilterAndMap.test.ts

@@ -0,0 +1,102 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+import { finalizeApplogForInsert } from '../applog/applog-helpers.ts'
+import { sortApplogsByTs } from '../applog/applog-utils.ts'
+import type { Applog, ApplogForInsert } from '../applog/datom-types.ts'
+import { ThreadInMemory } from '../thread/writeable.ts'
+import { lastWriteWins, liveFilterAndMap } from './basic.ts'
+
+let tsCounter = 0
+function makeApplogs(inputs: ApplogForInsert[]): Applog[] {
+	const logs = inputs.map(input =>
+		finalizeApplogForInsert({
+			ts: new Date(1700000000000 + ++tsCounter * 1000).toISOString(),
+			pv: null,
+			ag: 'testAgent',
+			...input,
+		} as ApplogForInsert, {}),
+	)
+	sortApplogsByTs(logs)
+	return logs
+}
+
+let db: ReturnType<typeof ThreadInMemory.fromArray>
+
+beforeEach(() => {
+	db = ThreadInMemory.fromArray(
+		makeApplogs([
+			{ en: 'p1', at: 'person/name', vl: 'Alice', ag: 'testAgent' },
+			{ en: 'p2', at: 'person/name', vl: 'Bob', ag: 'testAgent' },
+		]),
+		'test-people',
+	)
+})
+
+describe('liveFilterAndMap — identity tracking', () => {
+	it('reflects added items via _push', () => {
+		const lww = lastWriteWins(db)
+		const result = liveFilterAndMap(lww, { at: 'person/name' }, 'vl')
+		const unsub = result.subscribe(() => {})
+
+		expect([...result.items].sort()).toEqual(['Alice', 'Bob'])
+
+		db.insert([{ en: 'p3', at: 'person/name', vl: 'Carol', ag: 'testAgent' }])
+
+		expect([...result.items].sort()).toEqual(['Alice', 'Bob', 'Carol'])
+		unsub()
+	})
+
+	it('reflects removed items via _remove (LWW supersedes)', () => {
+		const lww = lastWriteWins(db)
+		const result = liveFilterAndMap(lww, { at: 'person/name' }, 'vl')
+		const unsub = result.subscribe(() => {})
+
+		expect([...result.items].sort()).toEqual(['Alice', 'Bob'])
+
+		// Supersede p1's name — LWW emits removed: [oldP1], added: [newP1]
+		db.insert([{ en: 'p1', at: 'person/name', vl: 'Alicia', ag: 'testAgent' }])
+
+		expect([...result.items].sort()).toEqual(['Alicia', 'Bob'])
+		unsub()
+	})
+
+	it('handles successive supersedes (no leak in identity index)', () => {
+		const lww = lastWriteWins(db)
+		const result = liveFilterAndMap(lww, { at: 'person/name' }, 'vl')
+		const unsub = result.subscribe(() => {})
+
+		db.insert([{ en: 'p1', at: 'person/name', vl: 'Alicia', ag: 'testAgent' }])
+		db.insert([{ en: 'p1', at: 'person/name', vl: 'Alex', ag: 'testAgent' }])
+		db.insert([{ en: 'p2', at: 'person/name', vl: 'Bobby', ag: 'testAgent' }])
+
+		expect([...result.items].sort()).toEqual(['Alex', 'Bobby'])
+		unsub()
+	})
+
+	it('mapper as object form — removed routes through cidToMapped', () => {
+		const lww = lastWriteWins(db)
+		const result = liveFilterAndMap(lww, { at: 'person/name' }, { en: 'id', vl: 'name' })
+		const unsub = result.subscribe(() => {})
+
+		expect(result.items).toHaveLength(2)
+		expect(result.items.find(r => r.id === 'p1')?.name).toBe('Alice')
+
+		db.insert([{ en: 'p1', at: 'person/name', vl: 'Alicia', ag: 'testAgent' }])
+
+		expect(result.items).toHaveLength(2)
+		expect(result.items.find(r => r.id === 'p1')?.name).toBe('Alicia')
+		unsub()
+	})
+
+	it('mapper as function form — removed routes through cidToMapped', () => {
+		const lww = lastWriteWins(db)
+		const result = liveFilterAndMap(lww, { at: 'person/name' }, log => `${log.en}=${log.vl}`)
+		const unsub = result.subscribe(() => {})
+
+		expect([...result.items].sort()).toEqual(['p1=Alice', 'p2=Bob'])
+
+		db.insert([{ en: 'p1', at: 'person/name', vl: 'Alicia', ag: 'testAgent' }])
+
+		expect([...result.items].sort()).toEqual(['p1=Alicia', 'p2=Bob'])
+		unsub()
+	})
+})

package/src/query/matchers.ts

@@ -0,0 +1,8 @@
+import { DatomPart } from '../applog/datom-types.ts'
+
+export function includes(str: string) {
+	return (vl: DatomPart) => vl?.includes?.(str)
+}
+export function includedIn(arr: string[]) {
+	return (vl: DatomPart) => arr?.includes?.(vl)
+}

package/src/query/memoized.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, it, vi } from 'vitest'
+import { memoizedFn, refCountedMemoizedFn } from './memoized.ts'
+
+describe('memoizedFn', () => {
+	it('returns cached result for same args', () => {
+		const fn = vi.fn((a: number, b: number) => a + b)
+		const memo = memoizedFn('add', fn)
+
+		expect(memo(1, 2)).toBe(3)
+		expect(memo(1, 2)).toBe(3)
+		expect(fn).toHaveBeenCalledTimes(1)
+	})
+
+	it('computes fresh result for different args', () => {
+		const fn = vi.fn((a: number) => a * 2)
+		const memo = memoizedFn('double', fn)
+
+		expect(memo(3)).toBe(6)
+		expect(memo(5)).toBe(10)
+		expect(fn).toHaveBeenCalledTimes(2)
+	})
+
+	it('deep-compares non-Thread args', () => {
+		const fn = vi.fn((obj: { x: number }) => obj.x * 2)
+		const memo = memoizedFn('deep', fn)
+
+		expect(memo({ x: 3 })).toBe(6)
+		expect(memo({ x: 3 })).toBe(6) // new object, same shape
+		expect(fn).toHaveBeenCalledTimes(1)
+	})
+
+	it('evicts oldest entry when maxSize exceeded', () => {
+		const fn = vi.fn((n: number) => n * 10)
+		const memo = memoizedFn('lru', fn, { maxSize: 2 })
+
+		memo(1) // cache: [1]
+		memo(2) // cache: [1, 2]
+		memo(3) // cache: [2, 3] — evicts 1
+
+		expect(fn).toHaveBeenCalledTimes(3)
+
+		// 2 and 3 are cached
+		memo(2)
+		memo(3)
+		expect(fn).toHaveBeenCalledTimes(3)
+
+		// 1 was evicted, needs recomputation
+		memo(1)
+		expect(fn).toHaveBeenCalledTimes(4)
+	})
+})
+
+describe('refCountedMemoizedFn', () => {
+	it('returns same result for same args, increments refCount', () => {
+		const fn = vi.fn((n: number) => ({ value: n * 2 }))
+		const memo = refCountedMemoizedFn('rc', fn)
+
+		const ref1 = memo(5)
+		const ref2 = memo(5)
+		expect(ref1.value).toBe(ref2.value) // same object
+		expect(fn).toHaveBeenCalledTimes(1)
+	})
+
+	it('calls onCleanup when last ref released', () => {
+		const cleanup = vi.fn()
+		const fn = vi.fn((n: number) => n * 2)
+		const memo = refCountedMemoizedFn('rc', fn, { onCleanup: cleanup })
+
+		const ref1 = memo(5)
+		const ref2 = memo(5)
+
+		ref1.release()
+		expect(cleanup).not.toHaveBeenCalled()
+
+		ref2.release()
+		expect(cleanup).toHaveBeenCalledOnce()
+		expect(cleanup).toHaveBeenCalledWith(10, 5) // result, ...args
+	})
+
+	it('recomputes after full cleanup', () => {
+		const fn = vi.fn((n: number) => n * 2)
+		const memo = refCountedMemoizedFn('rc', fn, { onCleanup: () => {} })
+
+		const ref1 = memo(3)
+		ref1.release()
+		expect(fn).toHaveBeenCalledTimes(1)
+
+		const ref2 = memo(3)
+		expect(fn).toHaveBeenCalledTimes(2)
+		ref2.release()
+	})
+
+	it('release is idempotent', () => {
+		const cleanup = vi.fn()
+		const fn = vi.fn((n: number) => n * 2)
+		const memo = refCountedMemoizedFn('rc', fn, { onCleanup: cleanup })
+
+		const ref = memo(1)
+		ref.release()
+		ref.release() // second release is a no-op
+		expect(cleanup).toHaveBeenCalledOnce()
+	})
+
+	it('grace period delays cleanup', () => {
+		vi.useFakeTimers()
+		const cleanup = vi.fn()
+		const fn = vi.fn((n: number) => n * 2)
+		const memo = refCountedMemoizedFn('rc', fn, {
+			onCleanup: cleanup,
+			gracePeriodMs: 100,
+		})
+
+		const ref = memo(5)
+		ref.release()
+
+		// Not cleaned up yet
+		expect(cleanup).not.toHaveBeenCalled()
+
+		// Re-acquire within grace period
+		const ref2 = memo(5)
+		expect(fn).toHaveBeenCalledTimes(1) // reused, not recomputed
+
+		vi.advanceTimersByTime(200)
+		expect(cleanup).not.toHaveBeenCalled() // still held by ref2
+
+		ref2.release()
+		vi.advanceTimersByTime(50)
+		expect(cleanup).not.toHaveBeenCalled() // still in grace
+
+		vi.advanceTimersByTime(60)
+		expect(cleanup).toHaveBeenCalledOnce()
+
+		vi.useRealTimers()
+	})
+
+	it('separate entries for different args', () => {
+		const cleanup = vi.fn()
+		const fn = vi.fn((n: number) => n * 2)
+		const memo = refCountedMemoizedFn('rc', fn, { onCleanup: cleanup })
+
+		const refA = memo(1)
+		const refB = memo(2)
+		expect(fn).toHaveBeenCalledTimes(2)
+
+		refA.release()
+		expect(cleanup).toHaveBeenCalledWith(2, 1)
+
+		refB.release()
+		expect(cleanup).toHaveBeenCalledWith(4, 2)
+	})
+})

package/src/query/memoized.ts

@@ -0,0 +1,180 @@
+/**
+ * memoizedFn — Simple argument memoization without MobX.
+ *
+ * Replaces computedFnDeepCompare for query functions.
+ * With lazy subscribe (SubscribableArray), there's no urgency to clean up
+ * cached entries — unsubscribed entries are just plain arrays in memory.
+ *
+ * refCountedMemoizedFn — Ref-counted memoization for reactive results.
+ * Returns a wrapper that increments a ref count on each call and decrements
+ * on dispose(). When refCount hits 0, the entry is cleaned up (with optional
+ * grace period).
+ */
+
+import { isEqual } from 'lodash-es'
+import { Thread } from '../thread/basic.ts'
+
+/** Deep-compare args, but Thread instances by identity (same as MobX version) */
+function compareStructural(argsA: any[], argsB: any[], versionsA?: number[]): boolean {
+	if (argsA.length !== argsB.length) return false
+	for (let i = 0; i < argsA.length; i++) {
+		if (argsA[i] instanceof Thread) {
+			if (argsB[i] !== argsA[i]) return false
+			// Check if thread was mutated since the cache entry was created
+			if (versionsA && versionsA[i] !== undefined && argsB[i]._version !== versionsA[i]) return false
+		} else {
+			if (!isEqual(argsA[i], argsB[i])) return false
+		}
+	}
+	return true
+}
+
+/** Snapshot Thread._version for each Thread arg */
+function snapshotVersions(args: any[]): number[] {
+	return args.map(a => a instanceof Thread ? a._version : undefined)
+}
+
+interface MemoizedFnOptions {
+	argsEqual?: (a: any[], b: any[]) => boolean
+	argsDebugName?: (...args: any[]) => string
+	/** Max cache entries. Oldest evicted when exceeded. Default: unlimited. */
+	maxSize?: number
+}
+
+export function memoizedFn<T extends (...args: any[]) => any>(
+	name: string,
+	fn: T,
+	opts?: MemoizedFnOptions,
+): T {
+	// TODO: cache grows unboundedly by default — see todo/2026-04-17_ciao-mobx/memoized-cache-cleanup.md for analysis
+	const cache: Array<{ args: any[]; versions: number[]; result: any }> = []
+	const argsEqual = opts?.argsEqual ?? compareStructural
+	const maxSize = opts?.maxSize ?? Infinity
+
+	return function (this: any, ...args: any[]) {
+		const existing = cache.find(entry => argsEqual(entry.args, args, entry.versions))
+		if (existing) return existing.result
+
+		const result = fn.apply(this, args)
+
+		if (cache.length >= maxSize) {
+			cache.shift() // evict oldest
+		}
+		cache.push({ args, versions: snapshotVersions(args), result })
+		return result
+	} as any
+}
+
+// ═══════════════════════════════════════════════════════════════
+// refCountedMemoizedFn — ref-counted cache with disposal
+// ═══════════════════════════════════════════════════════════════
+
+/** A result wrapper returned by refCountedMemoizedFn. Call release() when done. */
+export interface RefCounted<T> {
+	readonly value: T
+	/** Decrement ref count. When it reaches 0, the cache entry is cleaned up. */
+	release(): void
+}
+
+interface RefCountedOptions<T extends (...args: any[]) => any> {
+	argsEqual?: (a: any[], b: any[]) => boolean
+	argsDebugName?: (...args: any[]) => string
+	/**
+	 * Called when the last reference is released and the entry is evicted.
+	 * Use to tear down subscriptions, dispose SubscribableArrays, etc.
+	 */
+	onCleanup?: (result: ReturnType<T>, ...args: Parameters<T>) => void
+	/**
+	 * Grace period in ms before actually cleaning up after refCount hits 0.
+	 * If someone re-acquires within this window, the entry is reused.
+	 * Default: 0 (immediate cleanup).
+	 */
+	gracePeriodMs?: number
+}
+
+interface CacheEntry<T> {
+	args: any[]
+	result: T
+	refCount: number
+	graceTimer: ReturnType<typeof setTimeout> | null
+}
+
+/**
+ * Creates a memoized function whose results are ref-counted.
+ *
+ * Currently unused — doesn't fit liveQuery's recursive multi-step structure
+ * (API break, cache loss on pattern change without grace period).
+ * See todo/2026-04-17_ciao-mobx/memoized-cache-cleanup.md for full analysis.
+ *
+ * Each call returns `RefCounted<ReturnType<fn>>`. Multiple calls with the same
+ * args return the same cached result with an incremented ref count.
+ * When all holders call `release()`, the cache entry is cleaned up
+ * (subject to optional grace period).
+ *
+ * Usage:
+ * ```
+ * const getFiltered = refCountedMemoizedFn('rollingFilter', (thread, pattern) => {
+ *   // ... expensive setup, returns MappedThread
+ * }, { onCleanup: (result) => result.dispose() })
+ *
+ * const ref = getFiltered(myThread, myPattern)
+ * // use ref.value (the MappedThread)
+ * ref.release() // decrement; when last holder releases, onCleanup fires
+ * ```
+ */
+export function refCountedMemoizedFn<T extends (...args: any[]) => any>(
+	name: string,
+	fn: T,
+	opts?: RefCountedOptions<T>,
+): (...args: Parameters<T>) => RefCounted<ReturnType<T>> {
+	const cache: CacheEntry<ReturnType<T>>[] = []
+	const argsEqual = opts?.argsEqual ?? compareStructural
+	const gracePeriodMs = opts?.gracePeriodMs ?? 0
+
+	function evict(entry: CacheEntry<ReturnType<T>>, args: any[]) {
+		const idx = cache.indexOf(entry)
+		if (idx >= 0) cache.splice(idx, 1)
+		opts?.onCleanup?.(entry.result, ...args as any)
+	}
+
+	return function (this: any, ...args: Parameters<T>): RefCounted<ReturnType<T>> {
+		let entry = cache.find(e => argsEqual(e.args, args))
+
+		if (entry) {
+			// Cancel pending grace-period cleanup
+			if (entry.graceTimer !== null) {
+				clearTimeout(entry.graceTimer)
+				entry.graceTimer = null
+			}
+			entry.refCount++
+		} else {
+			const result = fn.apply(this, args)
+			entry = { args, result, refCount: 1, graceTimer: null }
+			cache.push(entry)
+		}
+
+		const capturedEntry = entry
+		let released = false
+
+		return {
+			get value() { return capturedEntry.result },
+			release() {
+				if (released) return // idempotent
+				released = true
+				capturedEntry.refCount--
+
+				if (capturedEntry.refCount <= 0) {
+					if (gracePeriodMs > 0) {
+						capturedEntry.graceTimer = setTimeout(() => {
+							if (capturedEntry.refCount <= 0) {
+								evict(capturedEntry, args)
+							}
+						}, gracePeriodMs)
+					} else {
+						evict(capturedEntry, args)
+					}
+				}
+			},
+		}
+	}
+}

package/src/query/query-steps.ts

@@ -0,0 +1,4 @@
+export const q = {
+	not: () => {
+	},
+}