@byearlybird/starling 0.14.0 → 0.17.0

package/README.md

@@ -17,7 +17,7 @@ Requires TypeScript 5 or higher.
 ## Quick Example
 
 ```typescript
-import { createStore } from "@byearlybird/starling";
+import { createStore, collection } from "@byearlybird/starling";
 import { z } from "zod";
 
 const userSchema = z.object({
@@ -26,12 +26,10 @@ const userSchema = z.object({
 });
 
 const store = createStore({
-  collections: {
-    users: { schema: userSchema },
-  },
+  users: collection(userSchema, (data) => data.id),
 });
 
-store.add("users", { id: "1", name: "Alice" });
+store.put("users", { id: "1", name: "Alice" });
 const user = store.get("users", "1"); // { id: "1", name: "Alice" }
 ```
 
@@ -52,53 +50,62 @@ const user = store.get("users", "1"); // { id: "1", name: "Alice" }
 A store holds one or more collections. Each collection has a schema that defines what data it can store.
 
 ```typescript
-import { createStore } from "@byearlybird/starling";
+import { createStore, collection } from "@byearlybird/starling";
 import { z } from "zod";
 
 const store = createStore({
-  collections: {
-    users: {
-      schema: z.object({
-        id: z.string(),
-        name: z.string(),
-        email: z.string().optional(),
-      }),
-    },
-    notes: {
-      schema: z.object({
-        id: z.string(),
-        content: z.string(),
-      }),
-    },
-  },
+  users: collection(
+    z.object({
+      id: z.string(),
+      name: z.string(),
+      email: z.string().optional(),
+    }),
+    (data) => data.id,
+  ),
+  notes: collection(
+    z.object({
+      id: z.string(),
+      content: z.string(),
+    }),
+    (data) => data.id,
+  ),
 });
 ```
 
 ### Adding Documents
 
-Add new items to a collection with `add()`:
+Add new items to a collection using `put()`:
 
 ```typescript
-store.add("users", {
+store.put("users", {
   id: "1",
   name: "Alice",
   email: "alice@example.com",
 });
 ```
 
+Or use `transact()` for atomic multi-collection operations:
+
+```typescript
+store.transact((tx) => {
+  tx.put("users", { id: "1", name: "Alice", email: "alice@example.com" });
+  tx.put("notes", { id: "n1", content: "Hello" });
+});
+```
+
 ### Updating Documents
 
-Update existing items with `update()`:
+Update existing items using `patch()`:
 
 ```typescript
-store.update("users", "1", {
+store.patch("users", "1", {
   email: "newemail@example.com",
 });
 ```
 
 ### Removing Documents
 
-Remove items with `remove()`:
+Remove items using `remove()`:
 
 ```typescript
 store.remove("users", "1");
@@ -106,14 +113,14 @@ store.remove("users", "1");
 
 ### Reading Data
 
-The store provides simple getter methods:
+Read data directly from the store:
 
 ```typescript
 // Get a single item
 const user = store.get("users", "1");
 
 // Get all items as an array
-const allUsers = store.getAll("users");
+const allUsers = store.list("users");
 
 // You can easily derive other operations:
 const userIds = allUsers.map((u) => u.id);
@@ -122,75 +129,48 @@ const hasUser = allUsers.some((u) => u.id === "1");
 
 ### Listening to Changes
 
-Subscribe to changes with `onChange()`:
+Subscribe to changes with `subscribe()`:
 
 ```typescript
-// Listen to all store changes
-store.onChange((event) => {
-  console.log(`${event.collection} changed:`, event.event.type);
-  // Invalidate queries, update UI, etc.
+// Subscribe to specific collections
+const unsubscribe = store.subscribe(["users"], (event) => {
+  console.log("Users collection changed:", event);
+  const allUsers = store.list("users");
+  // Update UI, invalidate queries, etc.
 });
 
-// Filter for specific collection changes
-store.onChange((event) => {
-  if (event.collection === "users") {
-    console.log("User change:", event.event.type, event.event.id);
-    if (event.event.type === "add") {
-      console.log("New user:", event.event.data);
-    }
-  }
+// Or subscribe to all changes
+store.subscribe((event) => {
+  console.log("Store changed:", event);
 });
+
+// Later, unsubscribe
+unsubscribe();
 ```
 
 ## Merging Data
 
 Starling's core feature is conflict-free merging. When data changes in multiple places, Starling automatically resolves conflicts using timestamps.
 
