@byearlybird/starling 0.8.1 → 0.9.0

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-import { a as StoreSnapshot, c as processDocument, i as Store, n as PluginHooks, o as createStore, r as PluginMethods, s as EncodedDocument, t as Plugin } from "./store-BGsRIZeM.js";
-export { type EncodedDocument, Plugin, PluginHooks, PluginMethods, Store, StoreSnapshot, createStore, processDocument };
+import { a as StoreAddOptions, i as Store, l as EncodedDocument, n as Query, o as StoreConfig, r as QueryConfig, s as StoreSetTransaction, t as Plugin, u as processDocument } from "./store-Dc-hIF56.js";
+export { type EncodedDocument, Plugin, Query, QueryConfig, Store, StoreAddOptions, StoreConfig, StoreSetTransaction, processDocument };

package/dist/index.js

@@ -1,11 +1,21 @@
-//#region src/eventstamp.ts
-const generateNonce = () => {
+//#region src/crdt/eventstamp.ts
+function generateNonce() {
 	return Math.random().toString(16).slice(2, 6).padStart(4, "0");
-};
-const encodeEventstamp = (timestampMs, counter, nonce) => {
+}
+function encodeEventstamp(timestampMs, counter, nonce) {
 	return `${new Date(timestampMs).toISOString()}|${counter.toString(16).padStart(4, "0")}|${nonce}`;
-};
-const decodeEventstamp = (eventstamp) => {
+}
+/**
+* Validates whether a string is a properly formatted eventstamp.
+* Expected format: YYYY-MM-DDTHH:mm:ss.SSSZ|HHHH+|HHHH
+* where HHHH+ represents 4 or more hex characters for the counter,
+* and HHHH represents exactly 4 hex characters for the nonce.
+*/
+function isValidEventstamp(stamp) {
+	return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z\|[0-9a-f]{4,}\|[0-9a-f]{4}$/.test(stamp);
+}
+function decodeEventstamp(eventstamp) {
+	if (!isValidEventstamp(eventstamp)) throw new Error(`Invalid eventstamp format: "${eventstamp}". Expected format: YYYY-MM-DDTHH:mm:ss.SSSZ|HHHH+|HHHH`);
 	const parts = eventstamp.split("|");
 	const isoString = parts[0];
 	const hexCounter = parts[1];
@@ -15,26 +25,36 @@ const decodeEventstamp = (eventstamp) => {
 		counter: parseInt(hexCounter, 16),
 		nonce
 	};
-};
+}
 const MIN_EVENTSTAMP = encodeEventstamp(0, 0, "0000");
 
 //#endregion
-//#region src/utils.ts
-const isObject = (value) => !!(value != null && typeof value === "object" && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype);
-const isEncodedValue = (value) => !!(typeof value === "object" && value !== null && "~value" in value && "~eventstamp" in value);
+//#region src/crdt/utils.ts
+function isObject(value) {
+	return !!(value != null && typeof value === "object" && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype);
+}
+function isEncodedValue(value) {
+	return !!(typeof value === "object" && value !== null && "~value" in value && "~eventstamp" in value);
+}
 
 //#endregion
-//#region src/value.ts
-const encodeValue = (value, eventstamp) => ({
-	"~value": value,
-	"~eventstamp": eventstamp
-});
-const decodeValue = (value) => value["~value"];
-const mergeValues = (into, from) => into["~eventstamp"] > from["~eventstamp"] ? [into, into["~eventstamp"]] : [from, from["~eventstamp"]];
+//#region src/crdt/value.ts
+function encodeValue(value, eventstamp) {
+	return {
+		"~value": value,
+		"~eventstamp": eventstamp
+	};
+}
+function decodeValue(value) {
+	return value["~value"];
+}
+function mergeValues(into, from) {
+	return into["~eventstamp"] > from["~eventstamp"] ? [into, into["~eventstamp"]] : [from, from["~eventstamp"]];
+}
 
 //#endregion
