@byearlybird/starling 0.9.3 → 0.10.0

package/package.json

@@ -1,6 +1,7 @@
 {
 	"name": "@byearlybird/starling",
-	"version": "0.9.3",
+	"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.",
 	"type": "module",
 	"license": "MIT",
 	"main": "./dist/index.js",
@@ -10,11 +11,6 @@
 			"types": "./dist/index.d.ts",
 			"import": "./dist/index.js",
 			"default": "./dist/index.js"
-		},
-		"./plugin-unstorage": {
-			"types": "./dist/plugins/unstorage/plugin.d.ts",
-			"import": "./dist/plugins/unstorage/plugin.js",
-			"default": "./dist/plugins/unstorage/plugin.js"
 		}
 	},
 	"files": [
@@ -24,14 +20,6 @@
 		"build": "bun run build.ts",
 		"prepublishOnly": "bun run build.ts"
 	},
-	"peerDependencies": {
-		"unstorage": "^1.17.1"
-	},
-	"peerDependenciesMeta": {
-		"unstorage": {
-			"optional": true
-		}
-	},
 	"publishConfig": {
 		"access": "public"
 	}

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

@@ -1,54 +0,0 @@
-import { c as Collection, t as Plugin } from "../../store-bS1Nb57l.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>;
-/**
- * Configuration options for the unstorage persistence plugin.
- */
-type UnstorageConfig = {
-  /** Delay in ms to collapse rapid mutations into a single write. Default: 0 (immediate) */
-  debounceMs?: number;
-  /** Interval in ms to poll storage for external changes. When set, enables automatic sync. */
-  pollIntervalMs?: number;
-  /** Hook invoked before persisting to storage. Use for encryption, compression, etc. */
-  onBeforeSet?: UnstorageOnBeforeSet;
-  /** Hook invoked after loading from storage. Use for decryption, validation, etc. */
-  onAfterGet?: UnstorageOnAfterGet;
-  /** Function that returns true to skip persistence operations. Use for conditional sync. */
-  skip?: () => boolean;
-};
-/**
- * Persistence plugin for Starling using unstorage backends.
- *
- * Automatically persists store snapshots and optionally polls for external changes.
- *
- * @param key - Storage key for this dataset
- * @param storage - Unstorage instance (localStorage, HTTP, filesystem, etc.)
- * @param config - Optional configuration for debouncing, polling, hooks, and conditional sync
- * @returns Plugin instance for store.use()
- *
- * @example
- * ```ts
- * import { unstoragePlugin } from "@byearlybird/starling/plugin-unstorage";
- * import { createStorage } from "unstorage";
- * import localStorageDriver from "unstorage/drivers/localstorage";
- *
- * const store = await new Store<Todo>()
- *   .use(unstoragePlugin('todos', createStorage({
- *     driver: localStorageDriver({ base: 'app:' })
- *   }), {
- *     debounceMs: 300,
- *     pollIntervalMs: 5000,
- *     skip: () => !navigator.onLine
- *   }))
- *   .init();
- * ```
- *
- * @see {@link ../../../../docs/plugins/unstorage.md} for detailed configuration guide
- */
-declare function unstoragePlugin<T>(key: string, storage: Storage<Collection>, config?: UnstorageConfig): Plugin<T>;
-//#endregion
-export { type UnstorageConfig, unstoragePlugin };

package/dist/plugins/unstorage/plugin.js