-### Getting a Snapshot
-
-Get the current state of your store:
+Merge snapshots directly:
 
 ```typescript
-const snapshot = store.getSnapshot();
-// { clock: { ms: ..., seq: ... }, collections: { ... } }
-```
-
-### Merging a Snapshot
+// Get current state as a snapshot
+const snapshot = store.getState();
 
-Merge a snapshot from another device or user:
-
-```typescript
-// Get snapshot from another device
-const otherSnapshot = await fetchFromServer();
+// Send to server or save locally
+await sendToServer(snapshot);
 
-// Merge it into your store
-store.merge(otherSnapshot);
+// Later, merge a snapshot from another source
+const remoteSnapshot = await fetchFromServer();
+store.merge(remoteSnapshot);
 ```
 
 Starling automatically resolves conflicts. If the same field was changed in both places, it keeps the change with the newer timestamp (Last-Write-Wins).
 
-### Syncing Between Two Stores
-
-Here's a simple example of syncing between two stores:
-
-```typescript
-const store1 = createStore({ collections: { users: { schema: userSchema } } });
-const store2 = createStore({ collections: { users: { schema: userSchema } } });
-
-// Add data to store1
-store1.add("users", { id: "1", name: "Alice" });
-
-// Sync to store2
-const snapshot = store1.getSnapshot();
-store2.merge(snapshot);
-
-// Now store2 has the same data
-console.log(store2.get("users", "1")); // { id: "1", name: "Alice" }
-```
-
 ## Reactivity Integration
 
-Starling is framework-agnostic. Use `onChange()` to integrate with your reactive system:
+Starling is framework-agnostic. Use `subscribe()` to integrate with your reactive system:
 
 ### React with TanStack Query
 
