@optimystic/db-core 0.21.0 → 0.24.0

package/src/transform/atomic-proxy.ts

@@ -1,92 +1,92 @@
-import { Atomic } from './atomic.js';
-import type { IBlock, BlockId, BlockStore, BlockType, BlockHeader, BlockOperation, ReadPurpose } from '../index.js';
-
-/**
- * Opaque handle to an in-flight atomic scope.
- *
- * A method that opens a scope (via {@link AtomicProxy.atomic}) receives the scope as its
- * callback argument. To make a *nested* call reuse the enclosing scope — rather than open
- * (and separately commit) a second one — pass that handle back as the `parent` argument of
- * the nested `atomic()` call. This is how genuine nesting is distinguished from a second,
- * unrelated concurrent scope, portably (no `AsyncLocalStorage`, which is Node-only).
- */
-export interface AtomicScope { readonly __atomicScope: unique symbol; }
-
-/**
- * A BlockStore proxy that enables scoped atomic operations.
- * Operations normally delegate directly to the underlying store,
- * but during an `atomic()` call, they route through an Atomic tracker
- * that commits all-or-nothing on success, or rolls back on error.
- *
- * Both the BTree and its trunk should share the same AtomicProxy instance
- * so that all mutations (including root pointer updates) are part of the
- * same atomic batch.
- *
- * Concurrency model: top-level `atomic()` calls are *serialized* through a promise queue,
- * so a second, un-awaited scope started while the first is still in flight waits for the
- * first to commit/roll back before opening its own tracker — it never shares the first's
- * tracker. A genuinely nested call (one that hands back its enclosing scope) bypasses the
- * queue and reuses that scope, so it neither deadlocks on itself nor double-commits.
- */
-export class AtomicProxy<T extends IBlock> implements BlockStore<T> {
-	private _base: BlockStore<T>;
-	private _active: BlockStore<T>;
-	/** Tail of the serialization queue; each new top-level scope awaits the prior one. */
-	private _tail: Promise<void> = Promise.resolve();
-	/** The scope currently executing, or undefined between scopes. Serialization guarantees
-	 *  at most one is active at a time, so identity against `parent` cleanly separates a
-	 *  nested call (parent === current) from a foreign concurrent one (parent absent/stale). */
-	private _current?: AtomicScope;
-
-	constructor(store: BlockStore<T>) {
-		this._base = store;
-		this._active = store;
-	}
-
-	async tryGet(id: BlockId, purpose?: ReadPurpose): Promise<T | undefined> { return this._active.tryGet(id, purpose); }
-	/** Forward a leaf-value upgrade to the active store (duck-typed; the Tracker/CacheSource chain
-	 *  implements it). Keeps navigation-read filtering working for a B-tree bound to this proxy. */
-	markReadValue(id: BlockId): void { (this._active as { markReadValue?: (id: BlockId) => void }).markReadValue?.(id); }
-	insert(block: T): void { this._active.insert(block); }
-	update(blockId: BlockId, op: BlockOperation): void { this._active.update(blockId, op); }
-	delete(blockId: BlockId): void { this._active.delete(blockId); }
-	generateId(): BlockId { return this._active.generateId(); }
-	createBlockHeader(type: BlockType, newId?: BlockId): BlockHeader { return this._active.createBlockHeader(type, newId); }
-
-	/** Execute fn within an atomic scope. All store mutations are collected and committed on
-	 *  success, or discarded on error. `fn` receives a scope handle; pass it as the `parent`
-	 *  of any nested `atomic()` call that should join this scope instead of opening its own.
-	 *  Re-entrant safe (nesting reuses the parent scope) and concurrency safe (unrelated
-	 *  overlapping scopes serialize rather than sharing a tracker). */
-	async atomic<R>(fn: (scope: AtomicScope) => Promise<R>, parent?: AtomicScope): Promise<R> {
-		// Genuine nesting: the caller handed back the scope it is already inside. Reuse it —
-		// no second tracker, no second commit — and skip the queue, since waiting on the very
-		// scope we are running inside would deadlock.
-		if (parent !== undefined && parent === this._current) {
-			return fn(parent);
-		}
-		// Top-level scope (first, or a foreign call that overlapped one in flight): take a
-		// place in the serialization queue so it runs against its own tracker only after the
-		// prior scope has committed/rolled back.
-		const prior = this._tail;
-		let release!: () => void;
-		this._tail = new Promise<void>(resolve => { release = resolve; });
-		await prior;
-		const atomic = new Atomic<T>(this._base);
-		const scope = atomic as unknown as AtomicScope;
-		this._current = scope;
-		this._active = atomic;
-		try {
-			const result = await fn(scope);
-			atomic.commit();
-			return result;
-		} catch (e) {
-			atomic.reset();
-			throw e;
-		} finally {
-			this._active = this._base;
-			this._current = undefined;
-			release();
-		}
-	}
-}
+import { Atomic } from './atomic.js';
+import type { IBlock, BlockId, BlockStore, BlockType, BlockHeader, BlockOperation, ReadPurpose } from '../index.js';
+
+/**
+ * Opaque handle to an in-flight atomic scope.
+ *
+ * A method that opens a scope (via {@link AtomicProxy.atomic}) receives the scope as its
+ * callback argument. To make a *nested* call reuse the enclosing scope — rather than open
+ * (and separately commit) a second one — pass that handle back as the `parent` argument of
+ * the nested `atomic()` call. This is how genuine nesting is distinguished from a second,
+ * unrelated concurrent scope, portably (no `AsyncLocalStorage`, which is Node-only).
+ */
+export interface AtomicScope { readonly __atomicScope: unique symbol; }
+
+/**
+ * A BlockStore proxy that enables scoped atomic operations.
+ * Operations normally delegate directly to the underlying store,
+ * but during an `atomic()` call, they route through an Atomic tracker
+ * that commits all-or-nothing on success, or rolls back on error.
+ *
+ * Both the BTree and its trunk should share the same AtomicProxy instance
+ * so that all mutations (including root pointer updates) are part of the
+ * same atomic batch.
+ *
+ * Concurrency model: top-level `atomic()` calls are *serialized* through a promise queue,
+ * so a second, un-awaited scope started while the first is still in flight waits for the
+ * first to commit/roll back before opening its own tracker — it never shares the first's
+ * tracker. A genuinely nested call (one that hands back its enclosing scope) bypasses the
+ * queue and reuses that scope, so it neither deadlocks on itself nor double-commits.
+ */
+export class AtomicProxy<T extends IBlock> implements BlockStore<T> {
+	private _base: BlockStore<T>;
+	private _active: BlockStore<T>;
+	/** Tail of the serialization queue; each new top-level scope awaits the prior one. */
+	private _tail: Promise<void> = Promise.resolve();
+	/** The scope currently executing, or undefined between scopes. Serialization guarantees
+	 *  at most one is active at a time, so identity against `parent` cleanly separates a
+	 *  nested call (parent === current) from a foreign concurrent one (parent absent/stale). */
+	private _current?: AtomicScope;
+
+	constructor(store: BlockStore<T>) {
+		this._base = store;
+		this._active = store;
+	}
+
+	async tryGet(id: BlockId, purpose?: ReadPurpose): Promise<T | undefined> { return this._active.tryGet(id, purpose); }
+	/** Forward a leaf-value upgrade to the active store (duck-typed; the Tracker/CacheSource chain
+	 *  implements it). Keeps navigation-read filtering working for a B-tree bound to this proxy. */
+	markReadValue(id: BlockId): void { (this._active as { markReadValue?: (id: BlockId) => void }).markReadValue?.(id); }
+	insert(block: T): void { this._active.insert(block); }
+	update(blockId: BlockId, op: BlockOperation): void { this._active.update(blockId, op); }
+	delete(blockId: BlockId): void { this._active.delete(blockId); }
+	generateId(): BlockId { return this._active.generateId(); }
+	createBlockHeader(type: BlockType, newId?: BlockId): BlockHeader { return this._active.createBlockHeader(type, newId); }
+
+	/** Execute fn within an atomic scope. All store mutations are collected and committed on
+	 *  success, or discarded on error. `fn` receives a scope handle; pass it as the `parent`
+	 *  of any nested `atomic()` call that should join this scope instead of opening its own.
+	 *  Re-entrant safe (nesting reuses the parent scope) and concurrency safe (unrelated
+	 *  overlapping scopes serialize rather than sharing a tracker). */
+	async atomic<R>(fn: (scope: AtomicScope) => Promise<R>, parent?: AtomicScope): Promise<R> {
+		// Genuine nesting: the caller handed back the scope it is already inside. Reuse it —
+		// no second tracker, no second commit — and skip the queue, since waiting on the very
+		// scope we are running inside would deadlock.
+		if (parent !== undefined && parent === this._current) {
+			return fn(parent);
+		}
+		// Top-level scope (first, or a foreign call that overlapped one in flight): take a
+		// place in the serialization queue so it runs against its own tracker only after the
+		// prior scope has committed/rolled back.
+		const prior = this._tail;
+		let release!: () => void;
+		this._tail = new Promise<void>(resolve => { release = resolve; });
+		await prior;
+		const atomic = new Atomic<T>(this._base);
+		const scope = atomic as unknown as AtomicScope;
+		this._current = scope;
+		this._active = atomic;
+		try {
+			const result = await fn(scope);
+			atomic.commit();
+			return result;
+		} catch (e) {
+			atomic.reset();
+			throw e;
+		} finally {
+			this._active = this._base;
+			this._current = undefined;
+			release();
+		}
+	}
+}

