@byearlybird/starling 0.17.3 → 0.19.0

package/README.md

@@ -10,6 +10,8 @@ Starling is a CRDT (conflict-free replicated data type) library that provides au
 npm install @byearlybird/starling
 # or
 pnpm add @byearlybird/starling
+# or
+bun add @byearlybird/starling
 ```
 
 Requires TypeScript 5 or higher.
@@ -17,20 +19,14 @@ Requires TypeScript 5 or higher.
 ## Quick Example
 
 ```typescript
-import { createStore, collection } from "@byearlybird/starling";
-import { z } from "zod";
-
-const userSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-});
+import { createStore } from "@byearlybird/starling";
 
 const store = createStore({
-  users: collection(userSchema, (data) => data.id),
+  users: (data: { id: string; name: string }) => data.id,
 });
 
-store.put("users", { id: "1", name: "Alice" });
-const user = store.get("users", "1"); // { id: "1", name: "Alice" }
+store.users.put({ id: "1", name: "Alice" });
+const user = store.users.get("1"); // { id: "1", name: "Alice" }
 ```
 
 ## Features
@@ -39,7 +35,6 @@ const user = store.get("users", "1"); // { id: "1", name: "Alice" }
 - **Fast and synchronous**: All operations are in-memory and synchronous
 - **Framework agnostic**: Works with React, Vue, Svelte, or vanilla JS
 - **Type-safe**: Full TypeScript support with type inference
-- **Schema validation**: Works with Zod, Valibot, ArkType, and more
 - **Merge snapshots**: Sync data between devices or users easily
 - **Change events**: Listen to data changes and integrate with your reactive system
 
@@ -47,28 +42,17 @@ const user = store.get("users", "1"); // { id: "1", name: "Alice" }
 
 ### Creating a Store
 
-A store holds one or more collections. Each collection has a schema that defines what data it can store.
+A store holds one or more collections. Each collection is defined by a function that extracts the document ID.
 
 ```typescript
-import { createStore, collection } from "@byearlybird/starling";
-import { z } from "zod";
+import { createStore } from "@byearlybird/starling";
+
+type User = { id: string; name: string; email?: string };
+type Note = { id: string; content: string };
 
 const store = createStore({
-  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,
-  ),
+  users: (data: User) => data.id,
+  notes: (data: Note) => data.id,
 });
 ```
 
@@ -77,7 +61,7 @@ const store = createStore({
 Add new items to a collection using `put()`:
 
 ```typescript
