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

package/src/query/subscribable.ts

@@ -0,0 +1,225 @@
+/**
+ * Push-based subscribable primitives for the query system.
+ *
+ * Two primitives:
+ * - Subscribable<T>     — any value + "changed" notifications
+ * - SubscribableArray<T> — array + incremental delta events (added/removed)
+ *
+ * Key property: **lazy subscribe** — upstream subscriptions only activate
+ * when the first subscriber attaches, and deactivate when the last leaves.
+ * This means one-off reads (.value / .items) have zero subscription overhead.
+ */
+
+export type Unsubscribe = () => void
+
+// ═══════════════════════════════════════════════════════════════
+// Subscribable<T> — generic single-value
+// ═══════════════════════════════════════════════════════════════
+
+export interface Subscribable<T> {
+	/** Current value — plain read, no side effects */
+	readonly value: T
+
+	/**
+	 * Subscribe to change notifications.
+	 * - First call activates upstream subscriptions (lazy).
+	 * - Callback does NOT fire immediately — read .value for current state.
+	 * - Callback fires whenever .value changes.
+	 * - Last unsubscribe deactivates upstream.
+	 */
+	subscribe(cb: () => void, type?: 'derived' | 'reaction'): Unsubscribe
+
+	/** Tear down all internal subscriptions */
+	dispose(): void
+}
+
+/**
+ * Implementation of Subscribable<T> with lazy upstream activation.
+ */
+export class SubscribableImpl<T> implements Subscribable<T> {
+	private _value: T
+	private _derivedSubscribers: (() => void)[] = []
+	private _subscribers: (() => void)[] = []
+	private _upstreamActive = false
+	private _activateUpstream: (() => Unsubscribe) | null
+	private _deactivateUpstream: Unsubscribe | null = null
+	private _equals: (a: T, b: T) => boolean
+
+	constructor(
+		initialValue: T,
+		activateUpstream?: () => Unsubscribe,
+		opts?: { equals?: false | ((a: T, b: T) => boolean) },
+	) {
+		this._value = initialValue
+		this._activateUpstream = activateUpstream ?? null
+		this._equals = opts?.equals === false ? () => false : (opts?.equals ?? ((a, b) => a === b))
+	}
+
+	get value(): T { return this._value }
+
+	subscribe(cb: () => void, type?: 'derived' | 'reaction'): Unsubscribe {
+		if (!this._upstreamActive && this._activateUpstream) {
+			this._deactivateUpstream = this._activateUpstream()
+			this._upstreamActive = true
+		}
+
+		const list = type === 'derived' ? this._derivedSubscribers : this._subscribers
+		list.push(cb)
+		// No immediate callback — subscriber reads .value for current state
+
+		return () => {
+			const idx = list.indexOf(cb)
+			if (idx >= 0) list.splice(idx, 1)
+
+			if (this._derivedSubscribers.length === 0 && this._subscribers.length === 0 && this._upstreamActive) {
+				this._deactivateUpstream?.()
+				this._deactivateUpstream = null
+				this._upstreamActive = false
+			}
+		}
+	}
+
+	/** Update value and notify subscribers (skips if equals check passes) */
+	_set(value: T) {
+		if (this._equals(value, this._value)) return
+		this._value = value
+		this._notify()
+	}
+
+	private _notify() {
+		const derived = [...this._derivedSubscribers]
+		for (const sub of derived) sub()
+		const subs = [...this._subscribers]
+		for (const sub of subs) sub()
+	}
+
+	dispose() {
+		this._deactivateUpstream?.()
+		this._deactivateUpstream = null
+		this._derivedSubscribers.length = 0
+		this._subscribers.length = 0
+		this._upstreamActive = false
+	}
+}
+
+// ═══════════════════════════════════════════════════════════════
+// SubscribableArray<T> — array with delta events
+// ═══════════════════════════════════════════════════════════════
+
+/** Delta events — mirrors ThreadEvent shape */
+export type ArrayEvent<T> =
+	| { init: readonly T[] }
+	| { added: readonly T[]; removed: readonly T[] | null }
+
+/** Type guard for init events. Same logic as thread's isInitEvent. */
+export function isArrayInitEvent<T>(event: ArrayEvent<T>): event is { init: readonly T[] } {
+	return (event as any).init !== undefined
+}
+
+export interface SubscribableArray<T> {
+	/** Current snapshot — plain readonly array */
+	readonly items: readonly T[]
+
+	/** Length shortcut */
+	readonly length: number
+
+	/**
+	 * Subscribe to delta events.
+	 * - First call activates upstream subscriptions (lazy).
+	 * - No init event on subscribe — read .items for current state.
+	 * - Receives `{ init }` only on genuine resets (triggerRemap).
+	 * - Last unsubscribe deactivates upstream.
+	 */
+	subscribe(cb: (event: ArrayEvent<T>) => void, type?: 'derived' | 'reaction'): Unsubscribe
+
+	/** Tear down all internal subscriptions */
+	dispose(): void
+}
+
+/**
+ * Implementation of SubscribableArray with lazy upstream activation.
+ *
+ * Constructor takes initial items (computed synchronously at query time)
+ * and an optional activation function that sets up upstream subscriptions.
+ * The activation function is only called on first `.subscribe()`.
+ */
+export class SubscribableArrayImpl<T> implements SubscribableArray<T> {
+	private _items: T[]
+	private _derivedSubscribers: ((event: ArrayEvent<T>) => void)[] = []
+	private _subscribers: ((event: ArrayEvent<T>) => void)[] = []
+	private _upstreamActive = false
+	private _activateUpstream: (() => Unsubscribe) | null
+	private _deactivateUpstream: Unsubscribe | null = null
+
+	constructor(
+		initialItems: T[],
+		activateUpstream?: () => Unsubscribe,
+	) {
+		this._items = initialItems
+		this._activateUpstream = activateUpstream ?? null
+	}
+
+	get items(): readonly T[] { return this._items }
+	get length(): number { return this._items.length }
+
+	subscribe(cb: (event: ArrayEvent<T>) => void, type?: 'derived' | 'reaction'): Unsubscribe {
+		// Activate upstream on first subscriber (lazy)
+		if (!this._upstreamActive && this._activateUpstream) {
+			this._deactivateUpstream = this._activateUpstream()
+			this._upstreamActive = true
+		}
+
+		const list = type === 'derived' ? this._derivedSubscribers : this._subscribers
+		list.push(cb)
+		// No init event — subscriber reads .items for current state
+
+		return () => {
+			const idx = list.indexOf(cb)
+			if (idx >= 0) list.splice(idx, 1)
+
+			// Deactivate upstream when last subscriber leaves
+			if (this._derivedSubscribers.length === 0 && this._subscribers.length === 0 && this._upstreamActive) {
+				this._deactivateUpstream?.()
+				this._deactivateUpstream = null
+				this._upstreamActive = false
+			}
+		}
+	}
+
+	/** Push items and notify subscribers */
+	_push(...items: T[]) {
+		this._items.push(...items)
+		this._notify({ added: items, removed: null })
+	}
+
+	/** Remove items and notify subscribers */
+	_remove(items: readonly T[]) {
+		for (const item of items) {
+			const idx = this._items.indexOf(item)
+			if (idx >= 0) this._items.splice(idx, 1)
+		}
+		this._notify({ added: [], removed: items })
+	}
+
+	/** Full reset — replace all items */
+	_reset(items: T[]) {
+		this._items = items
+		this._notify({ init: [...this._items] })
+	}
+
+	private _notify(event: ArrayEvent<T>) {
+		// Snapshot: subscriber callbacks may synchronously unsubscribe during iteration
+		const derived = [...this._derivedSubscribers]
+		for (const sub of derived) sub(event)
+		const subs = [...this._subscribers]
+		for (const sub of subs) sub(event)
+	}
+
+	dispose() {
+		this._deactivateUpstream?.()
+		this._deactivateUpstream = null
+		this._derivedSubscribers.length = 0
+		this._subscribers.length = 0
+		this._upstreamActive = false
+	}
+}

