@tanstack/db 0.0.4 → 0.0.6

package/dist/esm/collection.d.ts

@@ -1,7 +1,16 @@
 import { Derived, Store } from '@tanstack/store';
+import { Transaction } from './transactions.js';
 import { SortedMap } from './SortedMap.js';
-import { ChangeMessage, CollectionConfig, InsertConfig, OperationConfig, OptimisticChangeMessage, Transaction } from './types.js';
+import { ChangeMessage, CollectionConfig, InsertConfig, OperationConfig, OptimisticChangeMessage, Transaction as TransactionType } from './types.js';
 export declare const collectionsStore: Store<Map<string, Collection<any>>, (cb: Map<string, Collection<any>>) => Map<string, Collection<any>>>;
+/**
+ * Creates a new Collection instance with the given configuration
+ *
+ * @template T - The type of items in the collection
+ * @param config - Configuration for the collection, including id and sync
+ * @returns A new Collection instance
+ */
+export declare function createCollection<T extends object = Record<string, unknown>>(config: CollectionConfig<T>): Collection<T>;
 /**
  * Preloads a collection with the given configuration
  * Returns a promise that resolves once the sync tool has done its first commit (initial sync is finished)
@@ -44,7 +53,7 @@ export declare class SchemaValidationError extends Error {
     }>, message?: string);
 }
 export declare class Collection<T extends object = Record<string, unknown>> {
-    transactions: Store<SortedMap<string, Transaction>>;
+    transactions: Store<SortedMap<string, TransactionType>>;
     optimisticOperations: Derived<Array<OptimisticChangeMessage<T>>>;
     derivedState: Derived<Map<string, T>>;
     derivedArray: Derived<Array<T>>;
@@ -55,7 +64,6 @@ export declare class Collection<T extends object = Record<string, unknown>> {
     private syncedKeys;
     config: CollectionConfig<T>;
     private hasReceivedFirstCommit;
-    objectKeyMap: WeakMap<object, string>;
     private onFirstCommitCallbacks;
     /**
      * Register a callback to be executed on the next commit
@@ -63,27 +71,28 @@ export declare class Collection<T extends object = Record<string, unknown>> {
      * @param callback Function to call after the next commit
      */
     onFirstCommit(callback: () => void): void;
-    id: `${string}-${string}-${string}-${string}-${string}`;
+    id: string;
     /**
      * Creates a new Collection instance
      *
      * @param config - Configuration object for the collection
      * @throws Error if sync config is missing
      */
-    constructor(config?: CollectionConfig<T>);
+    constructor(config: CollectionConfig<T>);
     /**
      * Attempts to commit pending synced transactions if there are no active transactions
      * This method processes operations from pending transactions and applies them to the synced data
      */
     commitPendingTransactions: () => void;
     private ensureStandardSchema;
+    private getKeyFromId;
+    generateObjectKey(id: any, item: any): string;
     private validateData;
-    private generateKey;
     /**
      * Inserts one or more items into the collection
      * @param items - Single item or array of items to insert
      * @param config - Optional configuration including metadata and custom keys
-     * @returns A Transaction object representing the insert operation(s)
+     * @returns A TransactionType object representing the insert operation(s)
      * @throws {SchemaValidationError} If the data fails schema validation
      * @example
      * // Insert a single item
@@ -118,24 +127,43 @@ export declare class Collection<T extends object = Record<string, unknown>> {
      * // Update with metadata
      * update(todo, { metadata: { reason: "user update" } }, (draft) => { draft.text = "Updated text" })
      */