package/src/transform/cache-source.ts

@@ -1,5 +1,5 @@
 import type { IBlock, BlockHeader, BlockId, BlockSource, BlockType, ReadPurpose, Transforms } from "../index.js";
-import { applyOperation } from "../index.js";
+import { applyOperation } from "./helpers.js";
 import { LruMap } from "../utility/lru-map.js";
 import { createLogger } from "../logger.js";
 import type { ReadDependencyCollector } from "../transaction/read-dependency-collector.js";

package/src/transform/helpers.ts

@@ -1,158 +1,159 @@
-import type { BlockId, BlockOperation, BlockOperations, BlockStore, IBlock, Transform, Transforms } from "../index.js";
-
-/**
- * Mutates the given block with a copy of the given operation.
- *
- * @warning **MUTATES IN PLACE** - Callers must clone the block first if the original needs preservation.
- * Storage implementations must clone on get/save to prevent cross-revision contamination.
- * @see docs/internals.md for mutation contracts
- */
-export function applyOperation(block: IBlock, [entity, index, deleteCount, inserted]: BlockOperation) {
-	if (Array.isArray(inserted)) {
-		(block as unknown as any)[entity].splice(index, deleteCount, ...structuredClone(inserted));
-	} else {
-		(block as unknown as any)[entity] = structuredClone(inserted);
-	}
-}
-
-/**
- * Mutates the given block with the given set of operations.
- *
- * @warning **MUTATES IN PLACE** - Callers must clone the block first if the original needs preservation.
- * @see docs/internals.md for mutation contracts
- */
-export function applyOperations(block: IBlock, operations: BlockOperations) {
-	for (const op of operations) {
-		applyOperation(block, op);
-	}
-}
-
-/** Returns a copy of the block with the given operation applied */
-export function withOperation(block: IBlock, [entity, index, deleteCount, inserted]: BlockOperation) {
-	if (Array.isArray(inserted)) {
-		const source = (block as any)[entity];
-		return { ...block, [entity]: [...source.slice(0, index), ...structuredClone(inserted), ...source.slice(index + deleteCount)] };
-	} else {
-		return { ...block, [entity]: structuredClone(inserted) };
-	}
-}
-
-/** The set of distinct block ids affected by the transform */
-export function blockIdsForTransforms(transforms: Transforms | undefined) {
-	if (!transforms) return [];
-	const insertIds = Object.keys(transforms.inserts ?? {});
-	const updateIds = Object.keys(transforms.updates ?? {});
-	const deleteIds = transforms.deletes ?? [];
-	return [...new Set([...insertIds, ...updateIds, ...deleteIds])];
-}
-
-/** Returns an empty transform */
-export function emptyTransforms(): Transforms {
-	return { inserts: {}, updates: {}, deletes: [] };
-}
-
-/**
- * Creates a deep copy of a Transforms object.
- *
- * @pitfall Both `inserts` and `updates` MUST be deep cloned. A shallow copy like
- * `{ ...transform.updates }` or `{ ...transform.inserts }` shares references, causing
- * mutations in one consumer to affect others. Specifically, `Tracker.update` mutates
- * inserted block objects in place via `applyOperation`, so a shallow-cloned snapshot
- * tracker will leak ops back into the original `Transforms.inserts`.
- * @see docs/internals.md "Shallow Copy of Transforms" pitfall
- */
-export function copyTransforms(transform: Transforms): Transforms {
-	const inserts = transform.inserts
-		? Object.fromEntries(Object.entries(transform.inserts).map(([k, v]) => [k, structuredClone(v)]))
-		: {};
-	const updates = transform.updates
-		? Object.fromEntries(Object.entries(transform.updates).map(([k, v]) => [k, structuredClone(v)]))
-		: undefined;
-	return { inserts, updates, deletes: transform.deletes ? [...transform.deletes] : undefined };
-}
-
-export function mergeTransforms(a: Transforms, b: Transforms): Transforms {
-	// updates: for a block id present in both sides, concatenate a's ops then b's ops
-	// (order-preserving) rather than letting b's array replace a's. inserts stay last-wins.
-	const updates: { [blockId: BlockId]: BlockOperation[] } = { ...a.updates };
-	for (const [id, ops] of Object.entries(b.updates ?? {})) {
-		updates[id] = updates[id] ? [...updates[id], ...ops] : ops;
-	}
-	return {
-		inserts: { ...a.inserts, ...b.inserts },
-		updates,
-		deletes: [...new Set([...(a.deletes ?? []), ...(b.deletes ?? [])])]
-	};
-}
-
-export function isTransformsEmpty(transform: Transforms): boolean {
-	return Object.keys(transform.inserts ?? {}).length === 0
-		&& Object.keys(transform.updates ?? {}).length === 0
-		&& (transform.deletes?.length ?? 0) === 0;
-}
-
-export function concatTransforms(...transforms: Transforms[]): Transforms {
-	return transforms.reduce((acc, m) => mergeTransforms(acc, m), emptyTransforms());
-}
-
-
-/**
- * Extracts the transform for a specific block from a Transforms object.
- *
- * @pitfall Updates array MUST be deep cloned - extracting without cloning shares
- * the array reference, causing mutations to affect the original Transforms.
- * @see docs/internals.md "Shallow Copy of Transforms" pitfall
- */
-export function transformForBlockId(transform: Transforms, blockId: BlockId): Transform {
-	return {
-		...(transform.inserts && blockId in transform.inserts ? { insert: transform.inserts[blockId] } : {}),
-		// Clone updates array to prevent shared references
-		...(transform.updates && blockId in transform.updates ? { updates: structuredClone(transform.updates[blockId]) } : {}),
-		...(transform.deletes?.includes(blockId) ? { delete: true } : {})
-	};
-}
-
-export function transformsFromTransform(transform: Transform, blockId: BlockId): Transforms {
-	return {
-		inserts: transform.insert ? { [blockId]: transform.insert } : {},
-		updates: transform.updates ? { [blockId]: transform.updates } : {},
-		deletes: transform.delete ? [blockId] : []
-	};
-}
-
-export function applyTransformToStore<T extends IBlock>(transform: Transforms, store: BlockStore<T>) {
-	for (const blockId of transform.deletes ?? []) {
-		store.delete(blockId);
-	}
-	for (const [, block] of Object.entries(transform.inserts ?? {})) {
-		store.insert(block as T);
-	}
-	for (const [blockId, operations] of Object.entries(transform.updates ?? {})) {
-		for (const op of operations) {
-			store.update(blockId, op);
-		}
-	}
-}
-
-/** Applies a transform to the given block */
-export function applyTransform(block: IBlock | undefined, transform: Transform): IBlock | undefined {
-	if (transform.insert) {
-		block = transform.insert;
-	}
-	if (block && transform.updates) {
-		applyOperations(block, transform.updates);
-	}
-	if (transform.delete) {
-		return undefined;
-	}
-	return block;
-}
-
-/** Concatenates a transform to the given transforms */
-export function concatTransform(transforms: Transforms, blockId: BlockId, transform: Transform): Transforms {
-	return {
-		inserts: { ...transforms.inserts, ...(transform.insert ? { [blockId]: transform.insert } : {}) },
-		updates: { ...transforms.updates, ...(transform.updates ? { [blockId]: transform.updates } : {}) },
-		deletes: [...(transforms.deletes ?? []), ...(transform.delete ? [blockId] : [])]
-	};
-}
+import type { BlockId, BlockOperation, BlockOperations, BlockStore, IBlock, Transform, Transforms } from "../index.js";
+
+/**
+ * Mutates the given block with a copy of the given operation.
+ *
+ * @warning **MUTATES IN PLACE** - Callers must clone the block first if the original needs preservation.
+ * Storage implementations must clone on get/save to prevent cross-revision contamination.
+ * @see docs/internals.md for mutation contracts
+ */
+export function applyOperation(block: IBlock, [entity, index, deleteCount, inserted]: BlockOperation) {
+	if (Array.isArray(inserted)) {
+		(block as unknown as any)[entity].splice(index, deleteCount, ...structuredClone(inserted));
+	} else {
+		(block as unknown as any)[entity] = structuredClone(inserted);
+	}
+}
+
+/**
+ * Mutates the given block with the given set of operations.
+ *
+ * @warning **MUTATES IN PLACE** - Callers must clone the block first if the original needs preservation.
+ * @see docs/internals.md for mutation contracts
+ */
+export function applyOperations(block: IBlock, operations: BlockOperations) {
+	for (const op of operations) {
+		applyOperation(block, op);
+	}
+}
+
+/** Returns a copy of the block with the given operation applied */
+export function withOperation(block: IBlock, [entity, index, deleteCount, inserted]: BlockOperation) {
+	if (Array.isArray(inserted)) {
+		const source = (block as any)[entity];
+		return { ...block, [entity]: [...source.slice(0, index), ...structuredClone(inserted), ...source.slice(index + deleteCount)] };
+	} else {
+		return { ...block, [entity]: structuredClone(inserted) };
+	}
+}
+
+/** The set of distinct block ids affected by the transform */
+export function blockIdsForTransforms(transforms: Transforms | undefined) {
+	if (!transforms) return [];
+	const insertIds = Object.keys(transforms.inserts ?? {});
+	const updateIds = Object.keys(transforms.updates ?? {});
+	const deleteIds = transforms.deletes ?? [];
+	return [...new Set([...insertIds, ...updateIds, ...deleteIds])];
+}
+
+/** Returns an empty transform */
+export function emptyTransforms(): Transforms {
+	return { inserts: {}, updates: {}, deletes: [] };
+}
+
+/**
+ * Creates a deep copy of a Transforms object.
+ *
+ * @pitfall Both `inserts` and `updates` MUST be deep cloned. A shallow copy like
+ * `{ ...transform.updates }` or `{ ...transform.inserts }` shares references, causing
+ * mutations in one consumer to affect others. Specifically, `Tracker.update` mutates
+ * inserted block objects in place via `applyOperation`, so a shallow-cloned snapshot
+ * tracker will leak ops back into the original `Transforms.inserts`.
+ * @see docs/internals.md "Shallow Copy of Transforms" pitfall
+ */
+export function copyTransforms(transform: Transforms): Transforms {
+	const inserts = transform.inserts
+		? Object.fromEntries(Object.entries(transform.inserts).map(([k, v]) => [k, structuredClone(v)]))
+		: {};
+	const updates = transform.updates
+		? Object.fromEntries(Object.entries(transform.updates).map(([k, v]) => [k, structuredClone(v)]))
+		: undefined;
+	return { inserts, updates, deletes: transform.deletes ? [...transform.deletes] : undefined };
+}
+
+export function mergeTransforms(a: Transforms, b: Transforms): Transforms {
+	// updates: for a block id present in both sides, concatenate a's ops then b's ops
+	// (order-preserving) rather than letting b's array replace a's. inserts stay last-wins.
+	const updates: { [blockId: BlockId]: BlockOperation[] } = { ...a.updates };
+	for (const [id, ops] of Object.entries(b.updates ?? {})) {
+		updates[id] = updates[id] ? [...updates[id], ...ops] : ops;
+	}
+	return {
+		inserts: { ...a.inserts, ...b.inserts },
+		updates,
+		deletes: [...new Set([...(a.deletes ?? []), ...(b.deletes ?? [])])]
+	};
+}
+
+export function isTransformsEmpty(transform: Transforms): boolean {
+	return Object.keys(transform.inserts ?? {}).length === 0
+		&& Object.keys(transform.updates ?? {}).length === 0
+		&& (transform.deletes?.length ?? 0) === 0;
+}
+
+export function concatTransforms(...transforms: Transforms[]): Transforms {
+	return transforms.reduce((acc, m) => mergeTransforms(acc, m), emptyTransforms());
+}
+
+
+/**
+ * Extracts the transform for a specific block from a Transforms object.
+ *
+ * @pitfall Updates array MUST be deep cloned - extracting without cloning shares
+ * the array reference, causing mutations to affect the original Transforms.
+ * @see docs/internals.md "Shallow Copy of Transforms" pitfall
+ */
+export function transformForBlockId(transform: Transforms, blockId: BlockId): Transform {
+	return {
+		...(transform.inserts && blockId in transform.inserts ? { insert: transform.inserts[blockId] } : {}),
+		// Clone updates array to prevent shared references
+		...(transform.updates && blockId in transform.updates ? { updates: structuredClone(transform.updates[blockId]) } : {}),
+		...(transform.deletes?.includes(blockId) ? { delete: true } : {})
+	};
+}
+
+export function transformsFromTransform(transform: Transform, blockId: BlockId): Transforms {
+	return {
+		inserts: transform.insert ? { [blockId]: transform.insert } : {},
+		updates: transform.updates ? { [blockId]: transform.updates } : {},
+		deletes: transform.delete ? [blockId] : []
+	};
+}
+
+export function applyTransformToStore<T extends IBlock>(transform: Transforms, store: BlockStore<T>) {
+	for (const blockId of transform.deletes ?? []) {
+		store.delete(blockId);
+	}
+	for (const [, block] of Object.entries(transform.inserts ?? {})) {
+		store.insert(block as T);
+	}
+	for (const [blockId, operations] of Object.entries(transform.updates ?? {})) {
+		for (const op of operations) {
+			store.update(blockId, op);
+		}
+	}
+}
+
+/** Applies a transform to the given block */
+export function applyTransform(block: IBlock | undefined, transform: Transform): IBlock | undefined {
+	if (transform.insert) {
+		block = transform.insert;
+	}
+	if (block && transform.updates) {
+		applyOperations(block, transform.updates);
+	}
+	if (transform.delete) {
+		return undefined;
+	}
+	return block;
+}
+
+/**
+ * Concatenates a single block's transform onto the given transforms.
+ *
+ * Delegates to `mergeTransforms` so the two helpers cannot drift: updates for a shared
+ * block id concatenate (order-preserving), deletes dedupe, inserts stay last-wins.
+ */
+export function concatTransform(transforms: Transforms, blockId: BlockId, transform: Transform): Transforms {
+	return mergeTransforms(transforms, transformsFromTransform(transform, blockId));
+}

package/src/transform/tracker.ts

@@ -1,5 +1,6 @@
 import type { IBlock, BlockId, BlockStore as IBlockStore, BlockHeader, BlockOperation, BlockType, BlockSource as IBlockSource, ReadPurpose } from "../index.js";
-import { applyOperation, applyOperations, emptyTransforms, blockIdsForTransforms, ensured } from "../index.js";
+import { applyOperation, applyOperations, emptyTransforms, blockIdsForTransforms } from "./helpers.js";
+import { ensured } from "../utility/ensured.js";
 
 /** A block store that collects transformations, without applying them to the underlying source.
  * Transformations are also applied to the retrieved blocks, making it seem like the source has been modified.