package/src/query/types.ts

@@ -0,0 +1,155 @@
+import { joinThreads } from '../applog/applog-helpers.ts'
+import { SearchContext } from '../applog/datom-types.ts'
+import type { Thread } from '../thread/basic.ts'
+import { ArrayEvent, SubscribableArray, SubscribableArrayImpl, Unsubscribe } from './subscribable.ts'
+
+export class QueryNode {
+	constructor(
+		readonly logsOfThisNode: Thread,
+		readonly variables: SearchContext,
+		readonly prevNode: QueryNode | null = null,
+	) {}
+	get record() {
+		return this.variables // alias for end-user consumption
+	}
+
+	get threadOfTrail() {
+		if (!this.prevNode) return this.logsOfThisNode
+		return joinThreads([
+			this.logsOfThisNode,
+			this.prevNode.threadOfTrail,
+		])
+	}
+	get trailLogs() {
+		return this.threadOfTrail.applogs
+	}
+}
+
+/** Shared interface for query results (one-off and live) */
+export interface IQueryResult {
+	readonly nodes: readonly QueryNode[]
+	readonly size: number
+	readonly isEmpty: boolean
+	readonly records: readonly SearchContext[]
+	readonly leafNodeLogs: readonly import('../applog/datom-types').Applog[]
+	readonly leafNodeThread: Thread
+	readonly threadOfAllTrails: Thread
+	readonly thread: Thread
+	readonly allApplogs: readonly import('../applog/datom-types').Applog[]
+}
+
+/**
+ * One-off query result — plain frozen snapshot.
+ * No subscribe method. No stale-data risk.
+ */
+export class QueryResult implements IQueryResult {
+	constructor(
+		readonly nodes: readonly QueryNode[],
+	) {}
+
+	get size() {
+		return this.nodes.length
+	}
+	get isEmpty() {
+		return this.nodes.length === 0
+	}
+	get untrackedSize() {
+		return this.nodes.length
+	}
+
+	get records(): readonly SearchContext[] {
+		return this.nodes.map(({ variables }) => variables)
+	}
+	get leafNodeThread() {
+		return joinThreads(
+			this.nodes.map(({ logsOfThisNode: thread }) => thread),
+		)
+	}
+	get leafNodeLogSet() {
+		return this.nodes.map(({ logsOfThisNode: thread }) => thread.applogs)
+	}
+	get leafNodeLogs() {
+		return this.nodes.flatMap(({ logsOfThisNode: thread }) => thread.applogs)
+	}
+	get threadOfAllTrails() {
+		return joinThreads(this.nodes.map(node => node.threadOfTrail))
+	}
+	get thread() {
+		return this.threadOfAllTrails // alias
+	}
+	get allApplogs() {
+		return this.threadOfAllTrails.applogs
+	}
+}
+
+/**
+ * Live query result — eagerly activated, always up-to-date.
+ *
+ * `.nodes` returns the current live view.
+ * `.subscribe()` receives future delta events (consistent with current state).
+ * Must call `.dispose()` when done to tear down upstream subscriptions.
+ */
+export class LiveQueryResult implements IQueryResult {
+	constructor(
+		private _source: SubscribableArray<QueryNode>,
+		activate = true,
+	) {
+		if (activate) {
+			// Eagerly activate: subscribe with a no-op to start upstream.
+			// Store unsub so dispose() can tear it down.
+			this._activationUnsub = this._source.subscribe(() => {})
+		}
+	}
+
+	private _activationUnsub: Unsubscribe | null = null
+
+	/** Subscribe to node change events. Callback fires on future changes only. */
+	subscribe(cb: (event: ArrayEvent<QueryNode>) => void, type?: 'derived' | 'reaction'): Unsubscribe {
+		return this._source.subscribe(cb, type)
+	}
+
+	/** Current nodes — live view, always up-to-date while not disposed */
+	get nodes(): readonly QueryNode[] {
+		return this._source.items
+	}
+
+	get size() {
+		return this._source.length
+	}
+	get isEmpty() {
+		return this._source.length === 0
+	}
+	get untrackedSize() {
+		return this._source.length
+	}
+
+	get records(): readonly SearchContext[] {
+		return this.nodes.map(({ variables }) => variables)
+	}
+	get leafNodeThread() {
+		return joinThreads(
+			this.nodes.map(({ logsOfThisNode: thread }) => thread),
+		)
+	}
+	get leafNodeLogSet() {
+		return this.nodes.map(({ logsOfThisNode: thread }) => thread.applogs)
+	}
+	get leafNodeLogs() {
+		return this.nodes.flatMap(({ logsOfThisNode: thread }) => thread.applogs)
+	}
+	get threadOfAllTrails() {
+		return joinThreads(this.nodes.map(node => node.threadOfTrail))
+	}
+	get thread() {
+		return this.threadOfAllTrails // alias
+	}
+	get allApplogs() {
+		return this.threadOfAllTrails.applogs
+	}
+
+	dispose() {
+		this._activationUnsub?.()
+		this._activationUnsub = null
+		this._source.dispose()
+	}
+}

