@byearlybird/starling 0.10.0 → 0.11.1

package/dist/plugin-http.d.ts

@@ -0,0 +1,139 @@
+import { a as AnyObject, s as JsonDocument } from "./index-D7bXWDg6.js";
+import { g as SchemasMap, r as DatabasePlugin } from "./db-DJ_6dO-K.js";
+
+//#region src/plugins/http/index.d.ts
+
+/**
+ * Context provided to the onRequest hook
+ */
+type RequestContext<T extends AnyObject = AnyObject> = {
+  collection: string;
+  operation: "GET" | "PATCH";
+  url: string;
+  document?: JsonDocument<T>;
+};
+/**
+ * Result returned by the onRequest hook
+ */
+type RequestHookResult<T extends AnyObject = AnyObject> = {
+  skip: true;
+} | {
+  headers?: Record<string, string>;
+  document?: JsonDocument<T>;
+} | undefined;
+/**
+ * Result returned by the onResponse hook
+ */
+type ResponseHookResult<T extends AnyObject = AnyObject> = {
+  document: JsonDocument<T>;
+} | {
+  skip: true;
+} | undefined;
+/**
+ * Configuration for the HTTP plugin
+ */
+type HttpPluginConfig<_Schemas extends SchemasMap> = {
+  /**
+   * Base URL for the HTTP server (e.g., "https://api.example.com")
+   */
+  baseUrl: string;
+  /**
+   * Interval in milliseconds to poll for server updates
+   * @default 5000
+   */
+  pollingInterval?: number;
+  /**
+   * Delay in milliseconds to debounce local mutations before pushing
+   * @default 1000
+   */
+  debounceDelay?: number;
+  /**
+   * Hook called before each HTTP request
+   * Return { skip: true } to abort the request
+   * Return { headers } to add custom headers
+   * Return { document } to transform the document (PATCH only)
+   */
+  onRequest?: <T extends AnyObject>(context: RequestContext<T>) => RequestHookResult<T>;
+  /**
+   * Hook called after each successful HTTP response
+   * Return { skip: true } to skip merging the response
+   * Return { document } to transform the document before merging
+   */
+  onResponse?: <T extends AnyObject>(context: {
+    collection: string;
+    document: JsonDocument<T>;
+  }) => ResponseHookResult<T>;
+  /**
+   * Retry configuration for failed requests
+   */
+  retry?: {
+    /**
+     * Maximum number of retry attempts
+     * @default 3
+     */
+    maxAttempts?: number;
+    /**
+     * Initial delay in milliseconds before first retry
+     * @default 1000
+     */
+    initialDelay?: number;
+    /**
+     * Maximum delay in milliseconds between retries
+     * @default 30000
+     */
+    maxDelay?: number;
+  };
+};
+/**
+ * Create an HTTP sync plugin for Starling databases.
+ *
+ * The plugin:
+ * - Fetches all collections from the server on init (single attempt)
+ * - Polls the server at regular intervals to fetch updates (with retry)
+ * - Debounces local mutations and pushes them to the server (with retry)
+ * - Supports request/response hooks for authentication, encryption, etc.
+ *
+ * @param config - HTTP plugin configuration
+ * @returns A DatabasePlugin instance
+ *
+ * @example
+ * ```typescript
+ * const db = await createDatabase({
+ *   name: "my-app",
+ *   schema: {
+ *     tasks: { schema: taskSchema, getId: (task) => task.id },
+ *   },
+ * })
+ *   .use(httpPlugin({
+ *     baseUrl: "https://api.example.com",
+ *     onRequest: () => ({
+ *       headers: { Authorization: `Bearer ${token}` }
+ *     })
+ *   }))
+ *   .init();
+ * ```
+ *
+ * @example With encryption
+ * ```typescript
+ * const db = await createDatabase({
+ *   name: "my-app",
+ *   schema: {
+ *     tasks: { schema: taskSchema, getId: (task) => task.id },
+ *   },
+ * })
+ *   .use(httpPlugin({
+ *     baseUrl: "https://api.example.com",
+ *     onRequest: ({ document }) => ({
+ *       headers: { Authorization: `Bearer ${token}` },
+ *       document: document ? encrypt(document) : undefined
+ *     }),
+ *     onResponse: ({ document }) => ({
+ *       document: decrypt(document)
+ *     })
+ *   }))
+ *   .init();
+ * ```
+ */
+declare function httpPlugin<Schemas extends SchemasMap>(config: HttpPluginConfig<Schemas>): DatabasePlugin<Schemas>;
+//#endregion
+export { HttpPluginConfig, RequestContext, RequestHookResult, ResponseHookResult, httpPlugin };

