@wovin/core 0.1.36 → 0.2.2

package/src/query/subscribable.ts

@@ -0,0 +1,234 @@
+/**
+ * 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.
+	 *
+	 * NOTE: only stays current while at least one subscriber is active
+	 * (upstream is lazily activated on first `.subscribe()`). With no
+	 * subscribers this returns the initial snapshot from construction
+	 * and does NOT reflect later mutations. Tests/consumers that want
+	 * to observe updates must hold a subscription (`subscribe(() => {})`
+	 * is enough).
+	 */
+	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/withoutDeleted.test.ts

@@ -0,0 +1,204 @@
+/**
+ * Focused tests for `withoutDeleted.mapDelta` covering the four transition
+ * cases of an entity's hidden-state across a delta:
+ *
+ *   F→N : was-fine, still-fine          (no transition)
+ *   F→D : was-fine, becomes hidden      (newly deleted)
+ *   W→N : was-hidden, becomes visible   (newly restored / un-deleted)
+ *   W→D : was-hidden, still hidden      (idempotent re-deletion)
+ *
+ * The bug being guarded against: pre-fix, `mapDelta` filtered `delta.added` /
+ * `delta.removed` against the post-mutation `isDeleted(en)` predicate. That
+ * misclassifies entities whose hidden-state transitioned during the delta —
+ * causing W→N to crash MappedThread (stale `vl:true` log slips into `removed`
+ * but was never in result) and F→D-with-content-removal to silently keep
+ * stale content in result.
+ */
+import { afterEach, 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, withoutDeleted } from './basic.ts'
+import type { ArrayEvent } from './subscribable.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: ThreadInMemory
+let events: ArrayEvent<Applog>[]
+let unsub: () => void
+
+function recordEvents(thread: { subscribe: (cb: (e: ArrayEvent<Applog>) => void) => () => void }) {
+	events = []
+	unsub = thread.subscribe(event => events.push(event))
+}
+
+beforeEach(() => {
+	tsCounter = 0
+	const seed: ApplogForInsert[] = [
+		{ en: 'e1', at: 'movie/title', vl: 'Predator', ag: 'testAgent' },
+		{ en: 'e1', at: 'movie/year', vl: 1987, ag: 'testAgent' },
+		{ en: 'e2', at: 'movie/title', vl: 'Lethal Weapon', ag: 'testAgent' },
+		{ en: 'e2', at: 'movie/year', vl: 1987, ag: 'testAgent' },
+	]
+	db = ThreadInMemory.fromArray(makeApplogs(seed), 'test-withoutDeleted')
+})
+
+afterEach(() => {
+	unsub?.()
+})
+
+describe('withoutDeleted.mapDelta — transition truth table', () => {
+	it('F→N: ordinary content add/remove passes through unchanged', () => {
+		const filtered = withoutDeleted(lastWriteWins(db))
+		recordEvents(filtered)
+
+		// Sanity: e1 is visible at start
+		expect(filtered.applogs.some(l => l.en === 'e1' && l.at === 'movie/title')).toBe(true)
+
+		// Add new content — should pass through (entity stays visible)
+		db.insert([{ en: 'e1', at: 'movie/cast', vl: 'p1', ag: 'testAgent' }])
+
+		const lastEvent = events[events.length - 1] as { added: readonly Applog[]; removed: readonly Applog[] | null }
+		expect(lastEvent.added.length).toBe(1)
+		expect(lastEvent.added[0]).toMatchObject({ en: 'e1', at: 'movie/cast', vl: 'p1' })
+		expect(lastEvent.removed ?? []).toEqual([])
+
+		// Result still contains e1 + the new cast log
+		expect(filtered.applogs.some(l => l.en === 'e1' && l.at === 'movie/cast')).toBe(true)
+	})
+
+	it('F→D: insertion of isDeleted=true emits all entity applogs as removed', () => {
+		const filtered = withoutDeleted(lastWriteWins(db))
+		recordEvents(filtered)
+
+		const e1ApplogsBefore = filtered.applogs.filter(l => l.en === 'e1')
+		expect(e1ApplogsBefore.length).toBeGreaterThan(0)
+
+		db.insert([{ en: 'e1', at: 'isDeleted', vl: true, ag: 'testAgent' }])
+
+		const removedAcrossEvents = events.flatMap(e =>
+			'removed' in e ? (e.removed ?? []) : [],
+		)
+		const removedEns = new Set(removedAcrossEvents.map(l => l.en))
+		expect(removedEns).toEqual(new Set(['e1']))
+		// All e1 applogs that were in result should be removed
+		expect(removedAcrossEvents.length).toBe(e1ApplogsBefore.length)
+
+		// The isDeleted=true log itself must NOT appear in `added` (entity is now hidden)
+		const addedAcrossEvents = events.flatMap(e =>
+			'added' in e ? (e.added ?? []) : [],
+		)
+		expect(addedAcrossEvents.some(l => l.en === 'e1' && l.at === 'isDeleted')).toBe(false)
+
+		// e1 fully gone from result
+		expect(filtered.applogs.some(l => l.en === 'e1')).toBe(false)
+	})
+
+	it('W→N: un-deletion via LWW supersession re-adds entity applogs without crashing or duplicating', () => {
+		const filtered = withoutDeleted(lastWriteWins(db))
+
+		// Hide e1
+		db.insert([{ en: 'e1', at: 'isDeleted', vl: true, ag: 'testAgent' }])
+		expect(filtered.applogs.filter(l => l.en === 'e1').length).toBe(0)
+
+		// Now subscribe — only un-deletion events should arrive
+		recordEvents(filtered)
+
+		// LWW supersession: appending vl:false makes the vl:true log non-current,
+		// so withoutDeleted's mapper sees `delta.added=[{vl:false}]` and
+		// `delta.removed=[{vl:true}]`. With the bug, the stale {vl:true} would
+		// slip into our `removed` output and MappedThread.onParentUpdate would
+		// throw "log not found" when trying to splice it from _applogs.
+		expect(() => {
+			db.insert([{ en: 'e1', at: 'isDeleted', vl: false, ag: 'testAgent' }])
+		}).not.toThrow()
+
+		// The stale {vl:true} log must NOT appear in any `removed` — it was never in result.
+		const removedAcrossEvents = events.flatMap(e =>
+			'removed' in e ? (e.removed ?? []) : [],
+		)
+		expect(
+			removedAcrossEvents.some(l => l.en === 'e1' && l.at === 'isDeleted' && l.vl === true),
+		).toBe(false)
+
+		// All e1 applogs should be re-added (synthetic additions). No duplicates.
+		const addedAcrossEvents = events.flatMap(e =>
+			'added' in e ? (e.added ?? []) : [],
+		)
+		const addedE1 = addedAcrossEvents.filter(l => l.en === 'e1')
+		expect(addedE1.length).toBeGreaterThan(0)
+
+		// No duplicate cids in additions
+		const cids = addedE1.map(l => l.cid)
+		expect(new Set(cids).size).toBe(cids.length)
+
+		// Result contains e1 again, and original content is back
+		expect(filtered.applogs.some(l => l.en === 'e1' && l.at === 'movie/title' && l.vl === 'Predator')).toBe(true)
+	})
+
+	it('W→D: re-deleting an already-hidden entity (multi-attr) is idempotent — no events about that entity', () => {
+		const filtered = withoutDeleted(db)
+
+		// First mark e1 hidden via 'isDeleted'
+		db.insert([{ en: 'e1', at: 'isDeleted', vl: true, ag: 'testAgent' }])
+		expect(filtered.applogs.some(l => l.en === 'e1')).toBe(false)
+
+		// Now subscribe and add a SECOND deletion-class marker (block/isDeleted).
+		// Entity stays hidden; pass-through filter should exclude the marker.
+		recordEvents(filtered)
+		db.insert([{ en: 'e1', at: 'block/isDeleted', vl: true, ag: 'testAgent' }])
+
+		const addedAcrossEvents = events.flatMap(e => ('added' in e ? (e.added ?? []) : []))
+		const removedAcrossEvents = events.flatMap(e => ('removed' in e ? (e.removed ?? []) : []))
+
+		// The new isDeleted-class marker must NOT pass through to result (entity still hidden)
+		expect(addedAcrossEvents.some(l => l.en === 'e1' && l.at === 'block/isDeleted')).toBe(false)
+		// And nothing should be removed for e1 — it wasn't in result to begin with
+		expect(removedAcrossEvents.some(l => l.en === 'e1')).toBe(false)
+
+		// Result still has no e1 applogs
+		expect(filtered.applogs.some(l => l.en === 'e1')).toBe(false)
+	})
+
+	it('F→D + same-tick content removal: the removed content log appears in output exactly once', () => {
+		// This guards the silent-drift bug where post-mutation filter excluded
+		// legitimate `delta.removed` content for entities that just became hidden.
+		// We exercise it by going through LWW: a content update supersedes the
+		// previous content log, and in the SAME tick we delete the entity.
+		// The downstream withoutDeleted sees `delta.removed=[oldContent]` and
+		// `delta.added=[newContent, isDeleted=true]` — the old content log must
+		// be reported as removed exactly once.
+		const filtered = withoutDeleted(lastWriteWins(db))
+		recordEvents(filtered)
+
+		const oldTitle = filtered.applogs.find(l => l.en === 'e1' && l.at === 'movie/title')
+		expect(oldTitle).toBeDefined()
+
+		db.insert([
+			{ en: 'e1', at: 'movie/title', vl: 'Predator (rev)', ag: 'testAgent' },
+			{ en: 'e1', at: 'isDeleted', vl: true, ag: 'testAgent' },
+		])
+
+		const removedAcrossEvents = events.flatMap(e =>
+			'removed' in e ? (e.removed ?? []) : [],
+		)
+		const oldTitleOccurrences = removedAcrossEvents.filter(l => l.cid === oldTitle!.cid)
+		expect(oldTitleOccurrences.length).toBe(1)
+
+		// e1 is hidden now
+		expect(filtered.applogs.some(l => l.en === 'e1')).toBe(false)
+	})
+})

package/src/query.ts

@@ -0,0 +1,9 @@
+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'
+export * from './query/attr-helpers.ts'
+export * from './query/entity-collection.ts'

package/src/retrieve/index.ts

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