-    update<TItem extends object = T>(item: TItem, configOrCallback: ((draft: TItem) => void) | OperationConfig, maybeCallback?: (draft: TItem) => void): Transaction;
-    update<TItem extends object = T>(items: Array<TItem>, configOrCallback: ((draft: Array<TItem>) => void) | OperationConfig, maybeCallback?: (draft: Array<TItem>) => void): Transaction;
+    /**
+     * Updates one or more items in the collection using a callback function
+     * @param ids - Single ID or array of IDs to update
+     * @param configOrCallback - Either update configuration or update callback
+     * @param maybeCallback - Update callback if config was provided
+     * @returns A Transaction object representing the update operation(s)
+     * @throws {SchemaValidationError} If the updated data fails schema validation
+     * @example
+     * // Update a single item
+     * update("todo-1", (draft) => { draft.completed = true })
+     *
+     * // Update multiple items
+     * update(["todo-1", "todo-2"], (drafts) => {
+     *   drafts.forEach(draft => { draft.completed = true })
+     * })
+     *
+     * // Update with metadata
+     * update("todo-1", { metadata: { reason: "user update" } }, (draft) => { draft.text = "Updated text" })
+     */
+    update<TItem extends object = T>(id: unknown, configOrCallback: ((draft: TItem) => void) | OperationConfig, maybeCallback?: (draft: TItem) => void): TransactionType;
+    update<TItem extends object = T>(ids: Array<unknown>, configOrCallback: ((draft: Array<TItem>) => void) | OperationConfig, maybeCallback?: (draft: Array<TItem>) => void): TransactionType;
     /**
      * Deletes one or more items from the collection
-     * @param items - Single item/key or array of items/keys to delete
+     * @param ids - Single ID or array of IDs to delete
      * @param config - Optional configuration including metadata
-     * @returns A Transaction object representing the delete operation(s)
+     * @returns A TransactionType object representing the delete operation(s)
      * @example
      * // Delete a single item
-     * delete(todo)
+     * delete("todo-1")
      *
      * // Delete multiple items
-     * delete([todo1, todo2])
+     * delete(["todo-1", "todo-2"])
      *
      * // Delete with metadata
-     * delete(todo, { metadata: { reason: "completed" } })
+     * delete("todo-1", { metadata: { reason: "completed" } })
      */
-    delete: (items: Array<T | string> | T | string, config?: OperationConfig) => Transaction;
+    delete: (ids: Array<string> | string, config?: OperationConfig) => TransactionType;
     /**
      * Gets the current state of the collection as a Map
      *

package/dist/esm/collection.js

@@ -1,10 +1,16 @@
 import { Store, batch, Derived } from "@tanstack/store";
 import { withArrayChangeTracking, withChangeTracking } from "./proxy.js";
-import { getActiveTransaction } from "./transactions.js";
+import { getActiveTransaction, Transaction } from "./transactions.js";
 import { SortedMap } from "./SortedMap.js";
 const collectionsStore = new Store(/* @__PURE__ */ new Map());
 const loadingCollections = /* @__PURE__ */ new Map();