package/src/query.ts

@@ -0,0 +1,7 @@
+export * from './utils/debug-name.ts'
+export * from './query/basic.ts'
+export * from './query/divergences.ts'
+export * from './query/matchers.ts'
+export * from './query/memoized.ts'
+export * from './query/subscribable.ts'
+export * from './query/types.ts'

package/src/retrieve/index.ts

@@ -0,0 +1 @@
+export * from './update-thread.ts'

package/src/retrieve/update-thread.ts

@@ -0,0 +1,248 @@
+import { CarReader } from '@ipld/car'
+import * as dagJson from '@ipld/dag-json'
+import { Logger } from 'besonders-logger'
+import { CID } from 'multiformats/cid'
+import type { Applog } from '../applog/datom-types.ts'
+import { removeDuplicateAppLogs } from '../applog/applog-utils.ts'
+import type { SnapRootBlock, SnapBlockLogsOrChunks } from '../pubsub/pubsub-types.ts'
+import { unchunkApplogsBlock } from '../pubsub/snap-push.ts'
+import { areCidsEqual } from '../ipfs/ipfs-utils.ts'
+import type { WriteableThread } from '../thread/writeable.ts'
+import type { BlockStore } from '../blockstore/index.ts'
+
+const { WARN, LOG, DEBUG, VERBOSE, ERROR } = Logger.setup(Logger.INFO) // eslint-disable-line no-unused-vars
+
+/**
+ * Block retrieval abstraction - fetch or get blocks.
+ * Implemented by gateway retriever or local blockstore.
+ */
+export interface BlockRetriever {
+	/** Get single block by CID */
+	get(cid: CID): Promise<Uint8Array>
+	/** Get all blocks in DAG rooted at CID (for applogs/info sub-DAGs) */
+	getDag(cid: CID): AsyncIterable<{ cid: CID; bytes: Uint8Array }>
+}
+
+/**
+ * Wrap a BlockRetriever so fetched blocks flow through a BlockStore.
+ * - get: delegates to store.get() (which handles local-first / remote fallback)
+ * - getDag: streams from source, puts each block into store
+ */
+export function withBlockCache(
+	source: BlockRetriever,
+	store: BlockStore,
+): BlockRetriever {
+	return {
+		get: (cid) => store.get(cid),
+		async *getDag(cid) {
+			for await (const block of source.getDag(cid)) {
+				await store.put(block.cid, block.bytes)
+				yield block
+			}
+		},
+	}
+}
+
+/**
+ * Options for updateThreadFromSnapshot
+ */
+export interface UpdateOptions {
+	/** CID of last included snapshot - exclude this and older snapshots */
+	excludeSnapshotCID?: CID
+	/** Stop when we reach this counter (walking backwards) */
+	stopAtCounter?: number
+	/** Maximum number of snapshots to traverse (default: 100) */
+	maxDepth?: number
+}
+
+/**
+ * Result from updateThreadFromSnapshot
+ */
+export interface UpdateResult {
+	/** Root CID that was fetched */
+	cid: CID
+	/** All applogs decoded from the chain */
+	applogs: Applog[]
+	/** Count of applogs actually inserted (not duplicates) */
+	insertedCount: number
+	/** Number of snapshots traversed */
+	snapshotCount: number
+	/** Counter range encountered (min/max) */
+	counterRange?: { minCounter: number; maxCounter: number }
+}
+
+/**
+ * Simple in-memory block store used during snapshot chain fetch.
+ */
+interface MemoryBlockStore {
+	get(cid: CID): Uint8Array | undefined
+	put(cid: CID, bytes: Uint8Array): void
+}
+
+function createMemoryBlockStore(): MemoryBlockStore {
+	const blocks = new Map<string, Uint8Array>()
+	return {
+		get(cid: CID) {
+			return blocks.get(cid.toV1().toString())
+		},
+		put(cid: CID, bytes: Uint8Array) {
+			blocks.set(cid.toV1().toString(), bytes)
+		},
+	}
+}
+
+async function getDecodedBlock<T>(blockStore: MemoryBlockStore, cid: CID): Promise<T | null> {
+	const bytes = blockStore.get(cid)
+	if (!bytes) return null
+	return dagJson.decode(bytes) as T
+}
+
+/**
+ * Fetch snapshot chain from CID using a BlockRetriever, decode applogs, insert into thread.
+ * Stops before excludeSnapshotCID if provided (incremental update).
+ *
+ * @param thread - WriteableThread to insert applogs into
+ * @param cid - Root CID of the snapshot to start from
+ * @param retriever - BlockRetriever for fetching blocks
+ * @param options - Optional configuration
+ * @returns UpdateResult with applogs and counts
+ */
+export async function updateThreadFromSnapshot(
+	thread: WriteableThread,
+	cid: CID,
+	retriever: BlockRetriever,
+	options?: UpdateOptions
+): Promise<UpdateResult> {
+	const { excludeSnapshotCID, stopAtCounter, maxDepth = 100 } = options ?? {}
+
+	DEBUG('[updateThreadFromSnapshot] starting from', cid.toString(), {
+		excludeSnapshotCID: excludeSnapshotCID?.toString(),
+		stopAtCounter,
+		maxDepth,
+	})
+
+	const blockStore = createMemoryBlockStore()
+	const visited = new Set<string>()
+	let currentCID: CID | undefined = cid
+	let snapshotCount = 0
+	const allApplogs: Applog[] = []
+	let minCounter = Infinity
+	let maxCounter = -Infinity
+	let lastCounter: number | undefined
+
+	while (currentCID && snapshotCount < maxDepth) {
+		const cidStr = currentCID.toString()
+
+		// Loop detection
+		if (visited.has(cidStr)) {
+			throw ERROR('[updateThreadFromSnapshot] snapshot chain has a loop', {
+				currentCID: cidStr,
+				visited: [...visited],
+			})
+		}
+		visited.add(cidStr)
+
+		// Check stop condition BEFORE fetching content
+		if (excludeSnapshotCID && areCidsEqual(currentCID, excludeSnapshotCID)) {
+			DEBUG('[updateThreadFromSnapshot] reached excludeSnapshotCID, stopping', excludeSnapshotCID.toString())
+			break
+		}
+
+		// 1. Fetch root block
+		DEBUG('[updateThreadFromSnapshot] fetching root block', cidStr)
+		const rootBytes = await retriever.get(currentCID)
+		blockStore.put(currentCID, rootBytes)
+
+		// Parse root to get applogs, info, prev CIDs
+		const root = dagJson.decode(rootBytes) as SnapRootBlock
+
+		// Track counter range and validate sequentiality
+		if (typeof root.prevCounter === 'number') {
+			minCounter = Math.min(minCounter, root.prevCounter)
+			maxCounter = Math.max(maxCounter, root.prevCounter)
+
+			// Validate sequentiality (walking backwards, counter should decrease)
+			if (lastCounter !== undefined && root.prevCounter !== lastCounter - 1) {
+				WARN('[updateThreadFromSnapshot] counter gap detected', {
+					expected: lastCounter - 1,
+					got: root.prevCounter,
+				})
+			}
+			lastCounter = root.prevCounter
+		}
+
+		// Stop condition based on counter
+		if (stopAtCounter !== undefined && typeof root.prevCounter === 'number' && root.prevCounter <= stopAtCounter) {
+			DEBUG('[updateThreadFromSnapshot] reached stopAtCounter', { stopAtCounter, prevCounter: root.prevCounter })
+			break
+		}
+
+		// 2. Fetch applogs DAG
+		DEBUG('[updateThreadFromSnapshot] fetching applogs', root.applogs.toString())
+		for await (const { cid: blockCid, bytes } of retriever.getDag(root.applogs)) {
+			blockStore.put(blockCid, bytes)
+		}
+
+		// 3. Fetch info DAG
+		DEBUG('[updateThreadFromSnapshot] fetching info', root.info.toString())
+		for await (const { cid: blockCid, bytes } of retriever.getDag(root.info)) {
+			blockStore.put(blockCid, bytes)
+		}
+
+		// Decode applogs from this snapshot
+		const applogsBlock = await getDecodedBlock<SnapBlockLogsOrChunks>(blockStore, root.applogs)
+		if (!applogsBlock) {
+			throw ERROR('[updateThreadFromSnapshot] applogs block not found', { cid: root.applogs.toString() })
+		}
+
+		// Use the unchunk helper which handles both chunked and non-chunked formats
+		const applogCIDs = await unchunkApplogsBlock(applogsBlock, {
+			get: async (cid: CID) => blockStore.get(cid)!,
+		})
+
+		// Resolve each applog CID to actual applog data
+		for (const applogCID of applogCIDs) {
+			const applog = await getDecodedBlock<Applog>(blockStore, applogCID)
+			if (!applog) {
+				WARN('[updateThreadFromSnapshot] applog not found:', applogCID.toString())
+				continue
+			}
+			// Normalize pv field if it's a CID instance
+			if ((applog.pv as any) instanceof CID) {
+				applog.pv = (applog.pv as any as CID).toV1().toString()
+			}
+			allApplogs.push({
+				...applog,
+				cid: applogCID.toV1().toString(),
+			})
+		}
+
+		snapshotCount++
+		currentCID = root.prev // Move to previous snapshot
+	}
+
+	DEBUG('[updateThreadFromSnapshot] fetched', {
+		snapshotCount,
+		applogCount: allApplogs.length,
+		rootCID: cid.toString(),
+	})
+
+	// Deduplicate applogs (in case of overlapping snapshots)
+	const deduplicated = removeDuplicateAppLogs(allApplogs, 'cleanup')
+
+	// Insert into thread
+	const inserted = thread.insertMissing(deduplicated, false)
+
+	DEBUG('[updateThreadFromSnapshot] inserted', {
+		insertedCount: inserted.length,
+		duplicateCount: deduplicated.length - inserted.length,
+	})
+
+	return {
+		cid,
+		applogs: deduplicated,
+		insertedCount: inserted.length,
+		snapshotCount,
+		counterRange: minCounter !== Infinity ? { minCounter, maxCounter } : undefined,
+	}
+}

package/src/retrieve.ts

@@ -0,0 +1 @@
+export * from './retrieve/update-thread.ts'