@byearlybird/starling 0.6.1 → 0.7.2

package/dist/index.d.ts

@@ -1,74 +1,2 @@
-//#region src/value.d.ts
-type EncodedValue<T$1> = {
-  "~value": T$1;
-  "~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$1> = T$1 extends object ? { [P in keyof T$1]?: DeepPartial<T$1[P]> } : T$1;
-type StorePutOptions = {
-  withId?: string;
-};
-type StoreSetTransaction<T$1> = {
-  add: (value: T$1, options?: StorePutOptions) => string;
-  update: (key: string, value: DeepPartial<T$1>) => void;
-  merge: (doc: EncodedDocument) => void;
-  del: (key: string) => void;
-  get: (key: string) => T$1 | 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$1> = T$1 extends Promise<any> ? never : T$1;
-/**
- * Plugin lifecycle and event hooks.
- * All hooks are optional except onInit and onDispose, which are required.
- */
-type PluginHooks<T$1> = {
-  onInit: (store: Store<T$1>) => Promise<void> | void;
-  onDispose: () => Promise<void> | void;
-  onAdd?: (entries: ReadonlyArray<readonly [string, T$1]>) => void;
-  onUpdate?: (entries: ReadonlyArray<readonly [string, T$1]>) => void;
-  onDelete?: (keys: ReadonlyArray<string>) => void;
-};
-type PluginMethods = Record<string, (...args: any[]) => any>;
-type Plugin<T$1, M$1 extends PluginMethods = {}> = {
-  hooks: PluginHooks<T$1>;
-  methods?: M$1;
-};
-type Store<T$1, Extended = {}> = {
-  get: (key: string) => T$1 | null;
-  begin: <R = void>(callback: (tx: StoreSetTransaction<T$1>) => NotPromise<R>, opts?: {
-    silent?: boolean;
-  }) => NotPromise<R>;
-  add: (value: T$1, options?: StorePutOptions) => string;
-  update: (key: string, value: DeepPartial<T$1>) => void;
-  del: (key: string) => void;
-  entries: () => IterableIterator<readonly [string, T$1]>;
-  snapshot: () => EncodedDocument[];
-  use: <M extends PluginMethods>(plugin: Plugin<T$1, M>) => Store<T$1, Extended & M>;
-  init: () => Promise<Store<T$1, Extended>>;
-  dispose: () => Promise<void>;
-} & Extended;
-declare const createStore: <T>(config?: {
-  getId?: () => string;
-}) => Store<T, {}>;
-//#endregion
-export { type EncodedDocument, Plugin, PluginHooks, PluginMethods, Store, createStore, processDocument };
+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-CMzcvcsT.js";
+export { type EncodedDocument, Plugin, PluginHooks, PluginMethods, Store, StoreSnapshot, createStore, processDocument };

package/dist/index.js

@@ -8,7 +8,7 @@ const encodeValue = (value, eventstamp) => ({
 	"~eventstamp": eventstamp
 });
 const decodeValue = (value) => value["~value"];
-const mergeValues = (into, from) => into["~eventstamp"] > from["~eventstamp"] ? into : from;
+const mergeValues = (into, from) => into["~eventstamp"] > from["~eventstamp"] ? [into, into["~eventstamp"]] : [from, from["~eventstamp"]];
 const isEncodedValue = (value) => !!(typeof value === "object" && value !== null && "~value" in value && "~eventstamp" in value);
 
 //#endregion
@@ -62,14 +62,21 @@ const decodeRecord = (obj) => {
 };
 const mergeRecords = (into, from) => {
 	const result = {};
+	let greatestEventstamp = null;
 	const step = (v1, v2, output) => {
 		for (const key in v1) {
 			if (!Object.hasOwn(v1, key)) continue;
 			const value1 = v1[key];
 			const value2 = v2[key];
-			if (isEncodedValue(value1) && isEncodedValue(value2)) output[key] = mergeValues(value1, value2);
-			else if (isEncodedValue(value1)) output[key] = value1;
-			else if (isObject(value1) && isObject(value2)) {
+			if (isEncodedValue(value1) && isEncodedValue(value2)) {
+				const [win, eventstamp] = mergeValues(value1, value2);
+				output[key] = win;
+				if (!greatestEventstamp || eventstamp > greatestEventstamp) greatestEventstamp = eventstamp;
+			} else if (isEncodedValue(value1)) {
+				output[key] = value1;
+				const eventstamp = value1["~eventstamp"];
+				if (!greatestEventstamp || eventstamp > greatestEventstamp) greatestEventstamp = eventstamp;
+			} else if (isObject(value1) && isObject(value2)) {
 				output[key] = {};
 				step(value1, value2, output[key]);
 			} else if (value1) output[key] = value1;
@@ -77,11 +84,17 @@ const mergeRecords = (into, from) => {
 		for (const key in v2) {
 			if (!Object.hasOwn(v2, key) || Object.hasOwn(output, key)) continue;
 			const value = v2[key];
-			if (value !== void 0) output[key] = value;
+			if (value !== void 0) {
+				output[key] = value;
+				if (isEncodedValue(value)) {
+					const eventstamp = value["~eventstamp"];
+					if (!greatestEventstamp || eventstamp > greatestEventstamp) greatestEventstamp = eventstamp;
+				}
+			}
 		}
 	};
 	step(into, from, result);
-	return result;
+	return [result, greatestEventstamp];
 };
 
 //#endregion
@@ -100,13 +113,17 @@ const mergeDocs = (into, from) => {
 	const intoIsValue = isEncodedValue(into["~data"]);
 	const fromIsValue = isEncodedValue(from["~data"]);
 	if (intoIsValue !== fromIsValue) throw new Error("Merge error: Incompatible types");
-	const mergedData = intoIsValue && fromIsValue ? mergeValues(into["~data"], from["~data"]) : mergeRecords(into["~data"], from["~data"]);
+	const [mergedData, dataEventstamp] = intoIsValue && fromIsValue ? mergeValues(into["~data"], from["~data"]) : mergeRecords(into["~data"], from["~data"]);
 	const mergedDeletedAt = into["~deletedAt"] && from["~deletedAt"] ? into["~deletedAt"] > from["~deletedAt"] ? into["~deletedAt"] : from["~deletedAt"] : into["~deletedAt"] || from["~deletedAt"] || null;
-	return {
+	let greatestEventstamp = dataEventstamp;
+	if (mergedDeletedAt) {
+		if (!greatestEventstamp || mergedDeletedAt > greatestEventstamp) greatestEventstamp = mergedDeletedAt;
+	}
+	return [{
 		"~id": into["~id"],
 		"~data": mergedData,
 		"~deletedAt": mergedDeletedAt
-	};
+	}, greatestEventstamp];
 };
 const deleteDoc = (doc, eventstamp) => ({
 	"~id": doc["~id"],
@@ -144,13 +161,12 @@ const createClock = () => {
 	let lastMs = Date.now();
 	return {
 		now: () => {
-			const nowMs = Date.now();
-			if (nowMs <= lastMs) counter++;
-			else {
-				lastMs = nowMs;
+			const wallMs = Date.now();
+			if (wallMs > lastMs) {
+				lastMs = wallMs;
 				counter = 0;
-			}
-			return encodeEventstamp(nowMs, counter);
+			} else counter++;
+			return encodeEventstamp(lastMs, counter);
 		},
 		latest() {
 			return encodeEventstamp(lastMs, counter);
@@ -190,10 +206,19 @@ const createKV = (iterable) => {
 					return staging.get(key) ?? null;
 				},
 				set(key, value, opts) {
-					if (opts?.replace) staging.set(key, value);
-					else {
+					if (opts?.replace) {
+						staging.set(key, value);
+						return null;
+					} else {
 						const prev = staging.get(key);
-						staging.set(key, prev ? mergeDocs(prev, value) : value);
+						if (prev) {
+							const [merged, eventstamp] = mergeDocs(prev, value);
+							staging.set(key, merged);
+							return eventstamp;
+						} else {
+							staging.set(key, value);
+							return null;
+						}
 					}
 				},
 				del(key, eventstamp) {
@@ -286,7 +311,10 @@ const createStore = (config = {}) => {
 			return iterator();
 		},
 		snapshot() {
-			return Array.from(kv.values());
+			return {
+				docs: Array.from(kv.values()),
+				latestEventstamp: clock.latest()
+			};
 		},
 		begin(callback, opts) {
 			const silent = opts?.silent ?? false;
@@ -360,6 +388,12 @@ const createStore = (config = {}) => {
 			const disposerArray = Array.from(onDisposeHandlers);
 			disposerArray.reverse();
 			for (const fn of disposerArray) await fn();
+		},
+		latestEventstamp() {
+			return clock.latest();
+		},
+		forwardClock(eventstamp) {
+			clock.forward(eventstamp);
 		}
 	};
 };

package/dist/plugin-query.d.ts

@@ -0,0 +1,19 @@
+import { t as Plugin } from "./store-CMzcvcsT.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

@@ -0,0 +1,102 @@
+//#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

@@ -0,0 +1,16 @@
+import { a as StoreSnapshot, t as Plugin } from "./store-CMzcvcsT.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;
+};
+declare const unstoragePlugin: <T>(key: string, storage: Storage<StoreSnapshot>, config?: UnstorageConfig) => Plugin<T>;
+//#endregion
+export { type UnstorageConfig, unstoragePlugin };

package/dist/plugin-unstorage.js

@@ -0,0 +1,68 @@
+//#region src/plugins/unstorage/plugin.ts
+const unstoragePlugin = (key, storage, config = {}) => {
+	const { debounceMs = 0, pollIntervalMs, onBeforeSet, onAfterGet } = config;
+	let debounceTimer = null;
+	let pollInterval = null;
+	let store = null;
+	const persistSnapshot = async () => {
+		if (!store) return;
+		const data = store.snapshot();
+		const persisted = onBeforeSet !== void 0 ? await onBeforeSet(data) : data;
+		await storage.set(key, persisted);
+	};
+	const schedulePersist = () => {
+		const runPersist = () => {
+			debounceTimer = null;
+			persistSnapshot();
+		};
+		if (debounceMs === 0) {
+			runPersist();
+			return;
+		}
+		if (debounceTimer !== null) clearTimeout(debounceTimer);
+		debounceTimer = setTimeout(runPersist, debounceMs);
+	};
+	const pollStorage = async () => {
+		if (!store) return;
+		const persisted = await storage.get(key);
+		if (!persisted) return;
+		const data = onAfterGet !== void 0 ? await onAfterGet(persisted) : persisted;
+		if (!data || !data.docs || data.docs.length === 0) return;
+		store.forwardClock(data.latestEventstamp);
+		store.begin((tx) => {
+			for (const doc of data.docs) tx.merge(doc);
+		});
+	};
+	return { hooks: {
+		onInit: async (s) => {
+			store = s;
+			await pollStorage();
+			if (pollIntervalMs !== void 0 && pollIntervalMs > 0) pollInterval = setInterval(() => {
+				pollStorage();
+			}, pollIntervalMs);
+		},
+		onDispose: () => {
+			if (debounceTimer !== null) {
+				clearTimeout(debounceTimer);
+				debounceTimer = null;
+			}
+			if (pollInterval !== null) {
+				clearInterval(pollInterval);
+				pollInterval = null;
+			}
+			store = null;
+		},
+		onAdd: () => {
+			schedulePersist();
+		},
+		onUpdate: () => {
+			schedulePersist();
+		},
+		onDelete: () => {
+			schedulePersist();
+		}
+	} };
+};
+
+//#endregion
+export { unstoragePlugin };

package/dist/store-CMzcvcsT.d.ts

@@ -0,0 +1,85 @@
+//#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;
+  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 };

package/package.json

@@ -1,10 +1,27 @@
 {
 	"name": "@byearlybird/starling",
-	"version": "0.6.1",
+	"version": "0.7.2",
 	"type": "module",
 	"license": "MIT",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"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"
+		}
+	},
 	"files": [
 		"dist"
 	],
@@ -12,6 +29,14 @@
 		"build": "bun run build.ts",
 		"prepublishOnly": "bun run build.ts"
 	},
+	"peerDependencies": {
+		"unstorage": "^1.17.1"
+	},
+	"peerDependenciesMeta": {
+		"unstorage": {
+			"optional": true
+		}
+	},
 	"publishConfig": {
 		"access": "public"
 	}