+function createCollection(config) {
+  return new Collection(config);
+}
 function preloadCollection(config) {
+  if (!config.id) {
+    throw new Error(`The id property is required for preloadCollection`);
+  }
   if (collectionsStore.state.has(config.id) && !loadingCollections.has(config.id)) {
     return Promise.resolve(
       collectionsStore.state.get(config.id)
@@ -16,10 +22,14 @@ function preloadCollection(config) {
   if (!collectionsStore.state.has(config.id)) {
     collectionsStore.setState((prev) => {
       const next = new Map(prev);
+      if (!config.id) {
+        throw new Error(`The id property is required for preloadCollection`);
+      }
       next.set(
         config.id,
         new Collection({
           id: config.id,
+          getId: config.getId,
           sync: config.sync,
           schema: config.schema
         })
@@ -35,6 +45,9 @@ function preloadCollection(config) {
     };
   });
   collection.onFirstCommit(() => {
+    if (!config.id) {
+      throw new Error(`The id property is required for preloadCollection`);
+    }
     if (loadingCollections.has(config.id)) {
       loadingCollections.delete(config.id);
       resolveFirstCommit();
@@ -68,18 +81,15 @@ class Collection {
     this.pendingSyncedTransactions = [];
     this.syncedKeys = /* @__PURE__ */ new Set();
     this.hasReceivedFirstCommit = false;
-    this.objectKeyMap = /* @__PURE__ */ new WeakMap();
     this.onFirstCommitCallbacks = [];
-    this.id = crypto.randomUUID();
+    this.id = ``;
     this.commitPendingTransactions = () => {
       if (!Array.from(this.transactions.state.values()).some(
         ({ state }) => state === `persisting`
       )) {
-        const keys = /* @__PURE__ */ new Set();
         batch(() => {
           for (const transaction of this.pendingSyncedTransactions) {
             for (const operation of transaction.operations) {
-              keys.add(operation.key);
               this.syncedKeys.add(operation.key);
               this.syncedMetadata.setState((prevData) => {
                 switch (operation.type) {
@@ -118,12 +128,6 @@ class Collection {
             }
           }
         });
-        keys.forEach((key) => {
-          const curValue = this.state.get(key);
-          if (curValue) {
-            this.objectKeyMap.set(curValue, key);
-          }
-        });
         this.pendingSyncedTransactions = [];
         if (!this.hasReceivedFirstCommit) {
           this.hasReceivedFirstCommit = true;
@@ -134,26 +138,25 @@ class Collection {
       }
     };
     this.insert = (data, config2) => {
-      const transaction = getActiveTransaction();
-      if (typeof transaction === `undefined`) {
-        throw `no transaction found when calling collection.insert`;
+      const ambientTransaction = getActiveTransaction();
+      if (!ambientTransaction && !this.config.onInsert) {
+        throw new Error(
+          `Collection.insert called directly (not within an explicit transaction) but no 'onInsert' handler is configured.`
+        );
       }
       const items = Array.isArray(data) ? data : [data];
       const mutations = [];
-      let keys;
-      if (config2 == null ? void 0 : config2.key) {
-        const configKeys = Array.isArray(config2.key) ? config2.key : [config2.key];
-        if (Array.isArray(config2.key) && configKeys.length > items.length) {
-          throw new Error(`More keys provided than items to insert`);
-        }
-        keys = items.map((_, i) => configKeys[i] ?? this.generateKey(items[i]));
-      } else {
-        keys = items.map((item) => this.generateKey(item));
-      }
+      const keys = items.map(
+        (item) => this.generateObjectKey(this.config.getId(item), item)
+      );
       items.forEach((item, index) => {
         var _a, _b;
         const validatedData = this.validateData(item, `insert`);
         const key = keys[index];
+        const id = this.config.getId(item);
+        if (this.state.has(this.getKeyFromId(id))) {
+          throw `Cannot insert document with ID "${id}" because it already exists in the collection`;
+        }
         const mutation = {
           mutationId: crypto.randomUUID(),
           original: {},
@@ -169,45 +172,48 @@ class Collection {
         };
         mutations.push(mutation);
       });
-      transaction.applyMutations(mutations);
-      this.transactions.setState((sortedMap) => {
-        sortedMap.set(transaction.id, transaction);
-        return sortedMap;
-      });
-      return transaction;
+      if (ambientTransaction) {
+        ambientTransaction.applyMutations(mutations);
+        this.transactions.setState((sortedMap) => {
+          sortedMap.set(ambientTransaction.id, ambientTransaction);
+          return sortedMap;
+        });
+        return ambientTransaction;
+      } else {
+        const directOpTransaction = new Transaction({
+          mutationFn: async (params) => {
+            return this.config.onInsert(params);
+          }
+        });
+        directOpTransaction.applyMutations(mutations);
+        directOpTransaction.commit();
+        this.transactions.setState((sortedMap) => {
+          sortedMap.set(directOpTransaction.id, directOpTransaction);
+          return sortedMap;
+        });
+        return directOpTransaction;
+      }
     };
-    this.delete = (items, config2) => {
-      const transaction = getActiveTransaction();
-      if (typeof transaction === `undefined`) {
-        throw `no transaction found when calling collection.delete`;
+    this.delete = (ids, config2) => {
+      const ambientTransaction = getActiveTransaction();
+      if (!ambientTransaction && !this.config.onDelete) {
+        throw new Error(
+          `Collection.delete called directly (not within an explicit transaction) but no 'onDelete' handler is configured.`
+        );
       }
-      const itemsArray = Array.isArray(items) ? items : [items];
+      const idsArray = (Array.isArray(ids) ? ids : [ids]).map(
+        (id) => this.getKeyFromId(id)
+      );
       const mutations = [];
-      for (const item of itemsArray) {
-        let key;
-        if (typeof item === `object` && item !== null) {
-          const objectKey = this.objectKeyMap.get(item);
-          if (objectKey === void 0) {
-            throw new Error(
-              `Object not found in collection: ${JSON.stringify(item)}`
-            );
-          }
-          key = objectKey;
-        } else if (typeof item === `string`) {
-          key = item;
-        } else {
-          throw new Error(
-            `Invalid item type for delete - must be an object or string key`
-          );
-        }
+      for (const id of idsArray) {
         const mutation = {
           mutationId: crypto.randomUUID(),
-          original: this.state.get(key) || {},
-          modified: { _deleted: true },
-          changes: { _deleted: true },
-          key,
+          original: this.state.get(id) || {},
+          modified: this.state.get(id) || {},
+          changes: this.state.get(id) || {},
+          key: id,
           metadata: config2 == null ? void 0 : config2.metadata,
-          syncMetadata: this.syncedMetadata.state.get(key) || {},
+          syncMetadata: this.syncedMetadata.state.get(id) || {},
           type: `delete`,
           createdAt: /* @__PURE__ */ new Date(),
           updatedAt: /* @__PURE__ */ new Date(),
@@ -215,20 +221,37 @@ class Collection {
         };
         mutations.push(mutation);
       }
-      mutations.forEach((mutation) => {
-        const curValue = this.state.get(mutation.key);
-        if (curValue) {
-          this.objectKeyMap.delete(curValue);
+      if (ambientTransaction) {
+        ambientTransaction.applyMutations(mutations);
+        this.transactions.setState((sortedMap) => {
+          sortedMap.set(ambientTransaction.id, ambientTransaction);
+          return sortedMap;
+        });
+        return ambientTransaction;
+      }
+      const directOpTransaction = new Transaction({
+        autoCommit: true,
+        mutationFn: async (transaction) => {
+          return this.config.onDelete(transaction);
         }
       });
-      transaction.applyMutations(mutations);
+      directOpTransaction.applyMutations(mutations);
+      directOpTransaction.commit();
       this.transactions.setState((sortedMap) => {
-        sortedMap.set(transaction.id, transaction);
+        sortedMap.set(directOpTransaction.id, directOpTransaction);
         return sortedMap;
       });
-      return transaction;
+      return directOpTransaction;
     };
-    if (!(config == null ? void 0 : config.sync)) {
+    if (!config) {
+      throw new Error(`Collection requires a config`);
+    }
+    if (config.id) {
+      this.id = config.id;
+    } else {
+      this.id = crypto.randomUUID();
+    }
+    if (!config.sync) {
       throw new Error(`Collection requires a sync config`);
     }
     this.transactions = new Store(
@@ -263,9 +286,7 @@ class Collection {
     this.derivedState = new Derived({
       fn: ({ currDepVals: [syncedData, operations] }) => {
         const combined = new Map(syncedData);
-        const optimisticKeys = /* @__PURE__ */ new Set();
         for (const operation of operations) {
-          optimisticKeys.add(operation.key);
           if (operation.isActive) {
             switch (operation.type) {
               case `insert`:
@@ -280,11 +301,6 @@ class Collection {
             }
           }
         }
-        optimisticKeys.forEach((key) => {
-          if (combined.has(key)) {
-            this.objectKeyMap.set(combined.get(key), key);
-          }
-        });
         return combined;
       },
       deps: [this.syncedData, this.optimisticOperations]
@@ -361,7 +377,7 @@ class Collection {
           operations: []
         });
       },
-      write: (message) => {
+      write: (messageWithoutKey) => {
         const pendingTransaction = this.pendingSyncedTransactions[this.pendingSyncedTransactions.length - 1];
         if (!pendingTransaction) {
           throw new Error(`No pending sync transaction to write to`);
@@ -371,6 +387,24 @@ class Collection {
             `The pending sync transaction is already committed, you can't still write to it.`
           );
         }
+        const key = this.generateObjectKey(
+          this.config.getId(messageWithoutKey.value),
+          messageWithoutKey.value
+        );
+        if (messageWithoutKey.type === `insert`) {
+          if (this.syncedData.state.has(key) && !pendingTransaction.operations.some(
+            (op) => op.key === key && op.type === `delete`
+          )) {
+            const id = this.config.getId(messageWithoutKey.value);
+            throw new Error(
+              `Cannot insert document with ID "${id}" from sync because it already exists in the collection "${this.id}"`
+            );
+          }
+        }
+        const message = {
+          ...messageWithoutKey,
+          key
+        };
         pendingTransaction.operations.push(message);
       },
       commit: () => {
@@ -404,6 +438,24 @@ class Collection {
       `Schema must either implement the standard-schema interface or be a Zod schema`
     );
   }
+  getKeyFromId(id) {
+    if (typeof id === `undefined`) {
+      throw new Error(`id is undefined`);
+    }
+    if (typeof id === `string` && id.startsWith(`KEY::`)) {
+      return id;
+    } else {
+      return this.generateObjectKey(id, null);
+    }
+  }
+  generateObjectKey(id, item) {
+    if (typeof id === `undefined`) {
+      throw new Error(
+        `An object was created without a defined id: ${JSON.stringify(item)}`
+      );
+    }
+    return `KEY::${this.id}/${id}`;
+  }
   validateData(data, type, key) {
     if (!this.config.schema) return data;
     const standardSchema = this.ensureStandardSchema(this.config.schema);
@@ -444,39 +496,31 @@ class Collection {
     }
     return result.value;
   }
-  generateKey(data) {
-    const str = JSON.stringify(data);
-    let h = 0;
-    for (let i = 0; i < str.length; i++) {
-      h = Math.imul(31, h) + str.charCodeAt(i) | 0;
-    }
-    return `${this.id}/${Math.abs(h).toString(36)}`;
-  }
-  update(items, configOrCallback, maybeCallback) {
-    if (typeof items === `undefined`) {
+  update(ids, configOrCallback, maybeCallback) {
+    if (typeof ids === `undefined`) {
       throw new Error(`The first argument to update is missing`);
     }
-    const transaction = getActiveTransaction();
-    if (typeof transaction === `undefined`) {
-      throw `no transaction found when calling collection.update`;
+    const ambientTransaction = getActiveTransaction();
+    if (!ambientTransaction && !this.config.onUpdate) {
+      throw new Error(
+        `Collection.update called directly (not within an explicit transaction) but no 'onUpdate' handler is configured.`
+      );
     }
-    const isArray = Array.isArray(items);
-    const itemsArray = Array.isArray(items) ? items : [items];
+    const isArray = Array.isArray(ids);
+    const idsArray = (Array.isArray(ids) ? ids : [ids]).map(
+      (id) => this.getKeyFromId(id)
+    );
     const callback = typeof configOrCallback === `function` ? configOrCallback : maybeCallback;
     const config = typeof configOrCallback === `function` ? {} : configOrCallback;
-    const keys = itemsArray.map((item) => {
-      if (typeof item === `object` && item !== null) {
-        const key = this.objectKeyMap.get(item);
-        if (key === void 0) {
-          throw new Error(`Object not found in collection`);
-        }
-        return key;
+    const currentObjects = idsArray.map((id) => {
+      const item = this.state.get(id);
+      if (!item) {
+        throw new Error(
+          `The id "${id}" was passed to update but an object for this ID was not found in the collection`
+        );
       }
-      throw new Error(`Invalid item type for update - must be an object`);
+      return item;
     });
-    const currentObjects = keys.map((key) => ({
-      ...this.state.get(key) || {}
-    }));
     let changesArray;
     if (isArray) {
       changesArray = withArrayChangeTracking(
@@ -490,23 +534,33 @@ class Collection {
       );
       changesArray = [result];
     }
-    const mutations = keys.map((key, index) => {
-      const changes = changesArray[index];
-      if (!changes || Object.keys(changes).length === 0) {
+    const mutations = idsArray.map((id, index) => {
+      const itemChanges = changesArray[index];
+      if (!itemChanges || Object.keys(itemChanges).length === 0) {
         return null;
       }
-      const validatedData = this.validateData(changes, `update`, key);
+      const originalItem = currentObjects[index];
+      const validatedUpdatePayload = this.validateData(
+        itemChanges,
+        `update`,
+        id
+      );
+      const modifiedItem = { ...originalItem, ...validatedUpdatePayload };
+      const originalItemId = this.config.getId(originalItem);
+      const modifiedItemId = this.config.getId(modifiedItem);
+      if (originalItemId !== modifiedItemId) {
+        throw new Error(
+          `Updating the ID of an item is not allowed. Original ID: "${originalItemId}", Attempted new ID: "${modifiedItemId}". Please delete the old item and create a new one if an ID change is necessary.`
+        );
+      }
       return {
         mutationId: crypto.randomUUID(),
-        original: this.state.get(key) || {},
-        modified: {
-          ...this.state.get(key) || {},
-          ...validatedData
-        },
-        changes: validatedData,
-        key,
+        original: originalItem,
+        modified: modifiedItem,
+        changes: validatedUpdatePayload,
+        key: id,
         metadata: config.metadata,
-        syncMetadata: this.syncedMetadata.state.get(key) || {},
+        syncMetadata: this.syncedMetadata.state.get(id) || {},
         type: `update`,
         createdAt: /* @__PURE__ */ new Date(),
         updatedAt: /* @__PURE__ */ new Date(),
@@ -516,12 +570,26 @@ class Collection {
     if (mutations.length === 0) {
       throw new Error(`No changes were made to any of the objects`);
     }
-    transaction.applyMutations(mutations);
+    if (ambientTransaction) {
+      ambientTransaction.applyMutations(mutations);
+      this.transactions.setState((sortedMap) => {
+        sortedMap.set(ambientTransaction.id, ambientTransaction);
+        return sortedMap;
+      });
+      return ambientTransaction;
+    }
+    const directOpTransaction = new Transaction({
+      mutationFn: async (transaction) => {
+        return this.config.onUpdate(transaction);
+      }
+    });
+    directOpTransaction.applyMutations(mutations);
+    directOpTransaction.commit();
     this.transactions.setState((sortedMap) => {
-      sortedMap.set(transaction.id, transaction);
+      sortedMap.set(directOpTransaction.id, directOpTransaction);
       return sortedMap;
     });
-    return transaction;
+    return directOpTransaction;
   }
   /**
    * Gets the current state of the collection as a Map
@@ -600,6 +668,7 @@ export {
   Collection,
   SchemaValidationError,
   collectionsStore,
+  createCollection,
   preloadCollection
 };
 //# sourceMappingURL=collection.js.map