package/dist/plugin-http.js

@@ -0,0 +1,191 @@
+//#region src/plugins/http/index.ts
+/**
+* Create an HTTP sync plugin for Starling databases.
+*
+* The plugin:
+* - Fetches all collections from the server on init (single attempt)
+* - Polls the server at regular intervals to fetch updates (with retry)
+* - Debounces local mutations and pushes them to the server (with retry)
+* - Supports request/response hooks for authentication, encryption, etc.
+*
+* @param config - HTTP plugin configuration
+* @returns A DatabasePlugin instance
+*
+* @example
+* ```typescript
+* const db = await createDatabase({
+*   name: "my-app",
+*   schema: {
+*     tasks: { schema: taskSchema, getId: (task) => task.id },
+*   },
+* })
+*   .use(httpPlugin({
+*     baseUrl: "https://api.example.com",
+*     onRequest: () => ({
+*       headers: { Authorization: `Bearer ${token}` }
+*     })
+*   }))
+*   .init();
+* ```
+*
+* @example With encryption
+* ```typescript
+* const db = await createDatabase({
+*   name: "my-app",
+*   schema: {
+*     tasks: { schema: taskSchema, getId: (task) => task.id },
+*   },
+* })
+*   .use(httpPlugin({
+*     baseUrl: "https://api.example.com",
+*     onRequest: ({ document }) => ({
+*       headers: { Authorization: `Bearer ${token}` },
+*       document: document ? encrypt(document) : undefined
+*     }),
+*     onResponse: ({ document }) => ({
+*       document: decrypt(document)
+*     })
+*   }))
+*   .init();
+* ```
+*/
+function httpPlugin(config) {
+	const { baseUrl, pollingInterval = 5e3, debounceDelay = 1e3, onRequest, onResponse, retry = {} } = config;
+	const { maxAttempts = 3, initialDelay = 1e3, maxDelay = 3e4 } = retry;
+	let pollingTimer = null;
+	let unsubscribe = null;
+	const debounceTimers = /* @__PURE__ */ new Map();
+	return { handlers: {
+		async init(db) {
+			const collectionNames = db.collectionKeys();
+			for (const collectionName of collectionNames) try {
+				await fetchCollection(db, collectionName, baseUrl, onRequest, onResponse, false);
+			} catch (error) {
+				console.error(`Failed to fetch collection "${String(collectionName)}" during init:`, error);
+			}
+			pollingTimer = setInterval(async () => {
+				for (const collectionName of collectionNames) try {
+					await fetchCollection(db, collectionName, baseUrl, onRequest, onResponse, true, maxAttempts, initialDelay, maxDelay);
+				} catch (error) {
+					console.error(`Failed to poll collection "${String(collectionName)}":`, error);
+				}
+			}, pollingInterval);
+			unsubscribe = db.on("mutation", (event) => {
+				const collectionName = event.collection;
+				const key = String(collectionName);
+				const existingTimer = debounceTimers.get(key);
+				if (existingTimer) clearTimeout(existingTimer);
+				const timer = setTimeout(async () => {
+					debounceTimers.delete(key);
+					try {
+						await pushCollection(db, collectionName, baseUrl, onRequest, onResponse, maxAttempts, initialDelay, maxDelay);
+					} catch (error) {
+						console.error(`Failed to push collection "${String(collectionName)}":`, error);
+					}
+				}, debounceDelay);
+				debounceTimers.set(key, timer);
+			});
+		},
+		async dispose(_db) {
+			if (pollingTimer) {
+				clearInterval(pollingTimer);
+				pollingTimer = null;
+			}
+			for (const timer of debounceTimers.values()) clearTimeout(timer);
+			debounceTimers.clear();
+			if (unsubscribe) {
+				unsubscribe();
+				unsubscribe = null;
+			}
+		}
+	} };
+}
+/**
+* Fetch a collection from the server (GET request)
+*/
+async function fetchCollection(db, collectionName, baseUrl, onRequest, onResponse, enableRetry, maxAttempts = 3, initialDelay = 1e3, maxDelay = 3e4) {
+	const url = `${baseUrl}/${db.name}/${String(collectionName)}`;
+	const requestResult = onRequest?.({
+		collection: String(collectionName),
+		operation: "GET",
+		url
+	});
+	if (requestResult && "skip" in requestResult && requestResult.skip) return;
+	const headers = requestResult && "headers" in requestResult ? requestResult.headers : void 0;
+	const executeRequest = async () => {
+		const response = await fetch(url, {
+			method: "GET",
+			headers: {
+				"Content-Type": "application/json",
+				...headers
+			}
+		});
+		if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+		const document = await response.json();
+		const responseResult = onResponse?.({
+			collection: String(collectionName),
+			document
+		});
+		if (responseResult && "skip" in responseResult && responseResult.skip) return;
+		const finalDocument = responseResult && "document" in responseResult ? responseResult.document : document;
+		db[collectionName].merge(finalDocument);
+	};
+	if (enableRetry) await withRetry(executeRequest, maxAttempts, initialDelay, maxDelay);
+	else await executeRequest();
+}
+/**
+* Push a collection to the server (PATCH request)
+*/
+async function pushCollection(db, collectionName, baseUrl, onRequest, onResponse, maxAttempts = 3, initialDelay = 1e3, maxDelay = 3e4) {
+	const url = `${baseUrl}/${db.name}/${String(collectionName)}`;
+	const document = db[collectionName].toDocument();
+	const requestResult = onRequest?.({
+		collection: String(collectionName),
+		operation: "PATCH",
+		url,
+		document
+	});
+	if (requestResult && "skip" in requestResult && requestResult.skip) return;
+	const headers = requestResult && "headers" in requestResult ? requestResult.headers : void 0;
+	const requestDocument = requestResult && "document" in requestResult ? requestResult.document : document;
+	const executeRequest = async () => {
+		const response = await fetch(url, {
+			method: "PATCH",
+			headers: {
+				"Content-Type": "application/json",
+				...headers
+			},
+			body: JSON.stringify(requestDocument)
+		});
+		if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+		const responseDocument = await response.json();
+		const responseResult = onResponse?.({
+			collection: String(collectionName),
+			document: responseDocument
+		});
+		if (responseResult && "skip" in responseResult && responseResult.skip) return;
+		const finalDocument = responseResult && "document" in responseResult ? responseResult.document : responseDocument;
+		db[collectionName].merge(finalDocument);
+	};
+	await withRetry(executeRequest, maxAttempts, initialDelay, maxDelay);
+}
+/**
+* Execute a function with exponential backoff retry logic
+*/
+async function withRetry(fn, maxAttempts, initialDelay, maxDelay) {
+	let lastError;
+	let delay = initialDelay;
+	for (let attempt = 0; attempt < maxAttempts; attempt++) try {
+		return await fn();
+	} catch (error) {
+		lastError = error instanceof Error ? error : new Error(String(error));
+		if (attempt < maxAttempts - 1) {
+			await new Promise((resolve) => setTimeout(resolve, delay));
+			delay = Math.min(delay * 2, maxDelay);
+		}
+	}
+	throw lastError;
+}
+
+//#endregion
+export { httpPlugin };