-//#region src/record.ts
-const processRecord = (source, process) => {
+//#region src/crdt/record.ts
+function processRecord(source, process) {
 	const result = {};
 	const step = (input, output) => {
 		for (const key in input) {
@@ -49,8 +69,8 @@ const processRecord = (source, process) => {
 	};
 	step(source, result);
 	return result;
-};
-const encodeRecord = (obj, eventstamp) => {
+}
+function encodeRecord(obj, eventstamp) {
 	const result = {};
 	const step = (input, output) => {
 		for (const key in input) {
@@ -64,8 +84,8 @@ const encodeRecord = (obj, eventstamp) => {
 	};
 	step(obj, result);
 	return result;
-};
-const decodeRecord = (obj) => {
+}
+function decodeRecord(obj) {
 	const result = {};
 	const step = (input, output) => {
 		for (const key in input) {
@@ -80,8 +100,8 @@ const decodeRecord = (obj) => {
 	};
 	step(obj, result);
 	return result;
-};
-const mergeRecords = (into, from) => {
+}
+function mergeRecords(into, from) {
 	const result = {};
 	let greatestEventstamp = MIN_EVENTSTAMP;
 	const step = (v1, v2, output) => {
@@ -116,21 +136,25 @@ const mergeRecords = (into, from) => {
 	};
 	step(into, from, result);
 	return [result, greatestEventstamp];
-};
+}
 
 //#endregion
-//#region src/document.ts
-const encodeDoc = (id, obj, eventstamp, deletedAt = null) => ({
-	"~id": id,
-	"~data": isObject(obj) ? encodeRecord(obj, eventstamp) : encodeValue(obj, eventstamp),
-	"~deletedAt": deletedAt
-});
-const decodeDoc = (doc) => ({
-	"~id": doc["~id"],
-	"~data": isEncodedValue(doc["~data"]) ? decodeValue(doc["~data"]) : decodeRecord(doc["~data"]),
-	"~deletedAt": doc["~deletedAt"]
-});
-const mergeDocs = (into, from) => {
+//#region src/crdt/document.ts
+function encodeDoc(id, obj, eventstamp, deletedAt = null) {
+	return {
+		"~id": id,
+		"~data": isObject(obj) ? encodeRecord(obj, eventstamp) : encodeValue(obj, eventstamp),
+		"~deletedAt": deletedAt
+	};
+}
+function decodeDoc(doc) {
+	return {
+		"~id": doc["~id"],
+		"~data": isEncodedValue(doc["~data"]) ? decodeValue(doc["~data"]) : decodeRecord(doc["~data"]),
+		"~deletedAt": doc["~deletedAt"]
+	};
+}
+function mergeDocs(into, from) {
 	const intoIsValue = isEncodedValue(into["~data"]);
 	const fromIsValue = isEncodedValue(from["~data"]);
 	if (intoIsValue !== fromIsValue) throw new Error("Merge error: Incompatible types");
@@ -143,277 +167,354 @@ const mergeDocs = (into, from) => {
 		"~data": mergedData,
 		"~deletedAt": mergedDeletedAt
 	}, greatestEventstamp];
-};
-const deleteDoc = (doc, eventstamp) => ({
-	"~id": doc["~id"],
-	"~data": doc["~data"],
-	"~deletedAt": eventstamp
-});
-const processDocument = (doc, process) => {
+}
+function deleteDoc(doc, eventstamp) {
+	return {
+		"~id": doc["~id"],
+		"~data": doc["~data"],
+		"~deletedAt": eventstamp
+	};
+}
+function processDocument(doc, process) {
 	const processedData = isEncodedValue(doc["~data"]) ? process(doc["~data"]) : processRecord(doc["~data"], process);
 	return {
 		"~id": doc["~id"],
 		"~data": processedData,
 		"~deletedAt": doc["~deletedAt"]
 	};
-};
+}
 
 //#endregion
-//#region src/clock.ts
-const createClock = () => {
-	let counter = 0;
-	let lastMs = Date.now();
-	let lastNonce = generateNonce();
-	return {
-		now: () => {
-			const wallMs = Date.now();
-			if (wallMs > lastMs) {
-				lastMs = wallMs;
-				counter = 0;
-				lastNonce = generateNonce();
-			} else {
-				counter++;
-				lastNonce = generateNonce();
-			}
-			return encodeEventstamp(lastMs, counter, lastNonce);
-		},
-		latest() {
-			return encodeEventstamp(lastMs, counter, lastNonce);
-		},
-		forward(eventstamp) {
-			if (eventstamp > this.latest()) {
-				const newer = decodeEventstamp(eventstamp);
-				lastMs = newer.timestampMs;
-				counter = newer.counter;
-				lastNonce = newer.nonce;
-			}
+//#region src/crdt/collection.ts
+/**
+* Merges two collections using field-level Last-Write-Wins semantics.
+*
+* The merge operation:
+* 1. Forwards the clock to the newest eventstamp from either collection
+* 2. Merges each document pair using field-level LWW (via mergeDocs)
+* 3. Tracks what changed for hook notifications (added/updated/deleted)
+*
+* Deletion is final: once a document is deleted, updates to it are merged into
+* the document's data but don't restore visibility. Only new documents or
+* transitions into the deleted state are tracked.
+*
+* @param into - The base collection to merge into
+* @param from - The source collection to merge from
+* @returns Merged collection and categorized changes
+*
+* @example
+* ```typescript
+* const into = {
+*   "~docs": [{ "~id": "doc1", "~data": {...}, "~deletedAt": null }],
+*   "~eventstamp": "2025-01-01T00:00:00.000Z|0001|a1b2"
+* };
+*
+* const from = {
+*   "~docs": [
+*     { "~id": "doc1", "~data": {...}, "~deletedAt": null }, // updated
+*     { "~id": "doc2", "~data": {...}, "~deletedAt": null }  // new
+*   ],
+*   "~eventstamp": "2025-01-01T00:05:00.000Z|0001|c3d4"
+* };
+*
+* const result = mergeCollections(into, from);
+* // result.collection.~eventstamp === "2025-01-01T00:05:00.000Z|0001|c3d4"
+* // result.changes.added has "doc2"
+* // result.changes.updated has "doc1"
+* ```
+*/
+function mergeCollections(into, from) {
+	const intoDocsById = /* @__PURE__ */ new Map();
+	for (const doc of into["~docs"]) intoDocsById.set(doc["~id"], doc);
+	const added = /* @__PURE__ */ new Map();
+	const updated = /* @__PURE__ */ new Map();
+	const deleted = /* @__PURE__ */ new Set();
+	const mergedDocsById = new Map(intoDocsById);
+	for (const fromDoc of from["~docs"]) {
+		const id = fromDoc["~id"];
+		const intoDoc = intoDocsById.get(id);
+		if (!intoDoc) {
+			mergedDocsById.set(id, fromDoc);
+			if (!fromDoc["~deletedAt"]) added.set(id, fromDoc);
+		} else {
+			if (intoDoc === fromDoc) continue;
+			const [mergedDoc] = mergeDocs(intoDoc, fromDoc);
+			mergedDocsById.set(id, mergedDoc);
+			const wasDeleted = intoDoc["~deletedAt"] !== null;
+			const isDeleted = mergedDoc["~deletedAt"] !== null;
+			if (!wasDeleted && isDeleted) deleted.add(id);
+			else if (!isDeleted) updated.set(id, mergedDoc);
 		}
-	};
-};
-
-//#endregion
-//#region src/kv.ts
-const createKV = (iterable) => {
-	let readMap = new Map(iterable);
+	}
+	const newestEventstamp = into["~eventstamp"] >= from["~eventstamp"] ? into["~eventstamp"] : from["~eventstamp"];
 	return {
-		get(key) {
-			return readMap.get(key) ?? null;
-		},
-		values() {
-			return readMap.values();
+		collection: {
+			"~docs": Array.from(mergedDocsById.values()),
+			"~eventstamp": newestEventstamp
 		},
-		entries() {
-			return readMap.entries();
-		},
-		get size() {
-			return readMap.size;
-		},
-		begin(callback) {
-			const staging = new Map(readMap);
-			let rolledBack = false;
-			callback({
-				get(key) {
-					return staging.get(key) ?? null;
-				},
-				set(key, value, opts) {
-					if (opts?.replace) {
-						staging.set(key, value);
-						return null;
-					} else {
-						const prev = staging.get(key);
-						if (prev) {
-							const [merged, eventstamp] = mergeDocs(prev, value);
-							staging.set(key, merged);
-							return eventstamp;
-						} else {
-							staging.set(key, value);
-							return null;
-						}
-					}
-				},
-				del(key, eventstamp) {
-					const prev = staging.get(key);
-					if (prev) staging.set(key, deleteDoc(prev, eventstamp));
-				},
-				rollback() {
-					rolledBack = true;
-				}
-			});
-			if (!rolledBack) readMap = staging;
+		changes: {
+			added,
+			updated,
+			deleted
 		}
 	};
-};
+}
 
 //#endregion
-//#region src/transaction.ts
+//#region src/clock.ts
 /**
-* Factory for creating a transaction object with all mutation methods.
-* Closes over arrays for tracking puts, patches, and deletes.
+* A Hybrid Logical Clock that generates monotonically increasing eventstamps.
+* Combines wall-clock time with a counter for handling clock stalls and a
+* random nonce for tie-breaking.
+*
+* The clock automatically increments the counter when the wall clock doesn't
+* advance, ensuring eventstamps are always unique and monotonic.
 */
-const createTransaction = (kvTx, clock, getId, encodeValue$1, decodeActive, putKeyValues, patchKeyValues, deleteKeys) => {
-	const state = { rolledBack: false };
-	const tx = {
-		rolledBack: false,
-		add(value, options) {
-			const key = options?.withId ?? getId();
-			kvTx.set(key, encodeValue$1(key, value), { replace: true });
-			putKeyValues.push([key, value]);
-			return key;
-		},
-		update(key, value) {
-			kvTx.set(key, encodeDoc(key, value, clock.now()));
-			const merged = decodeActive(kvTx.get(key));
-			if (merged) patchKeyValues.push([key, merged]);
-		},
-		merge(doc) {
-			if (kvTx.get(doc["~id"])) kvTx.set(doc["~id"], doc);
-			else kvTx.set(doc["~id"], doc, { replace: true });
-			const currentDoc = kvTx.get(doc["~id"]);
-			if (currentDoc) if (currentDoc["~deletedAt"]) deleteKeys.push(doc["~id"]);
-			else {
-				const merged = decodeDoc(currentDoc)["~data"];
-				patchKeyValues.push([doc["~id"], merged]);
-			}
-		},
-		del(key) {
-			if (!kvTx.get(key)) return;
-			kvTx.del(key, clock.now());
-			deleteKeys.push(key);
-		},
-		get(key) {
-			return decodeActive(kvTx.get(key));
-		},
-		rollback() {
-			state.rolledBack = true;
-			tx.rolledBack = true;
-			kvTx.rollback();
+var Clock = class {
+	#counter = 0;
+	#lastMs = Date.now();
+	#lastNonce = generateNonce();
+	/** Generates a new eventstamp, advancing the clock */
+	now() {
+		const wallMs = Date.now();
+		if (wallMs > this.#lastMs) {
+			this.#lastMs = wallMs;
+			this.#counter = 0;
+			this.#lastNonce = generateNonce();
+		} else {
+			this.#counter++;
+			this.#lastNonce = generateNonce();
 		}
-	};
-	return tx;
+		return encodeEventstamp(this.#lastMs, this.#counter, this.#lastNonce);
+	}
+	/** Returns the most recent eventstamp without advancing the clock */
+	latest() {
+		return encodeEventstamp(this.#lastMs, this.#counter, this.#lastNonce);
+	}
+	/** Fast-forwards the clock to match a newer remote eventstamp */
+	forward(eventstamp) {
+		if (eventstamp > this.latest()) {
+			const newer = decodeEventstamp(eventstamp);
+			this.#lastMs = newer.timestampMs;
+			this.#counter = newer.counter;
+			this.#lastNonce = newer.nonce;
+		}
+	}
 };
 
 //#endregion
 //#region src/store.ts
-const createStore = (config = {}) => {
-	const kv = createKV();
-	const clock = createClock();
-	const getId = config.getId ?? (() => crypto.randomUUID());
-	const encodeValue$1 = (key, value) => encodeDoc(key, value, clock.now());
-	const decodeActive = (doc) => {
+var Store = class {
+	#readMap = /* @__PURE__ */ new Map();
+	#clock = new Clock();
+	#getId;
+	#onInitHandlers = [];
+	#onDisposeHandlers = [];
+	#onAddHandlers = [];
+	#onUpdateHandlers = [];
+	#onDeleteHandlers = [];
+	#queries = /* @__PURE__ */ new Set();
+	constructor(config = {}) {
+		this.#getId = config.getId ?? (() => crypto.randomUUID());
+	}
+	get(key) {
+		return this.#decodeActive(this.#readMap.get(key) ?? null);
+	}
+	entries() {
+		const self = this;
+		function* iterator() {
+			for (const [key, doc] of self.#readMap.entries()) {
+				const data = self.#decodeActive(doc);
+				if (data !== null) yield [key, data];
+			}
+		}
+		return iterator();
+	}
+	collection() {
+		return {
+			"~docs": Array.from(this.#readMap.values()),
+			"~eventstamp": this.#clock.latest()
+		};
+	}
+	merge(collection) {
+		const result = mergeCollections(this.collection(), collection);
+		this.#clock.forward(result.collection["~eventstamp"]);
+		this.#readMap = new Map(result.collection["~docs"].map((doc) => [doc["~id"], doc]));
+		const addEntries = Array.from(result.changes.added.entries()).map(([key, doc]) => [key, decodeDoc(doc)["~data"]]);
+		const updateEntries = Array.from(result.changes.updated.entries()).map(([key, doc]) => [key, decodeDoc(doc)["~data"]]);
+		const deleteKeys = Array.from(result.changes.deleted);
+		if (addEntries.length > 0 || updateEntries.length > 0 || deleteKeys.length > 0) this.#emitMutations(addEntries, updateEntries, deleteKeys);
+	}
+	begin(callback, opts) {
+		const silent = opts?.silent ?? false;
+		const addEntries = [];
+		const updateEntries = [];
+		const deleteKeys = [];
+		const staging = new Map(this.#readMap);
+		let rolledBack = false;
+		const result = callback({
+			add: (value, options) => {
+				const key = options?.withId ?? this.#getId();
+				staging.set(key, this.#encodeValue(key, value));
+				addEntries.push([key, value]);
+				return key;
+			},
+			update: (key, value) => {
+				const doc = encodeDoc(key, value, this.#clock.now());
+				const prev = staging.get(key);
+				const mergedDoc = prev ? mergeDocs(prev, doc)[0] : doc;
+				staging.set(key, mergedDoc);
+				const merged = this.#decodeActive(mergedDoc);
+				if (merged !== null) updateEntries.push([key, merged]);
+			},
+			merge: (doc) => {
+				const existing = staging.get(doc["~id"]);
+				const mergedDoc = existing ? mergeDocs(existing, doc)[0] : doc;
+				staging.set(doc["~id"], mergedDoc);
+				const decoded = this.#decodeActive(mergedDoc);
+				const isNew = !this.#readMap.has(doc["~id"]);
+				if (mergedDoc["~deletedAt"]) deleteKeys.push(doc["~id"]);
+				else if (decoded !== null) if (isNew) addEntries.push([doc["~id"], decoded]);
+				else updateEntries.push([doc["~id"], decoded]);
+			},
+			del: (key) => {
+				const currentDoc = staging.get(key);
+				if (!currentDoc) return;
+				staging.set(key, deleteDoc(currentDoc, this.#clock.now()));
+				deleteKeys.push(key);
+			},
+			get: (key) => this.#decodeActive(staging.get(key) ?? null),
+			rollback: () => {
+				rolledBack = true;
+			}
+		});
+		if (!rolledBack) {
+			this.#readMap = staging;
+			if (!silent) this.#emitMutations(addEntries, updateEntries, deleteKeys);
+		}
+		return result;
+	}
+	add(value, options) {
+		return this.begin((tx) => tx.add(value, options));
+	}
+	update(key, value) {
+		this.begin((tx) => tx.update(key, value));
+	}
+	del(key) {
+		this.begin((tx) => tx.del(key));
+	}
+	use(plugin) {
+		this.#onInitHandlers.push(plugin.onInit);
+		this.#onDisposeHandlers.push(plugin.onDispose);
+		if (plugin.onAdd) this.#onAddHandlers.push(plugin.onAdd);
+		if (plugin.onUpdate) this.#onUpdateHandlers.push(plugin.onUpdate);
+		if (plugin.onDelete) this.#onDeleteHandlers.push(plugin.onDelete);
+		return this;
+	}
+	async init() {
+		for (const hook of this.#onInitHandlers) await hook(this);
+		for (const query of this.#queries) this.#hydrateQuery(query);
+		return this;
+	}
+	async dispose() {
+		for (let i = this.#onDisposeHandlers.length - 1; i >= 0; i--) await this.#onDisposeHandlers[i]?.();
+		for (const query of this.#queries) {
+			query.callbacks.clear();
+			query.results.clear();
+		}
+		this.#queries.clear();
+		this.#onInitHandlers = [];
+		this.#onDisposeHandlers = [];
+		this.#onAddHandlers = [];
+		this.#onUpdateHandlers = [];
+		this.#onDeleteHandlers = [];
+	}
+	query(config) {
+		const query = {
+			where: config.where,
+			select: config.select,
+			order: config.order,
+			results: /* @__PURE__ */ new Map(),
+			callbacks: /* @__PURE__ */ new Set()
+		};
+		this.#queries.add(query);
+		this.#hydrateQuery(query);
+		return {
+			results: () => {
+				if (query.order) return Array.from(query.results).sort(([, a], [, b]) => query.order(a, b));
+				return Array.from(query.results);
+			},
+			onChange: (callback) => {
+				query.callbacks.add(callback);
+				return () => {
+					query.callbacks.delete(callback);
+				};
+			},
+			dispose: () => {
+				this.#queries.delete(query);
+				query.callbacks.clear();
+				query.results.clear();
+			}
+		};
+	}
+	#encodeValue(key, value) {
+		return encodeDoc(key, value, this.#clock.now());
+	}
+	#decodeActive(doc) {
 		if (!doc || doc["~deletedAt"]) return null;
 		return decodeDoc(doc)["~data"];
-	};
-	const onInitHandlers = /* @__PURE__ */ new Set();
-	const onDisposeHandlers = /* @__PURE__ */ new Set();
-	const onAddHandlers = /* @__PURE__ */ new Set();
-	const onUpdateHandlers = /* @__PURE__ */ new Set();
-	const onDeleteHandlers = /* @__PURE__ */ new Set();
-	return {
-		get(key) {
-			return decodeActive(kv.get(key));
-		},
-		entries() {
-			function* iterator() {
-				for (const [key, doc] of kv.entries()) {
-					const data = decodeActive(doc);
-					if (data !== null) yield [key, data];
-				}
+	}
+	#emitMutations(addEntries, updateEntries, deleteKeys) {
+		this.#notifyQueries(addEntries, updateEntries, deleteKeys);
+		if (addEntries.length > 0) for (const handler of this.#onAddHandlers) handler(addEntries);
+		if (updateEntries.length > 0) for (const handler of this.#onUpdateHandlers) handler(updateEntries);
+		if (deleteKeys.length > 0) for (const handler of this.#onDeleteHandlers) handler(deleteKeys);
+	}
+	#notifyQueries(addEntries, updateEntries, deleteKeys) {
+		if (this.#queries.size === 0) return;
+		const dirtyQueries = /* @__PURE__ */ new Set();
+		if (addEntries.length > 0) {
+			for (const [key, value] of addEntries) for (const query of this.#queries) if (query.where(value)) {
+				const selected = this.#selectValue(query, value);
+				query.results.set(key, selected);
+				dirtyQueries.add(query);
 			}
-			return iterator();
-		},
-		snapshot() {
-			return {
-				docs: Array.from(kv.values()),
-				latestEventstamp: clock.latest()
-			};
-		},
-		merge(snapshot) {
-			clock.forward(snapshot.latestEventstamp);
-			this.begin((tx) => {
-				for (const doc of snapshot.docs) tx.merge(doc);
-			});
-		},
-		begin(callback, opts) {
-			const silent = opts?.silent ?? false;
-			const putKeyValues = [];
-			const patchKeyValues = [];
-			const deleteKeys = [];
-			let result;
-			let shouldNotify = false;
-			kv.begin((kvTx) => {
-				const tx = createTransaction(kvTx, clock, getId, encodeValue$1, decodeActive, putKeyValues, patchKeyValues, deleteKeys);
-				result = callback(tx);
-				if (!tx.rolledBack && !silent) shouldNotify = true;
-			});
-			if (shouldNotify) {
-				if (putKeyValues.length > 0) onAddHandlers.forEach((fn) => {
-					fn(putKeyValues);
-				});
-				if (patchKeyValues.length > 0) onUpdateHandlers.forEach((fn) => {
-					fn(patchKeyValues);
-				});
-				if (deleteKeys.length > 0) onDeleteHandlers.forEach((fn) => {
-					fn(deleteKeys);
-				});
-			}
-			return result;
-		},
-		add(value, options) {
-			return this.begin((tx) => tx.add(value, options));
-		},
-		update(key, value) {
-			return this.begin((tx) => tx.update(key, value));
-		},
-		del(key) {
-			return this.begin((tx) => tx.del(key));
-		},
-		use(plugin) {
-			const { hooks: pluginHooks, methods } = plugin;
-			if (pluginHooks.onAdd || pluginHooks.onUpdate || pluginHooks.onDelete) {
-				if (pluginHooks.onAdd) {
-					const onAdd = pluginHooks.onAdd;
-					onAddHandlers.add(onAdd);
-					onDisposeHandlers.add(() => {
-						onAddHandlers.delete(onAdd);
-					});
-				}
-				if (pluginHooks.onUpdate) {
-					const onUpdate = pluginHooks.onUpdate;
-					onUpdateHandlers.add(onUpdate);
-					onDisposeHandlers.add(() => {
-						onUpdateHandlers.delete(onUpdate);
-					});
-				}
-				if (pluginHooks.onDelete) {
-					const onDelete = pluginHooks.onDelete;
-					onDeleteHandlers.add(onDelete);
-					onDisposeHandlers.add(() => {
-						onDeleteHandlers.delete(onDelete);
-					});
-				}
+		}
+		if (updateEntries.length > 0) for (const [key, value] of updateEntries) for (const query of this.#queries) {
+			const matches = query.where(value);
+			const inResults = query.results.has(key);
+			if (matches && !inResults) {
+				const selected = this.#selectValue(query, value);
+				query.results.set(key, selected);
+				dirtyQueries.add(query);
+			} else if (!matches && inResults) {
+				query.results.delete(key);
+				dirtyQueries.add(query);
+			} else if (matches && inResults) {
+				const selected = this.#selectValue(query, value);
+				query.results.set(key, selected);
+				dirtyQueries.add(query);
 			}
-			if (methods) Object.assign(this, methods);
-			onInitHandlers.add(pluginHooks.onInit);
-			onDisposeHandlers.add(pluginHooks.onDispose);
-			return this;
-		},
-		async init() {
-			for (const fn of onInitHandlers) await fn(this);
-			return this;
-		},
-		async dispose() {
-			const disposerArray = Array.from(onDisposeHandlers);
-			disposerArray.reverse();
-			for (const fn of disposerArray) await fn();
-		},
-		latestEventstamp() {
-			return clock.latest();
-		},
-		forwardClock(eventstamp) {
-			clock.forward(eventstamp);
 		}
-	};
+		if (deleteKeys.length > 0) {
+			for (const key of deleteKeys) for (const query of this.#queries) if (query.results.delete(key)) dirtyQueries.add(query);
+		}
+		if (dirtyQueries.size > 0) this.#runQueryCallbacks(dirtyQueries);
+	}
+	#runQueryCallbacks(dirtyQueries) {
+		for (const query of dirtyQueries) for (const callback of query.callbacks) callback();
+	}
+	#hydrateQuery(query) {
+		query.results.clear();
+		for (const [key, value] of this.entries()) if (query.where(value)) {
+			const selected = this.#selectValue(query, value);
+			query.results.set(key, selected);
+		}
+	}
+	#selectValue(query, value) {
+		return query.select ? query.select(value) : value;
+	}
 };
 
 //#endregion
-export { createStore, processDocument };
+export { Store, processDocument };

package/dist/plugins/unstorage/plugin.d.ts

@@ -0,0 +1,17 @@
+import { c as Collection, t as Plugin } from "../../store-Dc-hIF56.js";
+import { Storage } from "unstorage";
+
+//#region src/plugins/unstorage/plugin.d.ts
+type MaybePromise<T> = T | Promise<T>;
+type UnstorageOnBeforeSet = (data: Collection) => MaybePromise<Collection>;
+type UnstorageOnAfterGet = (data: Collection) => MaybePromise<Collection>;
+type UnstorageConfig = {
+  debounceMs?: number;
+  pollIntervalMs?: number;
+  onBeforeSet?: UnstorageOnBeforeSet;
+  onAfterGet?: UnstorageOnAfterGet;
+  skip?: () => boolean;
+};
+declare function unstoragePlugin<T>(key: string, storage: Storage<Collection>, config?: UnstorageConfig): Plugin<T>;
+//#endregion
+export { type UnstorageConfig, unstoragePlugin };

package/dist/{plugin-unstorage.js → plugins/unstorage/plugin.js}

@@ -1,12 +1,12 @@
 //#region src/plugins/unstorage/plugin.ts
-const unstoragePlugin = (key, storage, config = {}) => {
+function unstoragePlugin(key, storage, config = {}) {
 	const { debounceMs = 0, pollIntervalMs, onBeforeSet, onAfterGet, skip } = config;
 	let debounceTimer = null;
 	let pollInterval = null;
 	let store = null;
 	const persistSnapshot = async () => {
 		if (!store) return;
-		const data = store.snapshot();
+		const data = store.collection();
 		const persisted = onBeforeSet !== void 0 ? await onBeforeSet(data) : data;
 		await storage.set(key, persisted);
 	};
@@ -31,7 +31,7 @@ const unstoragePlugin = (key, storage, config = {}) => {
 		const data = onAfterGet !== void 0 ? await onAfterGet(persisted) : persisted;
 		store.merge(data);
 	};
-	return { hooks: {
+	return {
 		onInit: async (s) => {
 			store = s;
 			await pollStorage();
@@ -59,8 +59,8 @@ const unstoragePlugin = (key, storage, config = {}) => {
 		onDelete: () => {
 			schedulePersist();
 		}
-	} };
-};
+	};
+}
 
 //#endregion
 export { unstoragePlugin };

package/dist/store-Dc-hIF56.d.ts

@@ -0,0 +1,114 @@
+//#region src/crdt/value.d.ts
+/**
+ * A primitive value wrapped with its eventstamp for Last-Write-Wins conflict resolution.
+ * Used as the leaf nodes in the CRDT data structure.
+ *
+ * @template T - The type of the wrapped value (primitive or complex type)
+ */
+type EncodedValue<T> = {
+  /** The actual value being stored */
+  "~value": T;
+  /** The eventstamp indicating when this value was last written (ISO|counter|nonce) */
+  "~eventstamp": string;
+};
+//#endregion
+//#region src/crdt/record.d.ts
+/**
+ * A nested object structure where each field is either an EncodedValue (leaf)
+ * or another EncodedRecord (nested object). This enables field-level
+ * Last-Write-Wins merging for complex data structures.
+ *
+ * Each field maintains its own eventstamp, allowing concurrent updates to
+ * different fields to be preserved during merge operations.
+ */
+type EncodedRecord = {
+  [key: string]: EncodedValue<unknown> | EncodedRecord;
+};
+//#endregion
+//#region src/crdt/document.d.ts
+/**
+ * Top-level document structure with system metadata for tracking identity,
+ * data, and deletion state. Documents are the primary unit of storage and
+ * synchronization in Starling.
+ *
+ * The tilde prefix (~) distinguishes system metadata from user-defined data.
+ */
+type EncodedDocument = {
+  /** Unique identifier for this document */
+  "~id": string;
+  /** The document's data, either a primitive value or nested object structure */
+  "~data": EncodedValue<unknown> | EncodedRecord;
+  /** Eventstamp when this document was soft-deleted, or null if not deleted */
+  "~deletedAt": string | null;
+};
+declare function processDocument(doc: EncodedDocument, process: (value: EncodedValue<unknown>) => EncodedValue<unknown>): EncodedDocument;
+//#endregion
+//#region src/crdt/collection.d.ts
+/**
+ * A collection represents the complete state of a store:
+ * - A set of documents (including soft-deleted ones)
+ * - The highest eventstamp observed across all operations
+ *
+ * Collections are the unit of synchronization between store replicas.
+ */
+type Collection = {
+  /** Array of encoded documents with eventstamps and metadata */
+  "~docs": EncodedDocument[];
+  /** Latest eventstamp observed by this collection for clock synchronization */
+  "~eventstamp": string;
+};
+//#endregion
+//#region src/store.d.ts
+type NotPromise<T> = T extends Promise<any> ? never : T;
+type DeepPartial<T> = T extends object ? { [P in keyof T]?: DeepPartial<T[P]> } : T;
+type StoreAddOptions = {
+  withId?: string;
+};
+type StoreConfig = {
+  getId?: () => string;
+};
+type StoreSetTransaction<T> = {
+  add: (value: T, options?: StoreAddOptions) => string;
+  update: (key: string, value: DeepPartial<T>) => void;
+  merge: (doc: EncodedDocument) => void;
+  del: (key: string) => void;
+  get: (key: string) => T | null;
+  rollback: () => void;
+};
+type Plugin<T> = {
+  onInit: (store: Store<T>) => Promise<void> | void;
+  onDispose: () => Promise<void> | void;
+  onAdd?: (entries: ReadonlyArray<readonly [string, T]>) => void;
+  onUpdate?: (entries: ReadonlyArray<readonly [string, T]>) => void;
+  onDelete?: (keys: ReadonlyArray<string>) => void;
+};
+type QueryConfig<T, U = T> = {
+  where: (data: T) => boolean;
+  select?: (data: T) => U;
+  order?: (a: U, b: U) => number;
+};
+type Query<U> = {
+  results: () => Array<readonly [string, U]>;
+  onChange: (callback: () => void) => () => void;
+  dispose: () => void;
+};
+declare class Store<T> {
+  #private;
+  constructor(config?: StoreConfig);
+  get(key: string): T | null;
+  entries(): IterableIterator<readonly [string, T]>;
+  collection(): Collection;
+  merge(collection: Collection): void;
+  begin<R = void>(callback: (tx: StoreSetTransaction<T>) => NotPromise<R>, opts?: {
+    silent?: boolean;
+  }): NotPromise<R>;
+  add(value: T, options?: StoreAddOptions): string;
+  update(key: string, value: DeepPartial<T>): void;
+  del(key: string): void;
+  use(plugin: Plugin<T>): this;
+  init(): Promise<this>;
+  dispose(): Promise<void>;
+  query<U = T>(config: QueryConfig<T, U>): Query<U>;
+}
+//#endregion
+export { StoreAddOptions as a, Collection as c, Store as i, EncodedDocument as l, Query as n, StoreConfig as o, QueryConfig as r, StoreSetTransaction as s, Plugin as t, processDocument as u };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@byearlybird/starling",
-	"version": "0.8.1",
+	"version": "0.9.0",
 	"type": "module",
 	"license": "MIT",
 	"main": "./dist/index.js",
@@ -11,15 +11,10 @@
 			"import": "./dist/index.js",
 			"default": "./dist/index.js"
 		},
-		"./plugin-query": {
-			"types": "./dist/plugin-query.d.ts",
-			"import": "./dist/plugin-query.js",
-			"default": "./dist/plugin-query.js"
-		},
 		"./plugin-unstorage": {
-			"types": "./dist/plugin-unstorage.d.ts",
-			"import": "./dist/plugin-unstorage.js",
-			"default": "./dist/plugin-unstorage.js"
+			"types": "./dist/plugins/unstorage/plugin.d.ts",
+			"import": "./dist/plugins/unstorage/plugin.js",
+			"default": "./dist/plugins/unstorage/plugin.js"
 		}
 	},
 	"files": [

package/dist/plugin-query.d.ts

@@ -1,19 +0,0 @@
-import { t as Plugin } from "./store-BGsRIZeM.js";
-
-//#region src/plugins/query/plugin.d.ts
-type QueryConfig<T, U = T> = {
-  where: (data: T) => boolean;
-  select?: (data: T) => U;
-  order?: (a: U, b: U) => number;
-};
-type Query<U> = {
-  results: () => Map<string, U>;
-  onChange: (callback: () => void) => () => void;
-  dispose: () => void;
-};
-type QueryMethods<T> = {
-  query: <U = T>(config: QueryConfig<T, U>) => Query<U>;
-};
-declare const queryPlugin: <T>() => Plugin<T, QueryMethods<T>>;
-//#endregion
-export { type Query, type QueryConfig, type QueryMethods, queryPlugin };

package/dist/plugin-query.js

@@ -1,102 +0,0 @@
-//#region src/plugins/query/plugin.ts
-const queryPlugin = () => {
-	const queries = /* @__PURE__ */ new Set();
-	let store = null;
-	const hydrateQuery = (query) => {
-		if (!store) return;
-		query.results.clear();
-		for (const [key, value] of store.entries()) if (query.where(value)) {
-			const selected = query.select ? query.select(value) : value;
-			query.results.set(key, selected);
-		}
-	};
-	const runCallbacks = (dirtyQueries) => {
-		for (const query of dirtyQueries) for (const callback of query.callbacks) callback();
-		dirtyQueries.clear();
-	};
-	const onAdd = (entries) => {
-		const dirtyQueries = /* @__PURE__ */ new Set();
-		for (const [key, value] of entries) for (const q of queries) if (q.where(value)) {
-			const selected = q.select ? q.select(value) : value;
-			q.results.set(key, selected);
-			dirtyQueries.add(q);
-		}
-		runCallbacks(dirtyQueries);
-	};
-	const onUpdate = (entries) => {
-		const dirtyQueries = /* @__PURE__ */ new Set();
-		for (const [key, value] of entries) for (const q of queries) {
-			const matches = q.where(value);
-			const inResults = q.results.has(key);
-			if (matches && !inResults) {
-				const selected = q.select ? q.select(value) : value;
-				q.results.set(key, selected);
-				dirtyQueries.add(q);
-			} else if (!matches && inResults) {
-				q.results.delete(key);
-				dirtyQueries.add(q);
-			} else if (matches && inResults) {
-				const selected = q.select ? q.select(value) : value;
-				q.results.set(key, selected);
-				dirtyQueries.add(q);
-			}
-		}
-		runCallbacks(dirtyQueries);
-	};
-	const onDelete = (keys) => {
-		const dirtyQueries = /* @__PURE__ */ new Set();
-		for (const key of keys) for (const q of queries) if (q.results.has(key)) {
-			q.results.delete(key);
-			dirtyQueries.add(q);
-		}
-		runCallbacks(dirtyQueries);
-	};
-	return {
-		hooks: {
-			onInit: (s) => {
-				store = s;
-				for (const q of queries) hydrateQuery(q);
-			},
-			onDispose: () => {
-				queries.clear();
-				store = null;
-			},
-			onAdd,
-			onUpdate,
-			onDelete
-		},
-		methods: { query: (config) => {
-			const query = {
-				where: config.where,
-				...config.select && { select: config.select },
-				...config.order && { order: config.order },
-				results: /* @__PURE__ */ new Map(),
-				callbacks: /* @__PURE__ */ new Set()
-			};
-			queries.add(query);
-			hydrateQuery(query);
-			return {
-				results: () => {
-					if (query.order) {
-						const orderFn = query.order;
-						const sorted = Array.from(query.results).sort(([, a], [, b]) => orderFn(a, b));
-						return new Map(sorted);
-					} else return new Map(query.results);
-				},
-				onChange: (callback) => {
-					query.callbacks.add(callback);
-					return () => {
-						query.callbacks.delete(callback);
-					};
-				},
-				dispose: () => {
-					queries.delete(query);
-					query.callbacks.clear();
-				}
-			};
-		} }
-	};
-};
-
-//#endregion
-export { queryPlugin };

package/dist/plugin-unstorage.d.ts

@@ -1,17 +0,0 @@
-import { a as StoreSnapshot, t as Plugin } from "./store-BGsRIZeM.js";
-import { Storage } from "unstorage";
-
-//#region src/plugins/unstorage/plugin.d.ts
-type MaybePromise<T> = T | Promise<T>;
-type UnstorageOnBeforeSet = (data: StoreSnapshot) => MaybePromise<StoreSnapshot>;
-type UnstorageOnAfterGet = (data: StoreSnapshot) => MaybePromise<StoreSnapshot>;
-type UnstorageConfig = {
-  debounceMs?: number;
-  pollIntervalMs?: number;
-  onBeforeSet?: UnstorageOnBeforeSet;
-  onAfterGet?: UnstorageOnAfterGet;
-  skip?: () => boolean;
-};
-declare const unstoragePlugin: <T>(key: string, storage: Storage<StoreSnapshot>, config?: UnstorageConfig) => Plugin<T>;
-//#endregion
-export { type UnstorageConfig, unstoragePlugin };

package/dist/store-BGsRIZeM.d.ts

@@ -1,86 +0,0 @@
-//#region src/value.d.ts
-type EncodedValue<T> = {
-  "~value": T;
-  "~eventstamp": string;
-};
-//#endregion
-//#region src/record.d.ts
-type EncodedRecord = {
-  [key: string]: EncodedValue<unknown> | EncodedRecord;
-};
-//#endregion
-//#region src/document.d.ts
-type EncodedDocument = {
-  "~id": string;
-  "~data": EncodedValue<unknown> | EncodedRecord;
-  "~deletedAt": string | null;
-};
-declare const processDocument: (doc: EncodedDocument, process: (value: EncodedValue<unknown>) => EncodedValue<unknown>) => EncodedDocument;
-//#endregion
-//#region src/transaction.d.ts
-type DeepPartial<T> = T extends object ? { [P in keyof T]?: DeepPartial<T[P]> } : T;
-type StorePutOptions = {
-  withId?: string;
-};
-type StoreSetTransaction<T> = {
-  add: (value: T, options?: StorePutOptions) => string;
-  update: (key: string, value: DeepPartial<T>) => void;
-  merge: (doc: EncodedDocument) => void;
-  del: (key: string) => void;
-  get: (key: string) => T | null;
-  rollback: () => void;
-};
-//#endregion
-//#region src/store.d.ts
-/**
- * Type constraint to prevent Promise returns from set callbacks.
- * Transactions must be synchronous operations.
- */
-type NotPromise<T> = T extends Promise<any> ? never : T;
-/**
- * Plugin lifecycle and event hooks.
- * All hooks are optional except onInit and onDispose, which are required.
- */
-type PluginHooks<T> = {
-  onInit: (store: Store<T>) => Promise<void> | void;
-  onDispose: () => Promise<void> | void;
-  onAdd?: (entries: ReadonlyArray<readonly [string, T]>) => void;
-  onUpdate?: (entries: ReadonlyArray<readonly [string, T]>) => void;
-  onDelete?: (keys: ReadonlyArray<string>) => void;
-};
-type PluginMethods = Record<string, (...args: any[]) => any>;
-type Plugin<T, M extends PluginMethods = {}> = {
-  hooks: PluginHooks<T>;
-  methods?: M;
-};
-/**
- * Complete persistent state of a store.
- * Contains all encoded documents (including deleted ones with ~deletedAt metadata)
- * and the latest eventstamp for clock synchronization during merges.
- */
-type StoreSnapshot = {
-  docs: EncodedDocument[];
-  latestEventstamp: string;
-};
-type Store<T, Extended = {}> = {
-  get: (key: string) => T | null;
-  begin: <R = void>(callback: (tx: StoreSetTransaction<T>) => NotPromise<R>, opts?: {
-    silent?: boolean;
-  }) => NotPromise<R>;
-  add: (value: T, options?: StorePutOptions) => string;
-  update: (key: string, value: DeepPartial<T>) => void;
-  del: (key: string) => void;
-  entries: () => IterableIterator<readonly [string, T]>;
-  snapshot: () => StoreSnapshot;
-  merge: (snapshot: StoreSnapshot) => void;
-  use: <M extends PluginMethods>(plugin: Plugin<T, M>) => Store<T, Extended & M>;
-  init: () => Promise<Store<T, Extended>>;
-  dispose: () => Promise<void>;
-  latestEventstamp: () => string;
-  forwardClock: (eventstamp: string) => void;
-} & Extended;
-declare const createStore: <T>(config?: {
-  getId?: () => string;
-}) => Store<T, {}>;
-//#endregion
-export { StoreSnapshot as a, processDocument as c, Store as i, PluginHooks as n, createStore as o, PluginMethods as r, EncodedDocument as s, Plugin as t };