@tanstack/db 0.0.4 → 0.0.6

package/src/collection.ts

@@ -1,6 +1,6 @@
 import { Derived, Store, batch } from "@tanstack/store"
 import { withArrayChangeTracking, withChangeTracking } from "./proxy"
-import { getActiveTransaction } from "./transactions"
+import { Transaction, getActiveTransaction } from "./transactions"
 import { SortedMap } from "./SortedMap"
 import type {
   ChangeMessage,
@@ -10,7 +10,7 @@ import type {
   OptimisticChangeMessage,
   PendingMutation,
   StandardSchema,
-  Transaction,
+  Transaction as TransactionType,
 } from "./types"
 
 // Store collections in memory using Tanstack store
@@ -28,6 +28,19 @@ interface PendingSyncedTransaction<T extends object = Record<string, unknown>> {
   operations: Array<OptimisticChangeMessage<T>>
 }
 
+/**
+ * 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 function createCollection<T extends object = Record<string, unknown>>(
+  config: CollectionConfig<T>
+): Collection<T> {
+  return new Collection<T>(config)
+}
+
 /**
  * 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)
@@ -57,6 +70,10 @@ interface PendingSyncedTransaction<T extends object = Record<string, unknown>> {
 export function preloadCollection<T extends object = Record<string, unknown>>(
   config: CollectionConfig<T>
 ): Promise<Collection<T>> {
+  if (!config.id) {
+    throw new Error(`The id property is required for preloadCollection`)
+  }
+
   // If the collection is already fully loaded, return a resolved promise
   if (
     collectionsStore.state.has(config.id) &&
@@ -76,10 +93,14 @@ export function preloadCollection<T extends object = Record<string, unknown>>(
   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<T>({
           id: config.id,
+          getId: config.getId,
           sync: config.sync,
           schema: config.schema,
         })
@@ -100,6 +121,9 @@ export function preloadCollection<T extends object = Record<string, unknown>>(
 
   // Register a one-time listener for the first commit
   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()
@@ -145,7 +169,7 @@ export class SchemaValidationError extends Error {
 }
 
 export class Collection<T extends object = Record<string, unknown>> {
-  public transactions: Store<SortedMap<string, Transaction>>
+  public transactions: Store<SortedMap<string, TransactionType>>
   public optimisticOperations: Derived<Array<OptimisticChangeMessage<T>>>
   public derivedState: Derived<Map<string, T>>
   public derivedArray: Derived<Array<T>>
@@ -157,9 +181,6 @@ export class Collection<T extends object = Record<string, unknown>> {
   public config: CollectionConfig<T>
   private hasReceivedFirstCommit = false
 
-  // WeakMap to associate objects with their keys
-  public objectKeyMap = new WeakMap<object, string>()
-
   // Array to store one-time commit listeners
   private onFirstCommitCallbacks: Array<() => void> = []
 
@@ -172,7 +193,7 @@ export class Collection<T extends object = Record<string, unknown>> {
     this.onFirstCommitCallbacks.push(callback)
   }
 
-  public id = crypto.randomUUID()
+  public id = ``
 
   /**
    * Creates a new Collection instance
@@ -180,13 +201,24 @@ export class Collection<T extends object = Record<string, unknown>> {
    * @param config - Configuration object for the collection
    * @throws Error if sync config is missing
    */
-  constructor(config?: CollectionConfig<T>) {
-    if (!config?.sync) {
+  constructor(config: CollectionConfig<T>) {
+    // eslint-disable-next-line
+    if (!config) {
+      throw new Error(`Collection requires a config`)
+    }
+    if (config.id) {
+      this.id = config.id
+    } else {
+      this.id = crypto.randomUUID()
+    }
+
+    // eslint-disable-next-line
+    if (!config.sync) {
       throw new Error(`Collection requires a sync config`)
     }
 
     this.transactions = new Store(
-      new SortedMap<string, Transaction>(
+      new SortedMap<string, TransactionType>(
         (a, b) => a.createdAt.getTime() - b.createdAt.getTime()
       )
     )
@@ -232,11 +264,9 @@ export class Collection<T extends object = Record<string, unknown>> {
     this.derivedState = new Derived({
       fn: ({ currDepVals: [syncedData, operations] }) => {
         const combined = new Map<string, T>(syncedData)
-        const optimisticKeys = new Set<string>()
 
         // Apply the optimistic operations on top of the synced state.
         for (const operation of operations) {
-          optimisticKeys.add(operation.key)
           if (operation.isActive) {
             switch (operation.type) {
               case `insert`:
@@ -252,13 +282,6 @@ export class Collection<T extends object = Record<string, unknown>> {
           }
         }
 
-        // Update object => key mappings
-        optimisticKeys.forEach((key) => {
-          if (combined.has(key)) {
-            this.objectKeyMap.set(combined.get(key)!, key)
-          }
-        })
-
         return combined
       },
       deps: [this.syncedData, this.optimisticOperations],
@@ -353,7 +376,7 @@ export class Collection<T extends object = Record<string, unknown>> {
           operations: [],
         })
       },
-      write: (message: ChangeMessage<T>) => {
+      write: (messageWithoutKey: Omit<ChangeMessage<T>, `key`>) => {
         const pendingTransaction =
           this.pendingSyncedTransactions[
             this.pendingSyncedTransactions.length - 1
@@ -366,6 +389,30 @@ export class Collection<T extends object = Record<string, unknown>> {
             `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
+        )
+
+        // Check if an item with this ID already exists when inserting
+        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: ChangeMessage<T> = {
+          ...messageWithoutKey,
+          key,
+        }
         pendingTransaction.operations.push(message)
       },
       commit: () => {
@@ -399,11 +446,9 @@ export class Collection<T extends object = Record<string, unknown>> {
         ({ state }) => state === `persisting`
       )
     ) {
-      const keys = new Set<string>()
       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) {
@@ -443,13 +488,6 @@ export class Collection<T extends object = Record<string, unknown>> {
         }
       })
 
-      keys.forEach((key) => {
-        const curValue = this.state.get(key)
-        if (curValue) {
-          this.objectKeyMap.set(curValue, key)
-        }
-      })
-
       this.pendingSyncedTransactions = []
 
       // Call any registered one-time commit listeners
@@ -473,6 +511,29 @@ export class Collection<T extends object = Record<string, unknown>> {
     )
   }
 
+  private getKeyFromId(id: unknown): string {
+    if (typeof id === `undefined`) {
+      throw new Error(`id is undefined`)
+    }
+    if (typeof id === `string` && id.startsWith(`KEY::`)) {
+      return id
+    } else {
+      // if it's not a string, then it's some other
+      // primitive type and needs turned into a key.
+      return this.generateObjectKey(id, null)
+    }
+  }
+
+  public generateObjectKey(id: any, item: any): string {
+    if (typeof id === `undefined`) {
+      throw new Error(
+        `An object was created without a defined id: ${JSON.stringify(item)}`
+      )
+    }
+
+    return `KEY::${this.id}/${id}`
+  }
+
   private validateData(
     data: unknown,
     type: `insert` | `update`,
@@ -539,22 +600,11 @@ export class Collection<T extends object = Record<string, unknown>> {
     return result.value as T
   }
 
-  private generateKey(data: unknown): string {
-    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)}`
-  }
-
   /**
    * 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
@@ -570,27 +620,22 @@ export class Collection<T extends object = Record<string, unknown>> {
    * insert({ text: "Buy groceries" }, { key: "grocery-task" })
    */
   insert = (data: T | Array<T>, config?: InsertConfig) => {
-    const transaction = getActiveTransaction()
-    if (typeof transaction === `undefined`) {
-      throw `no transaction found when calling collection.insert`
+    const ambientTransaction = getActiveTransaction()
+
+    // If no ambient transaction exists, check for an onInsert handler early
+    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: Array<PendingMutation<T>> = []
 
     // Handle keys - convert to array if string, or generate if not provided
-    let keys: Array<string>
-    if (config?.key) {
-      const configKeys = Array.isArray(config.key) ? config.key : [config.key]
-      // If keys are provided, ensure we have the right number or allow sparse array
-      if (Array.isArray(config.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 {
-      // No keys provided, generate for all items
-      keys = items.map((item) => this.generateKey(item))
-    }
+    const keys: Array<unknown> = items.map((item) =>
+      this.generateObjectKey(this.config.getId(item), item)
+    )
 
     // Create mutations for each item
     items.forEach((item, index) => {
@@ -598,6 +643,12 @@ export class Collection<T extends object = Record<string, unknown>> {
       const validatedData = this.validateData(item, `insert`)
       const key = keys[index]!
 
+      // Check if an item with this ID already exists in the collection
+      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: PendingMutation<T> = {
         mutationId: crypto.randomUUID(),
         original: {},
@@ -615,14 +666,37 @@ export class Collection<T extends object = Record<string, unknown>> {
       mutations.push(mutation)
     })
 
-    transaction.applyMutations(mutations)
+    // If an ambient transaction exists, use it
+    if (ambientTransaction) {
+      ambientTransaction.applyMutations(mutations)
 
-    this.transactions.setState((sortedMap) => {
-      sortedMap.set(transaction.id, transaction)
-      return sortedMap
-    })
+      this.transactions.setState((sortedMap) => {
+        sortedMap.set(ambientTransaction.id, ambientTransaction)
+        return sortedMap
+      })
+
+      return ambientTransaction
+    } else {
+      // Create a new transaction with a mutation function that calls the onInsert handler
+      const directOpTransaction = new Transaction({
+        mutationFn: async (params) => {
+          // Call the onInsert handler with the transaction
+          return this.config.onInsert!(params)
+        },
+      })
+
+      // Apply mutations to the new transaction
+      directOpTransaction.applyMutations(mutations)
+      directOpTransaction.commit()
 
-    return transaction
+      // Add the transaction to the collection's transactions store
+      this.transactions.setState((sortedMap) => {
+        sortedMap.set(directOpTransaction.id, directOpTransaction)
+        return sortedMap
+      })
+
+      return directOpTransaction
+    }
   }
 
   /**
@@ -645,54 +719,75 @@ export class Collection<T extends object = Record<string, unknown>> {
    * update(todo, { metadata: { reason: "user update" } }, (draft) => { draft.text = "Updated text" })
    */
 
+  /**
+   * 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>(
-    item: TItem,
+    id: unknown,
     configOrCallback: ((draft: TItem) => void) | OperationConfig,
     maybeCallback?: (draft: TItem) => void
-  ): Transaction
+  ): TransactionType
 
   update<TItem extends object = T>(
-    items: Array<TItem>,
+    ids: Array<unknown>,
     configOrCallback: ((draft: Array<TItem>) => void) | OperationConfig,
     maybeCallback?: (draft: Array<TItem>) => void
-  ): Transaction
+  ): TransactionType
 
   update<TItem extends object = T>(
-    items: TItem | Array<TItem>,
+    ids: unknown | Array<unknown>,
     configOrCallback: ((draft: TItem | Array<TItem>) => void) | OperationConfig,
     maybeCallback?: (draft: TItem | Array<TItem>) => void
   ) {
-    if (typeof items === `undefined`) {
+    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 no ambient transaction exists, check for an onUpdate handler early
+    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 as unknown) !== null) {
-        const key = this.objectKeyMap.get(item)
-        if (key === undefined) {
-          throw new Error(`Object not found in collection`)
-        }
-        return key
+    // Get the current objects or empty objects if they don't exist
+    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`)
-    })
 
-    // Get the current objects or empty objects if they don't exist
-    const currentObjects = keys.map((key) => ({
-      ...(this.state.get(key) || {}),
-    })) as Array<TItem>
+      return item
+    }) as unknown as Array<TItem>
 
     let changesArray
     if (isArray) {
@@ -710,29 +805,44 @@ export class Collection<T extends object = Record<string, unknown>> {
     }
 
     // Create mutations for each object that has changes
-    const mutations: Array<PendingMutation<T>> = keys
-      .map((key, index) => {
-        const changes = changesArray[index]
+    const mutations: Array<PendingMutation<T>> = idsArray
+      .map((id, index) => {
+        const itemChanges = changesArray[index] // User-provided changes for this specific item
 
         // Skip items with no changes
-        if (!changes || Object.keys(changes).length === 0) {
+        if (!itemChanges || Object.keys(itemChanges).length === 0) {
           return null
         }
 
-        // Validate the changes for this item
-        const validatedData = this.validateData(changes, `update`, key)
+        const originalItem = currentObjects[index] as unknown as T
+        // Validate the user-provided changes for this item
+        const validatedUpdatePayload = this.validateData(
+          itemChanges,
+          `update`,
+          id
+        )
+
+        // Construct the full modified item by applying the validated update payload to the original item
+        const modifiedItem = { ...originalItem, ...validatedUpdatePayload }
+
+        // Check if the ID of the item is being changed
+        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) || {}) as Record<string, unknown>,
-          modified: {
-            ...(this.state.get(key) || {}),
-            ...validatedData,
-          } as Record<string, unknown>,
-          changes: validatedData as Record<string, unknown>,
-          key,
+          original: originalItem as Record<string, unknown>,
+          modified: modifiedItem as Record<string, unknown>,
+          changes: validatedUpdatePayload as Record<string, unknown>,
+          key: id,
           metadata: config.metadata as unknown,
-          syncMetadata: (this.syncedMetadata.state.get(key) || {}) as Record<
+          syncMetadata: (this.syncedMetadata.state.get(id) || {}) as Record<
             string,
             unknown
           >,
@@ -749,69 +859,83 @@ export class Collection<T extends object = Record<string, unknown>> {
       throw new Error(`No changes were made to any of the objects`)
     }
 
-    transaction.applyMutations(mutations)
+    // If an ambient transaction exists, use it
+    if (ambientTransaction) {
+      ambientTransaction.applyMutations(mutations)
+
+      this.transactions.setState((sortedMap) => {
+        sortedMap.set(ambientTransaction.id, ambientTransaction)
+        return sortedMap
+      })
+
+      return ambientTransaction
+    }
+
+    // No need to check for onUpdate handler here as we've already checked at the beginning
+
+    // Create a new transaction with a mutation function that calls the onUpdate handler
+    const directOpTransaction = new Transaction({
+      mutationFn: async (transaction) => {
+        // Call the onUpdate handler with the transaction
+        return this.config.onUpdate!(transaction)
+      },
+    })
+
+    // Apply mutations to the new transaction
+    directOpTransaction.applyMutations(mutations)
+    directOpTransaction.commit()
 
+    // Add the transaction to the collection's transactions store
     this.transactions.setState((sortedMap) => {
-      sortedMap.set(transaction.id, transaction)
+      sortedMap.set(directOpTransaction.id, directOpTransaction)
       return sortedMap
     })
 
-    return transaction
+    return directOpTransaction
   }
 
   /**
    * 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,
+    ids: Array<string> | string,
     config?: OperationConfig
-  ) => {
-    const transaction = getActiveTransaction()
-    if (typeof transaction === `undefined`) {
-      throw `no transaction found when calling collection.delete`
+  ): TransactionType => {
+    const ambientTransaction = getActiveTransaction()
+
+    // If no ambient transaction exists, check for an onDelete handler early
+    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: Array<PendingMutation<T>> = []
 
-    for (const item of itemsArray) {
-      let key: string
-      if (typeof item === `object` && (item as unknown) !== null) {
-        const objectKey = this.objectKeyMap.get(item)
-        if (objectKey === undefined) {
-          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: PendingMutation<T> = {
         mutationId: crypto.randomUUID(),
-        original: (this.state.get(key) || {}) as Record<string, unknown>,
-        modified: { _deleted: true },
-        changes: { _deleted: true },
-        key,
+        original: (this.state.get(id) || {}) as Record<string, unknown>,
+        modified: (this.state.get(id) || {}) as Record<string, unknown>,
+        changes: (this.state.get(id) || {}) as Record<string, unknown>,
+        key: id,
         metadata: config?.metadata as unknown,
-        syncMetadata: (this.syncedMetadata.state.get(key) || {}) as Record<
+        syncMetadata: (this.syncedMetadata.state.get(id) || {}) as Record<
           string,
           unknown
         >,
@@ -824,22 +948,38 @@ export class Collection<T extends object = Record<string, unknown>> {
       mutations.push(mutation)
     }
 
-    // Delete object => key mapping.
-    mutations.forEach((mutation) => {
-      const curValue = this.state.get(mutation.key)
-      if (curValue) {
-        this.objectKeyMap.delete(curValue)
-      }
+    // If an ambient transaction exists, use it
+    if (ambientTransaction) {
+      ambientTransaction.applyMutations(mutations)
+
+      this.transactions.setState((sortedMap) => {
+        sortedMap.set(ambientTransaction.id, ambientTransaction)
+        return sortedMap
+      })
+
+      return ambientTransaction
+    }
+
+    // Create a new transaction with a mutation function that calls the onDelete handler
+    const directOpTransaction = new Transaction({
+      autoCommit: true,
+      mutationFn: async (transaction) => {
+        // Call the onDelete handler with the transaction
+        return this.config.onDelete!(transaction)
+      },
     })
 
-    transaction.applyMutations(mutations)
+    // Apply mutations to the new transaction
+    directOpTransaction.applyMutations(mutations)
+    directOpTransaction.commit()
 
+    // Add the transaction to the collection's transactions store
     this.transactions.setState((sortedMap) => {
-      sortedMap.set(transaction.id, transaction)
+      sortedMap.set(directOpTransaction.id, directOpTransaction)
       return sortedMap
     })
 
-    return transaction
+    return directOpTransaction
   }
 
   /**