@@ -201,16 +181,14 @@ function useUsers() {
   const queryClient = useQueryClient();
 
   useEffect(() => {
-    return store.onChange((event) => {
-      if (event.collection === "users") {
-        queryClient.invalidateQueries({ queryKey: ["users"] });
-      }
+    return store.subscribe(["users"], () => {
+      queryClient.invalidateQueries({ queryKey: ["users"] });
     });
   }, []);
 
   return useQuery({
     queryKey: ["users"],
-    queryFn: () => store.getAll("users"),
+    queryFn: () => store.list("users"),
   });
 }
 ```
@@ -222,11 +200,8 @@ import { useSyncExternalStore } from "react";
 
 function useUsers() {
   return useSyncExternalStore(
-    (callback) =>
-      store.onChange((event) => {
-        if (event.collection === "users") callback();
-      }),
-    () => store.getAll("users"),
+    (callback) => store.subscribe(["users"], () => callback()),
+    () => store.list("users"),
   );
 }
 ```
@@ -236,11 +211,9 @@ function useUsers() {
 ```typescript
 import { writable } from "svelte/store";
 
-const users = writable(store.getAll("users"));
-store.onChange((event) => {
-  if (event.collection === "users") {
-    users.set(store.getAll("users"));
-  }
+const users = writable(store.list("users"));
+store.subscribe(["users"], () => {
+  users.set(store.list("users"));
 });
 ```
 
@@ -249,11 +222,9 @@ store.onChange((event) => {
 ```typescript
 import { ref } from "vue";
 
-const users = ref(store.getAll("users"));
-store.onChange((event) => {
-  if (event.collection === "users") {
-    users.value = store.getAll("users");
-  }
+const users = ref(store.list("users"));
+store.subscribe(["users"], () => {
+  users.value = store.list("users");
 });
 ```
 
@@ -290,17 +261,25 @@ const schema = type({ id: "string", name: "string" });
 
 ### Store Methods
 
-- `add(collection, data)` - Add a new document to a collection
 - `get(collection, id)` - Get a document by ID from a collection
-- `getAll(collection)` - Get all documents from a collection as an array
-- `update(collection, id, data)` - Update an existing document in a collection
-- `remove(collection, id)` - Remove a document from a collection
-- `getSnapshot()` - Get the full store snapshot for syncing
-- `merge(snapshot)` - Merge a store snapshot
-- `onChange(listener)` - Subscribe to all collection changes
+- `list(collection)` - Get all documents as an array from a collection
+- `put(collection, data)` - Insert or replace a document (upsert, revives tombstoned IDs)
+- `patch(collection, id, data)` - Partially update an existing document (throws if ID missing)
+- `remove(collection, id)` - Remove a document
+- `transact(callback)` - Execute operations atomically. Collections are cloned lazily on first access.
+- `subscribe(callback)` - Subscribe to all collection changes
+- `subscribe(collections, callback)` - Subscribe to changes in specific collections
+- `getState()` - Get current store state as a snapshot
+- `merge(snapshot)` - Merge a snapshot into the store
 
 For full type definitions, see the TypeScript types exported from the package.
 
+## Package structure
+
+- **`lib/core/`** – CRDT primitives: hybrid logical clock, per-field atoms (LWW), tombstones, and document/collection merging.
+- **`lib/store/`** – Store API with collections, batching, queries, and change subscriptions.
+- **`lib/middleware/`** – Optional middleware (e.g. persistence).
+
 ## Development
 
 ```bash

package/dist/index.d.ts

@@ -5,22 +5,92 @@ type Clock = {
   ms: number;
   seq: number;
 };
-//#endregion
-//#region lib/core/document.d.ts
-type Field<T = unknown> = {
-  "~value": T;
-  "~stamp": string;
+/**
+ * Branded type for HLC timestamps.
+ * Stamps are lexicographically sortable hex strings encoding (ms, seq, nonce).
+ */
+type Stamp = string & {
+  readonly __brand: "Stamp";
 };
-type Document = Record<string, Field>;
+declare function advanceClock(current: Clock, next: Clock): Clock;
+declare function makeStamp(ms: number, seq: number): Stamp;
+/**
+ * Parse and validate a string as a Stamp. Use when deserializing stored state.
+ * Throws if the value is not a valid 24-character hex string.
+ */
+declare function asStamp(value: string): Stamp;
 //#endregion
 //#region lib/core/tombstone.d.ts
-type Tombstones = Record<string, string>;
+type Tombstones = Record<string, Stamp>;
+declare function isDeleted(id: string, tombstones: Tombstones): boolean;
+declare function mergeTombstones(target: Tombstones, source: Tombstones): Tombstones;
 //#endregion
-//#region lib/core/collection.d.ts
-type DocumentId = string;
-type Collection = {
-  documents: Record<DocumentId, Document>;
+//#region lib/core/types.d.ts
+declare const KEYS: {
+  readonly VAL: "~val";
+  readonly TS: "~ts";
 };
+/**
+ * Base constraint for plain document shapes - any object with string keys.
+ */
+type Document = Record<string, unknown>;
+type Atom<T> = {
+  [KEYS.VAL]: T;
+  [KEYS.TS]: Stamp;
+};
+/**
+ * Atomized document with plain shape T. Each key K is stored as Atom<T[K]> (per-field).
+ */
+type AtomizedDocument<T extends Document> = { [K in keyof T]: Atom<T[K]> };
+/**
+ * Collection of atomized documents with shape T. Map from document ID to AtomizedDocument<T>.
+ */
+type Collection<T extends Document> = Record<string, AtomizedDocument<T>>;
+/**
+ * Collection state containing documents and tombstones.
+ */
+type CollectionState<T extends Document> = {
+  documents: Collection<T>;
+  tombstones: Tombstones;
+};
+type StoreState = {
+  clock: Clock;
+  collections: Record<string, CollectionState<Document>>;
+};
+/**
+ * Type guard to check if a value is an AtomizedDocument.
+ * An AtomizedDocument is an object where all values are Atoms.
+ */
+declare function isAtomizedDocument<T extends Document>(value: unknown): value is AtomizedDocument<T>;
+/**
+ * Type guard to check if a value is a Collection.
+ * A Collection is a Record where all values are AtomizedDocuments.
+ */
+declare function isCollection<T extends Document>(value: unknown): value is Collection<T>;
+/**
+ * Type guard to check if a value is a CollectionState.
+ * A CollectionState has documents (Collection) and tombstones (Record<string, string>).
+ */
+declare function isCollectionState<T extends Document>(value: unknown): value is CollectionState<T>;
+//#endregion
+//#region lib/core/atomizer.d.ts
+declare function pack<T>(value: T, timestamp: Stamp): Atom<T>;
+declare function unpack<T>(node: unknown): T | undefined;
+declare function isAtom(node: unknown): node is Atom<unknown>;
+declare function atomize<T extends Document>(data: T, timestamp: Stamp): AtomizedDocument<T>;
+//#endregion
+//#region lib/core/lens.d.ts
+declare function createReadLens<T extends Document>(doc: AtomizedDocument<T>): T;
+//#endregion
+//#region lib/core/merge.d.ts
+/** Merges incoming doc fields into local. Adds new keys from incoming; LWW on conflicts. */
+declare function mergeDocs<T extends Document>(local: AtomizedDocument<T>, incoming: Partial<AtomizedDocument<T>>): AtomizedDocument<T>;
+/**
+ * Merges two collection states, respecting tombstones.
+ * Documents that are tombstoned are excluded from the result.
+ * For documents that exist in both collections, fields are merged using LWW semantics.
+ */
+declare function mergeCollections<T extends Document>(local: CollectionState<T>, incoming: CollectionState<T>): CollectionState<T>;
 //#endregion
 //#region lib/store/schema.d.ts
 /**
@@ -28,51 +98,144 @@ type Collection = {
  */
 type AnyObject = StandardSchemaV1<Record<string, any>>;
 type Output<T extends AnyObject> = StandardSchemaV1.InferOutput<T>;
-type Input<T extends AnyObject> = StandardSchemaV1.InferInput<T>;
+type CollectionDef<T extends Document = Document, Id extends string = string> = {
+  readonly "~docType": T;
+  readonly "~idType": Id;
+  schema: AnyObject;
+  getId: (data: T) => Id;
+};
+/**
+ * Helper function to create a collection definition with proper type inference.
+ * This captures the schema output type directly as the document type.
+ *
+ * @example
+ * ```ts
+ * const store = createStore({
+ *   users: define(userSchema, (data) => data.id),
+ * });
+ * ```
+ */
+declare function define<S extends AnyObject, Id extends string = string>(schema: S, getId: (data: Output<S>) => Id): CollectionDef<Output<S>, Id>;
+/**
+ * Extract the document type from a CollectionDef
+ */
+type DocType<C extends CollectionDef> = C["~docType"];
+/**
+ * Extract the ID type from a CollectionDef
+ */
+type IdType<C extends CollectionDef> = C["~idType"];
+/**
+ * Configuration for all collections in a store.
+ * All collection definitions must be created using the `collection()` helper.
+ *
+ * Uses `any` for type parameters to allow any CollectionDef to be stored,
+ * while still preserving specific types through inference in createStore.
+ */
+type StoreConfig = Record<string, CollectionDef<any, any>>;
+/**
+ * Valid collection name from a store config
+ */
+type CollectionName<T extends StoreConfig> = keyof T & string;
+//#endregion
+//#region lib/store/types.d.ts
+type StoreChangeEvent<T extends StoreConfig> = { [K in keyof T]?: true };
 //#endregion
 //#region lib/store/store.d.ts
-type CollectionConfig<T extends AnyObject> = {
-  schema: T;
-  keyPath: keyof Output<T> & string;
+type TransactionAPI<T extends StoreConfig> = {
+  get<N extends CollectionName<T>>(collection: N, id: IdType<T[N]>): DocType<T[N]> | undefined;
+  list<N extends CollectionName<T>>(collection: N): DocType<T[N]>[];
+  put<N extends CollectionName<T>>(collection: N, data: DocType<T[N]>): DocType<T[N]>;
+  patch<N extends CollectionName<T>>(collection: N, id: IdType<T[N]>, data: Partial<DocType<T[N]>>): DocType<T[N]>;
+  remove<N extends CollectionName<T>>(collection: N, id: IdType<T[N]>): void;
 };
-type StoreSnapshot = {
-  clock: Clock;
-  collections: Record<string, Collection>;
-  tombstones: Tombstones;
+declare class Store<T extends StoreConfig> {
+  #private;
+  constructor(config: T);
+  get<N extends CollectionName<T>>(collection: N, id: IdType<T[N]>): DocType<T[N]> | undefined;
+  list<N extends CollectionName<T>>(collection: N): DocType<T[N]>[];
+  put<N extends CollectionName<T>>(collection: N, data: DocType<T[N]>): DocType<T[N]>;
+  patch<N extends CollectionName<T>>(collection: N, id: IdType<T[N]>, data: Partial<DocType<T[N]>>): DocType<T[N]>;
+  remove<N extends CollectionName<T>>(collection: N, id: IdType<T[N]>): void;
+  subscribe(callback: (event: StoreChangeEvent<T>) => void): () => void;
+  getState(): StoreState;
+  merge(snapshot: StoreState): StoreChangeEvent<T>;
+  transact<R>(callback: (tx: TransactionAPI<T>) => R): R;
+}
+declare function createStore<T extends StoreConfig>(config: T): Store<T>;
+//#endregion
+//#region lib/middleware/idb-persister.d.ts
+interface IPersister {
+  init(): Promise<void>;
+  dispose(): Promise<void>;
+}
+type PersistenceOptions = {
+  key: string;
+  storeName?: string;
+  debounceMs?: number;
+  channelName?: string;
+  serialize?: (state: StoreState) => string;
+  deserialize?: (serialized: string) => StoreState;
 };
-type StoreChangeEvent<T extends Record<string, CollectionConfig<AnyObject>>> = { [K in keyof T]: {
-  type: "add";
-  collection: K;
-  id: DocumentId;
-  data: Output<T[K]["schema"]>;
-} | {
-  type: "update";
-  collection: K;
-  id: DocumentId;
-  data: Output<T[K]["schema"]>;
-} | {
-  type: "remove";
-  collection: K;
-  id: DocumentId;
-} | {
-  type: "merge";
-  collection: K;
-} }[keyof T];
-type StoreAPI<T extends Record<string, CollectionConfig<AnyObject>>> = {
-  add<K$1 extends keyof T & string>(collection: K$1, data: Input<T[K$1]["schema"]>): void;
-  get<K$1 extends keyof T & string>(collection: K$1, id: DocumentId): Output<T[K$1]["schema"]> | undefined;
-  getAll<K$1 extends keyof T & string>(collection: K$1, options?: {
-    where?: (item: Output<T[K$1]["schema"]>) => boolean;
-  }): Output<T[K$1]["schema"]>[];
-  update<K$1 extends keyof T & string>(collection: K$1, id: DocumentId, data: Partial<Input<T[K$1]["schema"]>>): void;
-  remove<K$1 extends keyof T & string>(collection: K$1, id: DocumentId): void;
-  getSnapshot(): StoreSnapshot;
-  merge(snapshot: StoreSnapshot): void;
-  onChange(listener: (event: StoreChangeEvent<T>) => void): () => void;
+declare class IdbPersister<T extends StoreConfig> implements IPersister {
+  #private;
+  constructor(store: Store<T>, options: PersistenceOptions);
+  init(): Promise<void>;
+  dispose(): Promise<void>;
+  subscribe(listener: (serialized: string) => void): () => void;
+}
+//#endregion
+//#region lib/middleware/debouncer.d.ts
+/**
+ * A simple debouncer that delays callback execution until after
+ * a specified time has elapsed since the last trigger.
+ */
+declare class Debouncer {
+  #private;
+  constructor(ms: number, callback: () => void | Promise<void>);
+  /**
+   * Trigger the debouncer. Resets the timer if already pending.
+   */
+  trigger(): void;
+  /**
+   * Cancel any pending execution without invoking the callback.
+   */
+  cancel(): void;
+  /**
+   * Immediately execute the callback if there's a pending timer,
+   * then cancel the timer. Does nothing if no timer is pending.
+   */
+  flush(): void | Promise<void>;
+  /**
+   * Check if there's a pending execution.
+   */
+  get pending(): boolean;
+}
+//#endregion
+//#region lib/middleware/broadcast-sync.d.ts
+type BroadcastSyncOptions = {
+  channelName: string;
+  onMessage: (state: StoreState) => void;
 };
-declare function createStore<T extends Record<string, CollectionConfig<AnyObject>>>(config: {
-  collections: T;
-}): StoreAPI<T>;
+/**
+ * Cross-tab synchronization via BroadcastChannel.
+ * Handles environments where BroadcastChannel is unavailable.
+ */
+declare class BroadcastSync {
+  #private;
+  constructor(options: BroadcastSyncOptions);
+  /**
+   * Broadcast state to other tabs. Does nothing if BroadcastChannel is unavailable.
+   */
+  broadcast(state: StoreState): void;
+  /**
+   * Close the BroadcastChannel and clean up resources.
+   */
+  close(): void;
+  /**
+   * Check if BroadcastChannel is available and connected.
+   */
+  get available(): boolean;
+}
 //#endregion
-export { type AnyObject, type CollectionConfig, type StoreAPI, type StoreChangeEvent, type StoreSnapshot, createStore };
+export { type AnyObject, Atom, AtomizedDocument, BroadcastSync, type BroadcastSyncOptions, Clock, Collection, type CollectionDef, CollectionState, Debouncer, type DocType, Document, type IPersister, type IdType, IdbPersister, KEYS, type PersistenceOptions, Stamp, Store, type StoreChangeEvent, type StoreConfig, type StoreState, Tombstones, type TransactionAPI, advanceClock, asStamp, atomize, define as collection, createReadLens, createStore, isAtom, isAtomizedDocument, isCollection, isCollectionState, isDeleted, makeStamp, mergeCollections, mergeDocs, mergeTombstones, pack, unpack };
 //# sourceMappingURL=index.d.ts.map