@wovin/core 0.0.0-ciao-mobx-955482e8

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/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: () => {
+	},
+}