@@ -1,104 +0,0 @@
-//#region src/plugins/unstorage/plugin.ts
-/**
-* Persistence plugin for Starling using unstorage backends.
-*
-* Automatically persists store snapshots and optionally polls for external changes.
-*
-* @param key - Storage key for this dataset
-* @param storage - Unstorage instance (localStorage, HTTP, filesystem, etc.)
-* @param config - Optional configuration for debouncing, polling, hooks, and conditional sync
-* @returns Plugin instance for store.use()
-*
-* @example
-* ```ts
-* import { unstoragePlugin } from "@byearlybird/starling/plugin-unstorage";
-* import { createStorage } from "unstorage";
-* import localStorageDriver from "unstorage/drivers/localstorage";
-*
-* const store = await new Store<Todo>()
-*   .use(unstoragePlugin('todos', createStorage({
-*     driver: localStorageDriver({ base: 'app:' })
-*   }), {
-*     debounceMs: 300,
-*     pollIntervalMs: 5000,
-*     skip: () => !navigator.onLine
-*   }))
-*   .init();
-* ```
-*
-* @see {@link ../../../../docs/plugins/unstorage.md} for detailed configuration guide
-*/
-function unstoragePlugin(key, storage, config = {}) {
-	const { debounceMs = 0, pollIntervalMs, onBeforeSet, onAfterGet, skip } = config;
-	let debounceTimer = null;
-	let pollInterval = null;
-	let store = null;
-	let persistPromise = null;
-	const persistSnapshot = async () => {
-		if (!store) return;
-		const data = store.collection();
-		const persisted = onBeforeSet !== void 0 ? await onBeforeSet(data) : data;
-		await storage.set(key, persisted);
-	};
-	const runPersist = async () => {
-		debounceTimer = null;
-		persistPromise = persistSnapshot();
-		await persistPromise;
-		persistPromise = null;
-	};
-	const schedulePersist = () => {
-		if (skip?.()) return;
-		if (debounceMs === 0) {
-			persistPromise = persistSnapshot().finally(() => {
-				persistPromise = null;
-			});
-			return;
-		}
-		if (debounceTimer !== null) clearTimeout(debounceTimer);
-		debounceTimer = setTimeout(() => {
-			runPersist();
-		}, debounceMs);
-	};
-	const pollStorage = async () => {
-		if (!store) return;
-		if (skip?.()) return;
-		const persisted = await storage.get(key);
-		if (!persisted) return;
-		const data = onAfterGet !== void 0 ? await onAfterGet(persisted) : persisted;
-		store.merge(data);
-	};
-	return {
-		onInit: async (s) => {
-			store = s;
-			await pollStorage();
-			if (pollIntervalMs !== void 0 && pollIntervalMs > 0) pollInterval = setInterval(() => {
-				pollStorage();
-			}, pollIntervalMs);
-		},
-		onDispose: async () => {
-			if (debounceTimer !== null) {
-				clearTimeout(debounceTimer);
-				debounceTimer = null;
-				await runPersist();
-			}
-			if (pollInterval !== null) {
-				clearInterval(pollInterval);
-				pollInterval = null;
-			}
-			if (persistPromise !== null) await persistPromise;
-			store = null;
-		},
-		onAdd: () => {
-			schedulePersist();
-		},
-		onUpdate: () => {
-			schedulePersist();
-		},
-		onDelete: () => {
-			schedulePersist();
-		}
-	};
-}
-
-//#endregion
-export { unstoragePlugin };

package/dist/store-bS1Nb57l.d.ts