package/dist/plugin-idb.d.ts

@@ -0,0 +1,59 @@
+import "./index-D7bXWDg6.js";
+import { r as DatabasePlugin } from "./db-DJ_6dO-K.js";
+
+//#region src/plugins/idb/index.d.ts
+type IdbPluginConfig = {
+  /**
+   * Version of the IndexedDB database
+   * @default 1
+   */
+  version?: number;
+  /**
+   * Use BroadcastChannel API for instant cross-tab sync
+   * @default true
+   */
+  useBroadcastChannel?: boolean;
+};
+/**
+ * Create an IndexedDB persistence plugin for Starling databases.
+ *
+ * The plugin:
+ * - Loads existing documents from IndexedDB on init
+ * - Persists all documents to IndexedDB on every mutation
+ * - Enables instant cross-tab sync via BroadcastChannel API
+ * - Gracefully closes the database connection on dispose
+ *
+ * Cross-tab sync uses the BroadcastChannel API to notify other tabs
+ * of changes in real-time. When a mutation occurs in one tab, other tabs
+ * are instantly notified and reload the data from IndexedDB.
+ *
+ * @param config - IndexedDB configuration
+ * @returns A DatabasePlugin instance
+ *
+ * @example
+ * ```typescript
+ * const db = await createDatabase({
+ *   name: "my-app",
+ *   schema: {
+ *     tasks: { schema: taskSchema, getId: (task) => task.id },
+ *   },
+ * })
+ *   .use(idbPlugin())
+ *   .init();
+ * ```
+ *
+ * @example Disable BroadcastChannel
+ * ```typescript
+ * const db = await createDatabase({
+ *   name: "my-app",
+ *   schema: {
+ *     tasks: { schema: taskSchema, getId: (task) => task.id },
+ *   },
+ * })
+ *   .use(idbPlugin({ useBroadcastChannel: false }))
+ *   .init();
+ * ```
+ */
+declare function idbPlugin(config?: IdbPluginConfig): DatabasePlugin<any>;
+//#endregion
+export { IdbPluginConfig, idbPlugin };