-store.put("users", {
+store.users.put({
   id: "1",
   name: "Alice",
   email: "alice@example.com",
@@ -88,8 +72,8 @@ 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" });
+  tx.users.put({ id: "1", name: "Alice", email: "alice@example.com" });
+  tx.notes.put({ id: "n1", content: "Hello" });
 });
 ```
 
@@ -98,7 +82,7 @@ store.transact((tx) => {
 Update existing items using `patch()`:
 
 ```typescript
-store.patch("users", "1", {
+store.users.patch("1", {
   email: "newemail@example.com",
 });
 ```
@@ -108,7 +92,7 @@ store.patch("users", "1", {
 Remove items using `remove()`:
 
 ```typescript
-store.remove("users", "1");
+store.users.remove("1");
 ```
 
 ### Reading Data
@@ -117,10 +101,13 @@ Read data directly from the store:
 
 ```typescript
 // Get a single item
-const user = store.get("users", "1");
+const user = store.users.get("1");
 
 // Get all items as an array
-const allUsers = store.list("users");
+const allUsers = store.users.list();
+
+// Filter with a where clause
+const admins = store.users.list({ where: (u) => u.role === "admin" });
 
 // You can easily derive other operations:
 const userIds = allUsers.map((u) => u.id);
@@ -132,15 +119,9 @@ const hasUser = allUsers.some((u) => u.id === "1");
 Subscribe to changes with `subscribe()`:
 
 ```typescript
-// 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.
-});
-
-// Or subscribe to all changes
-store.subscribe((event) => {
+// Subscribe to all changes
+const unsubscribe = store.subscribe((event) => {
+  // event is e.g. { users: true } or { users: true, notes: true }
   console.log("Store changed:", event);
 });
 
@@ -181,14 +162,16 @@ function useUsers() {
   const queryClient = useQueryClient();
 
   useEffect(() => {
-    return store.subscribe(["users"], () => {
-      queryClient.invalidateQueries({ queryKey: ["users"] });
+    return store.subscribe((event) => {
+      if ("users" in event) {
+        queryClient.invalidateQueries({ queryKey: ["users"] });
+      }
     });
   }, []);
 
   return useQuery({
     queryKey: ["users"],
-    queryFn: () => store.list("users"),
+    queryFn: () => store.users.list(),
   });
 }
 ```
@@ -200,8 +183,11 @@ import { useSyncExternalStore } from "react";
 
 function useUsers() {
   return useSyncExternalStore(
-    (callback) => store.subscribe(["users"], () => callback()),
-    () => store.list("users"),
+    (callback) =>
+      store.subscribe((event) => {
+        if ("users" in event) callback();
+      }),
+    () => store.users.list(),
   );
 }
 ```
@@ -211,9 +197,11 @@ function useUsers() {
 ```typescript
 import { writable } from "svelte/store";
 
-const users = writable(store.list("users"));
-store.subscribe(["users"], () => {
-  users.set(store.list("users"));
+const users = writable(store.users.list());
+store.subscribe((event) => {
+  if ("users" in event) {
+    users.set(store.users.list());
+  }
 });
 ```
 
@@ -222,55 +210,36 @@ store.subscribe(["users"], () => {
 ```typescript
 import { ref } from "vue";
 
-const users = ref(store.list("users"));
-store.subscribe(["users"], () => {
-  users.value = store.list("users");
+const users = ref(store.users.list());
+store.subscribe((event) => {
+  if ("users" in event) {
+    users.value = store.users.list();
+  }
 });
 ```
 
-## Schema Support
-
-Starling works with any library that follows the [Standard Schema](https://github.com/standard-schema/spec) specification. This includes:
-
-- **Zod** - Most popular schema library
-- **Valibot** - Lightweight alternative
-- **ArkType** - TypeScript-first schemas
-
-You can use any of these to define your data shapes. Starling will validate your data and give you full TypeScript types.
-
-```typescript
-import { z } from "zod";
-// or
-import * as v from "valibot";
-// or
-import { type } from "arktype";
-
-// All of these work the same way
-const schema = z.object({ id: z.string(), name: z.string() });
-// or
-const schema = v.object({ id: v.string(), name: v.string() });
-// or
-const schema = type({ id: "string", name: "string" });
-```
-
 ## API Overview
 
 ### Main Export
 
 - `createStore(config)` - Creates a new store with collections
 
+### Collection Methods
+
+Each collection is accessed as a property on the store (e.g., `store.users`):
+
+- `store.<collection>.get(id)` - Get a document by ID
+- `store.<collection>.list(options?)` - Get all documents as an array, with optional `where` filter
+- `store.<collection>.put(data)` - Insert or replace a document (upsert, revives tombstoned IDs)
+- `store.<collection>.patch(id, data)` - Partially update an existing document (throws if ID missing)
+- `store.<collection>.remove(id)` - Remove a document
+
 ### Store Methods
 
-- `get(collection, id)` - Get a document by ID from a collection
-- `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
+- `store.transact(callback)` - Execute operations atomically across collections. The `tx` object has the same collection properties (e.g., `tx.users.put(...)`)
+- `store.subscribe(callback)` - Subscribe to all collection changes
+- `store.getState()` - Get current store state as a snapshot
+- `store.merge(snapshot)` - Merge a snapshot into the store
 
 For full type definitions, see the TypeScript types exported from the package.
 
@@ -278,20 +247,19 @@ For full type definitions, see the TypeScript types exported from the package.
 
 - **`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
 # Install dependencies
-pnpm install
+bun install
 
 # Build the library
-pnpm run build
+bun run build
 
 # Run tests
-pnpm test
+bun test
 
 # Watch mode for development
-pnpm run dev
+bun run dev
 ```

package/dist/index.d.ts

@@ -1,209 +1,94 @@
 import { StandardSchemaV1 } from "@standard-schema/spec";
 
-//#region lib/core/clock.d.ts
+//#region lib/clock.d.ts
 type Clock = {
   ms: number;
   seq: number;
 };
 /**
- * Branded type for HLC timestamps.
- * Stamps are lexicographically sortable hex strings encoding (ms, seq, nonce).
+ * HLC timestamp.
+ * Lexicographically sortable string: `${ms}@${seq}@${deviceId}`.
+ * ms and seq are zero-padded hex; deviceId is appended as-is.
  */
-type Stamp = string & {
-  readonly __brand: "Stamp";
-};
+type Stamp = string;
 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;
+declare function makeStamp(ms: number, seq: number, deviceId: string): Stamp;
 //#endregion
-//#region lib/core/tombstone.d.ts
-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/types.d.ts
-declare const KEYS: {
-  readonly VAL: "~val";
-  readonly TS: "~ts";
-};
-/**
- * Base constraint for plain document shapes - any object with string keys.
- */
+//#region lib/crdt.d.ts
 type Document = Record<string, unknown>;
 type Atom<T> = {
-  [KEYS.VAL]: T;
-  [KEYS.TS]: Stamp;
+  "~v": T;
+  "~ts": string;
 };
-/**
- * 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>;
+type AtomizedDocument = Record<string, Atom<unknown>>;
+type Tombstones = Record<string, string>;
+type CollectionState = {
+  documents: Record<string, AtomizedDocument>;
   tombstones: Tombstones;
 };
 type StoreState = {
   clock: Clock;
-  collections: Record<string, CollectionState<Document>>;
+  collections: Record<string, CollectionState>;
+};
+type CollectionChangeEvent = {
+  put: string[];
+  patch: string[];
+  remove: string[];
 };
-/**
- * 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
-/**
- * Validates input data against a schema.
- * Accepts `unknown` input to allow safe validation of untyped data.
- * The schema's runtime validation will ensure type safety.
- */
-declare function validate<T extends StandardSchemaV1>(schema: T, input: unknown): StandardSchemaV1.InferOutput<T>;
-/**
- * Base type constraint for any standard schema object
- */
-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, S$1 extends AnyObject = AnyObject> = {
-  readonly "~docType": T;
-  readonly "~idType": Id;
-  readonly "~schemaType": S$1;
-  schema: AnyObject;
-  getId: (data: T) => Id;
+//#region lib/collection.d.ts
+type CollectionDef<Input = unknown, Output extends Document = Document, KeyPath extends keyof Output & string = string> = {
+  keyPath: KeyPath;
+  schema?: StandardSchemaV1<Input, Output>;
 };
-/**
- * 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$1 extends AnyObject, Id extends string = string>(schema: S$1, getId: (data: Output<S$1>) => Id): CollectionDef<Output<S$1>, Id, S$1>;
-/**
- * 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"];
-/**
- * Extract the input type from a CollectionDef's schema
- * This allows put() to accept partial data when schemas have defaults
- */
-type InputType<C extends CollectionDef> = C extends CollectionDef<any, any, infer S> ? Input<S> : never;
-/**
- * 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.
- */
+//#endregion
+//#region lib/store.d.ts
+type DocType<C> = C extends CollectionDef<any, infer T, any> ? T : never;
+type InputType<C> = C extends CollectionDef<infer I, any, any> ? I : never;
 type StoreConfig = Record<string, CollectionDef<any, 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 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: InputType<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 CollectionAPI<C extends CollectionDef> = {
+  get(id: string): DocType<C> | undefined;
+  list(options?: {
+    where?: (doc: DocType<C>) => boolean;
+  }): DocType<C>[];
+  put(data: InputType<C>): DocType<C>;
+  patch(id: string, data: Partial<DocType<C>>): DocType<C>;
+  remove(id: string): void;
 };
-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: InputType<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 StoreChangeEvent<T extends StoreConfig> = { [K in keyof T]?: CollectionChangeEvent };
+type TransactionAPI<T extends StoreConfig> = { [K in CollectionName<T>]: CollectionAPI<T[K]> };
+type Store<T extends StoreConfig> = { [K in CollectionName<T>]: CollectionAPI<T[K]> } & {
   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/store/operations.d.ts
-declare function doGet<T extends Document>(docs: Collection<T>, tombstones: Tombstones, id: string): T | undefined;
-declare function doList<T extends Document>(docs: Collection<T>, tombstones: Tombstones): T[];
-declare function doPut<T extends Document>(docs: Collection<T>, tombstones: Tombstones, data: T, stamp: Stamp, validateFn: (data: unknown) => T, getId: (data: T) => string): T;
-declare function doPatch<T extends Document>(docs: Collection<T>, id: string, data: Partial<T>, stamp: Stamp, validateFn: (data: unknown) => T): T;
-declare function doRemove(docs: Collection<Document>, tombstones: Tombstones, id: string, stamp: Stamp): void;
-declare function mergeState<T extends StoreConfig>(currentState: StoreState, snapshot: StoreState, config: T): StoreChangeEvent<T>;
+};
+type StringKeyOf<T> = { [K in keyof T & string]: T[K] extends string ? K : never }[keyof T & string];
+declare function createStore<T extends StoreConfig>(config: {
+  deviceId: string;
+  collections: T & { [K in keyof T & string]: T[K] extends {
+    schema: StandardSchemaV1<any, infer O>;
+  } ? {
+    keyPath: StringKeyOf<O>;
+  } : T[K] };
+}): Store<T>;
+declare function createStore<T extends Record<string, Document & {
+  keyPath?: never;
+}>>(config: {
+  deviceId: string;
+  collections: { [K in keyof T & string]: {
+    keyPath: StringKeyOf<T[K]>;
+  } };
+}): Store<{ [K in keyof T & string]: CollectionDef<T[K], T[K], string> }>;
 //#endregion
-//#region lib/persisters/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;
+//#region lib/query.d.ts
+type Query<R> = {
+  readonly result: R;
+  subscribe(cb: (result: R) => void): () => void;
+  dispose(): 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;
-}
+declare function createQuery<T extends StoreConfig, R>(store: Store<T>, predicate: (store: Store<T>) => R, dependencies: CollectionName<T>[]): Query<R>;
 //#endregion
-export { AnyObject, Atom, AtomizedDocument, Clock, Collection, CollectionDef, CollectionName, CollectionState, DocType, Document, IPersister, IdType, IdbPersister, Input, InputType, KEYS, Output, PersistenceOptions, Stamp, Store, StoreConfig, StoreState, Tombstones, TransactionAPI, advanceClock, asStamp, atomize, createReadLens, createStore, define, doGet, doList, doPatch, doPut, doRemove, isAtom, isAtomizedDocument, isCollection, isCollectionState, isDeleted, makeStamp, mergeCollections, mergeDocs, mergeState, mergeTombstones, pack, unpack, validate };
+export { type Clock, type CollectionAPI, type CollectionChangeEvent, type CollectionDef, type CollectionName, type CollectionState, type DocType, type Document, type InputType, type Query, type Store, type StoreChangeEvent, type StoreConfig, type StoreState, type Tombstones, type TransactionAPI, advanceClock, createQuery, createStore, makeStamp };
 //# sourceMappingURL=index.d.ts.map