@@ -1,365 +0,0 @@
-//#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;
-};
-/**
- * Transform all values in a document using a provided function.
- *
- * Useful for custom serialization in plugin hooks (encryption, compression, etc.)
- *
- * @param doc - Document to transform
- * @param process - Function to apply to each leaf value
- * @returns New document with transformed values
- *
- * @example
- * ```ts
- * // Encrypt all values before persisting
- * const encrypted = processDocument(doc, (value) => ({
- *   ...value,
- *   "~value": encrypt(value["~value"])
- * }));
- * ```
- */
-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;
-};
-/**
- * Change tracking information returned by mergeCollections.
- * Categorizes documents by mutation type for hook notifications.
- */
-type CollectionChanges = {
-  /** Documents that were newly added (didn't exist before or were previously deleted) */
-  added: Map<string, EncodedDocument>;
-  /** Documents that were modified (existed before and changed) */
-  updated: Map<string, EncodedDocument>;
-  /** Documents that were deleted (newly marked with ~deletedAt) */
-  deleted: Set<string>;
-};
-/**
- * Result of merging two collections.
- */
-type MergeCollectionsResult = {
-  /** The merged collection with updated documents and forwarded clock */
-  collection: Collection;
-  /** Change tracking for plugin hook notifications */
-  changes: CollectionChanges;
-};
-/**
- * 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"
- * ```
- */
-declare function mergeCollections(into: Collection, from: Collection): MergeCollectionsResult;
-//#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;
-/**
- * Options for adding documents to the store.
- */
-type StoreAddOptions = {
-  /** Provide a custom ID instead of generating one */
-  withId?: string;
-};
-/**
- * Configuration options for creating a Store instance.
- */
-type StoreConfig = {
-  /** Custom ID generator. Defaults to crypto.randomUUID() */
-  getId?: () => string;
-};
-/**
- * Transaction context for batching multiple operations with rollback support.
- *
- * Transactions allow you to group multiple mutations together and optionally
- * abort all changes if validation fails.
- *
- * @example
- * ```ts
- * store.begin((tx) => {
- *   const id = tx.add({ name: 'Alice' });
- *   if (!isValid(tx.get(id))) {
- *     tx.rollback(); // Abort all changes
- *   }
- * });
- * ```
- */
-type StoreSetTransaction<T> = {
-  /** Add a document and return its ID */
-  add: (value: T, options?: StoreAddOptions) => string;
-  /** Update a document with a partial value (field-level merge) */
-  update: (key: string, value: DeepPartial<T>) => void;
-  /** Merge an encoded document (used by sync/persistence plugins) */
-  merge: (doc: EncodedDocument) => void;
-  /** Soft-delete a document */
-  del: (key: string) => void;
-  /** Get a document within this transaction */
-  get: (key: string) => T | null;
-  /** Abort the transaction and discard all changes */
-  rollback: () => void;
-};
-/**
- * Plugin interface for extending store behavior with persistence, analytics, etc.
- *
- * All hooks are optional. Mutation hooks receive batched entries after each
- * transaction commits.
- *
- * @example
- * ```ts
- * const loggingPlugin: Plugin<Todo> = {
- *   onInit: async () => console.log('Store initialized'),
- *   onAdd: (entries) => console.log('Added:', entries.length),
- *   onDispose: async () => console.log('Store disposed')
- * };
- * ```
- */
-type Plugin<T> = {
-  /** Called once when store.init() runs */
-  onInit: (store: Store<T>) => Promise<void> | void;
-  /** Called once when store.dispose() runs */
-  onDispose: () => Promise<void> | void;
-  /** Called after documents are added (batched per transaction) */
-  onAdd?: (entries: ReadonlyArray<readonly [string, T]>) => void;
-  /** Called after documents are updated (batched per transaction) */
-  onUpdate?: (entries: ReadonlyArray<readonly [string, T]>) => void;
-  /** Called after documents are deleted (batched per transaction) */
-  onDelete?: (keys: ReadonlyArray<string>) => void;
-};
-/**
- * Configuration for creating a reactive query.
- *
- * Queries automatically update when matching documents change.
- *
- * @example
- * ```ts
- * const config: QueryConfig<Todo> = {
- *   where: (todo) => !todo.completed,
- *   select: (todo) => todo.text,
- *   order: (a, b) => a.localeCompare(b)
- * };
- * ```
- */
-type QueryConfig<T, U = T> = {
-  /** Filter predicate - return true to include document in results */
-  where: (data: T) => boolean;
-  /** Optional projection - transform documents before returning */
-  select?: (data: T) => U;
-  /** Optional comparator for stable ordering of results */
-  order?: (a: U, b: U) => number;
-};
-/**
- * A reactive query handle that tracks matching documents and notifies on changes.
- *
- * Call `dispose()` when done to clean up listeners and remove from the store.
- */
-type Query<U> = {
-  /** Get current matching documents as [id, document] tuples */
-  results: () => Array<readonly [string, U]>;
-  /** Register a change listener. Returns unsubscribe function. */
-  onChange: (callback: () => void) => () => void;
-  /** Remove this query from the store and clear all listeners */
-  dispose: () => void;
-};
-/**
- * Lightweight local-first data store with built-in sync and reactive queries.
- *
- * Stores plain JavaScript objects with automatic field-level conflict resolution
- * using Last-Write-Wins semantics powered by hybrid logical clocks.
- *
- * @template T - The type of documents stored in this collection
- *
- * @example
- * ```ts
- * const store = await new Store<{ text: string; completed: boolean }>()
- *   .use(unstoragePlugin('todos', storage))
- *   .init();
- *
- * // Add, update, delete
- * const id = store.add({ text: 'Buy milk', completed: false });
- * store.update(id, { completed: true });
- * store.del(id);
- *
- * // Reactive queries
- * const activeTodos = store.query({ where: (todo) => !todo.completed });
- * activeTodos.onChange(() => console.log('Todos changed!'));
- * ```
- */
-declare class Store<T> {
-  #private;
-  constructor(config?: StoreConfig);
-  /**
-   * Get a document by ID.
-   * @returns The document, or null if not found or deleted
-   */
-  get(key: string): T | null;
-  /**
-   * Iterate over all non-deleted documents as [id, document] tuples.
-   */
-  entries(): IterableIterator<readonly [string, T]>;
-  /**
-   * Get the complete store state as a Collection for persistence or sync.
-   * @returns Collection containing all documents and the latest eventstamp
-   */
-  collection(): Collection;
-  /**
-   * Merge a collection from storage or another replica using field-level LWW.
-   * @param collection - Collection from storage or another store instance
-   */
-  merge(collection: Collection): void;
-  /**
-   * Run multiple operations in a transaction with rollback support.
-   *
-   * @param callback - Function receiving a transaction context
-   * @param opts - Optional config. Use `silent: true` to skip plugin hooks.
-   * @returns The callback's return value
-   *
-   * @example
-   * ```ts
-   * const id = store.begin((tx) => {
-   *   const newId = tx.add({ text: 'Buy milk' });
-   *   tx.update(newId, { priority: 'high' });
-   *   return newId; // Return value becomes begin()'s return value
-   * });
-   * ```
-   */
-  begin<R = void>(callback: (tx: StoreSetTransaction<T>) => NotPromise<R>, opts?: {
-    silent?: boolean;
-  }): NotPromise<R>;
-  /**
-   * Add a document to the store.
-   * @returns The document's ID (generated or provided via options)
-   */
-  add(value: T, options?: StoreAddOptions): string;
-  /**
-   * Update a document with a partial value.
-   *
-   * Uses field-level merge - only specified fields are updated.
-   */
-  update(key: string, value: DeepPartial<T>): void;
-  /**
-   * Soft-delete a document.
-   *
-   * Deleted docs remain in snapshots for sync purposes but are
-   * excluded from queries and reads.
-   */
-  del(key: string): void;
-  /**
-   * Register a plugin for persistence, analytics, etc.
-   * @returns This store instance for chaining
-   */
-  use(plugin: Plugin<T>): this;
-  /**
-   * Initialize the store and run plugin onInit hooks.
-   *
-   * Must be called before using the store. Runs plugin setup (hydrate
-   * snapshots, start pollers, etc.) and hydrates existing queries.
-   *
-   * @returns This store instance for chaining
-   */
-  init(): Promise<this>;
-  /**
-   * Dispose the store and run plugin cleanup.
-   *
-   * Flushes pending operations, clears queries, and runs plugin teardown.
-   * Call when shutting down to avoid memory leaks.
-   */
-  dispose(): Promise<void>;
-  /**
-   * Create a reactive query that auto-updates when matching docs change.
-   *
-   * @example
-   * ```ts
-   * const active = store.query({ where: (todo) => !todo.completed });
-   * active.results(); // [[id, todo], ...]
-   * active.onChange(() => console.log('Updated!'));
-   * active.dispose(); // Clean up when done
-   * ```
-   */
-  query<U = T>(config: QueryConfig<T, U>): Query<U>;
-}
-//#endregion
-export { StoreAddOptions as a, Collection as c, processDocument as d, EncodedRecord as f, Store as i, mergeCollections as l, Query as n, StoreConfig as o, EncodedValue as p, QueryConfig as r, StoreSetTransaction as s, Plugin as t, EncodedDocument as u };