package/dist/plugin-idb.js

@@ -0,0 +1,169 @@
+//#region src/plugins/idb/index.ts
+/**
+* Create an IndexedDB persistence plugin for Starling databases.
+*
+* The plugin:
+* - Loads existing documents from IndexedDB on init
+* - Persists all documents to IndexedDB on every mutation
+* - Enables instant cross-tab sync via BroadcastChannel API
+* - Gracefully closes the database connection on dispose
+*
+* Cross-tab sync uses the BroadcastChannel API to notify other tabs
+* of changes in real-time. When a mutation occurs in one tab, other tabs
+* are instantly notified and reload the data from IndexedDB.
+*
+* @param config - IndexedDB configuration
+* @returns A DatabasePlugin instance
+*
+* @example
+* ```typescript
+* const db = await createDatabase({
+*   name: "my-app",
+*   schema: {
+*     tasks: { schema: taskSchema, getId: (task) => task.id },
+*   },
+* })
+*   .use(idbPlugin())
+*   .init();
+* ```
+*
+* @example Disable BroadcastChannel
+* ```typescript
+* const db = await createDatabase({
+*   name: "my-app",
+*   schema: {
+*     tasks: { schema: taskSchema, getId: (task) => task.id },
+*   },
+* })
+*   .use(idbPlugin({ useBroadcastChannel: false }))
+*   .init();
+* ```
+*/
+function idbPlugin(config = {}) {
+	const { version = 1, useBroadcastChannel = true } = config;
+	let dbInstance = null;
+	let unsubscribe = null;
+	let broadcastChannel = null;
+	const instanceId = crypto.randomUUID();
+	return { handlers: {
+		async init(db) {
+			const collectionNames = db.collectionKeys();
+			dbInstance = await openDatabase(db.name, version, collectionNames);
+			const savedDocs = await loadDocuments(dbInstance, collectionNames);
+			for (const collectionName of Object.keys(savedDocs)) {
+				const doc = savedDocs[collectionName];
+				const collection = db[collectionName];
+				if (doc && collection) collection.merge(doc);
+			}
+			unsubscribe = db.on("mutation", async () => {
+				if (dbInstance) {
+					const docs = db.toDocuments();
+					await saveDocuments(dbInstance, docs);
+					if (broadcastChannel) broadcastChannel.postMessage({
+						type: "mutation",
+						instanceId,
+						timestamp: Date.now()
+					});
+				}
+			});
+			if (useBroadcastChannel && typeof BroadcastChannel !== "undefined") {
+				broadcastChannel = new BroadcastChannel(`starling:${db.name}`);
+				broadcastChannel.onmessage = async (event) => {
+					if (event.data.instanceId === instanceId) return;
+					if (event.data.type === "mutation" && dbInstance) {
+						const savedDocs$1 = await loadDocuments(dbInstance, collectionNames);
+						for (const collectionName of Object.keys(savedDocs$1)) {
+							const doc = savedDocs$1[collectionName];
+							const collection = db[collectionName];
+							if (doc && collection) collection.merge(doc);
+						}
+					}
+				};
+			}
+		},
+		async dispose(db) {
+			if (broadcastChannel) {
+				broadcastChannel.close();
+				broadcastChannel = null;
+			}
+			if (unsubscribe) {
+				unsubscribe();
+				unsubscribe = null;
+			}
+			if (dbInstance) {
+				const docs = db.toDocuments();
+				await saveDocuments(dbInstance, docs);
+				dbInstance.close();
+				dbInstance = null;
+			}
+		}
+	} };
+}
+/**
+* Open an IndexedDB database and create object stores for each collection
+*/
+function openDatabase(dbName, version, collectionNames) {
+	return new Promise((resolve, reject) => {
+		const request = indexedDB.open(dbName, version);
+		request.onerror = () => {
+			reject(/* @__PURE__ */ new Error(`Failed to open IndexedDB: ${request.error?.message}`));
+		};
+		request.onsuccess = () => {
+			resolve(request.result);
+		};
+		request.onupgradeneeded = (event) => {
+			const db = event.target.result;
+			for (const collectionName of collectionNames) if (!db.objectStoreNames.contains(collectionName)) db.createObjectStore(collectionName);
+		};
+	});
+}
+/**
+* Load documents from IndexedDB for all collections
+*/
+async function loadDocuments(db, collectionNames) {
+	const documents = {};
+	for (const collectionName of collectionNames) if (db.objectStoreNames.contains(collectionName)) {
+		const doc = await getFromStore(db, collectionName, "document");
+		if (doc) documents[collectionName] = doc;
+	}
+	return documents;
+}
+/**
+* Save documents to IndexedDB for all collections
+*/
+async function saveDocuments(db, documents) {
+	const promises = [];
+	for (const collectionName of Object.keys(documents)) if (db.objectStoreNames.contains(collectionName)) promises.push(putToStore(db, collectionName, "document", documents[collectionName]));
+	await Promise.all(promises);
+}
+/**
+* Get a value from an IndexedDB object store
+*/
+function getFromStore(db, storeName, key) {
+	return new Promise((resolve, reject) => {
+		const request = db.transaction(storeName, "readonly").objectStore(storeName).get(key);
+		request.onerror = () => {
+			reject(/* @__PURE__ */ new Error(`Failed to get from store ${storeName}: ${request.error?.message}`));
+		};
+		request.onsuccess = () => {
+			resolve(request.result ?? null);
+		};
+	});
+}
+/**
+* Put a value into an IndexedDB object store
+*/
+function putToStore(db, storeName, key, value) {
+	return new Promise((resolve, reject) => {
+		const request = db.transaction(storeName, "readwrite").objectStore(storeName).put(value, key);
+		request.onerror = () => {
+			reject(/* @__PURE__ */ new Error(`Failed to put to store ${storeName}: ${request.error?.message}`));
+		};
+		request.onsuccess = () => {
+			resolve();
+		};
+	});
+}
+
+//#endregion
+export { idbPlugin };

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@byearlybird/starling",
-	"version": "0.10.0",
-	"description": "Lightweight local-first data store with automatic cross-device sync. Plain JavaScript queries, framework-agnostic, zero dependencies. Offline-first apps without the complexity, in just 4KB.",
+	"version": "0.11.1",
+	"description": "Local-first data sync for JavaScript apps. Typed collections, transactions, and automatic conflict resolution.",
 	"type": "module",
 	"license": "MIT",
 	"main": "./dist/index.js",
@@ -11,6 +11,21 @@
 			"types": "./dist/index.d.ts",
 			"import": "./dist/index.js",
 			"default": "./dist/index.js"
+		},
+		"./core": {
+			"types": "./dist/core.d.ts",
+			"import": "./dist/core.js",
+			"default": "./dist/core.js"
+		},
+		"./plugin-idb": {
+			"types": "./dist/plugin-idb.d.ts",
+			"import": "./dist/plugin-idb.js",
+			"default": "./dist/plugin-idb.js"
+		},
+		"./plugin-http": {
+			"types": "./dist/plugin-http.d.ts",
+			"import": "./dist/plugin-http.js",
+			"default": "./dist/plugin-http.js"
 		}
 	},
 	"files": [
@@ -22,5 +37,10 @@
 	},
 	"publishConfig": {
 		"access": "public"
+	},
+	"devDependencies": {
+		"fake-indexeddb": "^6.0.0",
+		"happy-dom": "^20.0.10",
+		"zod": "^4.1.12"
 	}
 }