@tanstack/db 0.0.23 → 0.0.25

package/src/collection.ts

@@ -229,8 +229,9 @@ export class CollectionImpl<
   private hasReceivedFirstCommit = false
   private isCommittingSyncTransactions = false
 
-  // Array to store one-time commit listeners
-  private onFirstCommitCallbacks: Array<() => void> = []
+  // Array to store one-time ready listeners
+  private onFirstReadyCallbacks: Array<() => void> = []
+  private hasBeenReady = false
 
   // Event batching for preventing duplicate emissions during transaction flows
   private batchedEvents: Array<ChangeMessage<T, TKey>> = []
@@ -244,17 +245,66 @@ export class CollectionImpl<
   private syncCleanupFn: (() => void) | null = null
 
   /**
-   * Register a callback to be executed on the next commit
+   * Register a callback to be executed when the collection first becomes ready
    * Useful for preloading collections
-   * @param callback Function to call after the next commit
+   * @param callback Function to call when the collection first becomes ready
    * @example
-   * collection.onFirstCommit(() => {
-   *   console.log('Collection has received first data')
+   * collection.onFirstReady(() => {
+   *   console.log('Collection is ready for the first time')
    *   // Safe to access collection.state now
    * })
    */
-  public onFirstCommit(callback: () => void): void {
-    this.onFirstCommitCallbacks.push(callback)
+  public onFirstReady(callback: () => void): void {
+    // If already ready, call immediately
+    if (this.hasBeenReady) {
+      callback()
+      return
+    }
+
+    this.onFirstReadyCallbacks.push(callback)
+  }
+
+  /**
+   * Check if the collection is ready for use
+   * Returns true if the collection has been marked as ready by its sync implementation
+   * @returns true if the collection is ready, false otherwise
+   * @example
+   * if (collection.isReady()) {
+   *   console.log('Collection is ready, data is available')
+   *   // Safe to access collection.state
+   * } else {
+   *   console.log('Collection is still loading')
+   * }
+   */
+  public isReady(): boolean {
+    return this._status === `ready`
+  }
+
+  /**
+   * Mark the collection as ready for use
+   * This is called by sync implementations to explicitly signal that the collection is ready,
+   * providing a more intuitive alternative to using commits for readiness signaling
+   * @private - Should only be called by sync implementations
+   */
+  private markReady(): void {
+    // Can transition to ready from loading or initialCommit states
+    if (this._status === `loading` || this._status === `initialCommit`) {
+      this.setStatus(`ready`)
+
+      // Call any registered first ready callbacks (only on first time becoming ready)
+      if (!this.hasBeenReady) {
+        this.hasBeenReady = true
+
+        // Also mark as having received first commit for backwards compatibility
+        if (!this.hasReceivedFirstCommit) {
+          this.hasReceivedFirstCommit = true
+        }
+
+        const callbacks = [...this.onFirstReadyCallbacks]
+        this.onFirstReadyCallbacks = []
+        callbacks.forEach((callback) => callback())
+      }
+    }
   }
 
   public id = ``
@@ -302,7 +352,7 @@ export class CollectionImpl<
       Array<CollectionStatus>
     > = {
       idle: [`loading`, `error`, `cleaned-up`],
-      loading: [`initialCommit`, `error`, `cleaned-up`],
+      loading: [`initialCommit`, `ready`, `error`, `cleaned-up`],
       initialCommit: [`ready`, `error`, `cleaned-up`],
       ready: [`cleaned-up`, `error`],
       error: [`cleaned-up`, `idle`],
@@ -455,11 +505,9 @@ export class CollectionImpl<
           }
 
           this.commitPendingTransactions()
-
-          // Transition from initialCommit to ready after the first commit is complete
-          if (this._status === `initialCommit`) {
-            this.setStatus(`ready`)
-          }
+        },
+        markReady: () => {
+          this.markReady()
         },
       })
 
@@ -492,7 +540,7 @@ export class CollectionImpl<
       }
 
       // Register callback BEFORE starting sync to avoid race condition
-      this.onFirstCommit(() => {
+      this.onFirstReady(() => {
         resolve()
       })
 
@@ -555,7 +603,8 @@ export class CollectionImpl<
     this.pendingSyncedTransactions = []
     this.syncedKeys.clear()
     this.hasReceivedFirstCommit = false
-    this.onFirstCommitCallbacks = []
+    this.hasBeenReady = false
+    this.onFirstReadyCallbacks = []
     this.preloadPromise = null
     this.batchedEvents = []
     this.shouldBatchEvents = false
@@ -1184,8 +1233,8 @@ export class CollectionImpl<
       // Call any registered one-time commit listeners
       if (!this.hasReceivedFirstCommit) {
         this.hasReceivedFirstCommit = true
-        const callbacks = [...this.onFirstCommitCallbacks]
-        this.onFirstCommitCallbacks = []
+        const callbacks = [...this.onFirstReadyCallbacks]
+        this.onFirstReadyCallbacks = []
         callbacks.forEach((callback) => callback())
       }
     }
@@ -1812,14 +1861,14 @@ export class CollectionImpl<
    * @returns Promise that resolves to a Map containing all items in the collection
    */
   stateWhenReady(): Promise<Map<TKey, T>> {
-    // If we already have data or there are no loading collections, resolve immediately
-    if (this.size > 0 || this.hasReceivedFirstCommit === true) {
+    // If we already have data or collection is ready, resolve immediately
+    if (this.size > 0 || this.isReady()) {
       return Promise.resolve(this.state)
     }
 
-    // Otherwise, wait for the first commit
+    // Otherwise, wait for the collection to be ready
     return new Promise<Map<TKey, T>>((resolve) => {
-      this.onFirstCommit(() => {
+      this.onFirstReady(() => {
         resolve(this.state)
       })
     })
@@ -1841,14 +1890,14 @@ export class CollectionImpl<
    * @returns Promise that resolves to an Array containing all items in the collection
    */
   toArrayWhenReady(): Promise<Array<T>> {
-    // If we already have data or there are no loading collections, resolve immediately
-    if (this.size > 0 || this.hasReceivedFirstCommit === true) {
+    // If we already have data or collection is ready, resolve immediately
+    if (this.size > 0 || this.isReady()) {
       return Promise.resolve(this.toArray)
     }
 
-    // Otherwise, wait for the first commit
+    // Otherwise, wait for the collection to be ready
     return new Promise<Array<T>>((resolve) => {
-      this.onFirstCommit(() => {
+      this.onFirstReady(() => {
         resolve(this.toArray)
       })
     })

package/src/local-only.ts

@@ -240,7 +240,7 @@ function createLocalOnlySync<T extends object, TKey extends string | number>(
      * @returns Unsubscribe function (empty since no ongoing sync is needed)
      */
     sync: (params) => {
-      const { begin, write, commit } = params
+      const { begin, write, commit, markReady } = params
 
       // Capture sync functions for later use by confirmOperationsSync
       syncBegin = begin
@@ -259,6 +259,9 @@ function createLocalOnlySync<T extends object, TKey extends string | number>(
         commit()
       }
 
+      // Mark collection as ready since local-only collections are immediately ready
+      markReady()
+
       // Return empty unsubscribe function - no ongoing sync needed
       return () => {}
     },

package/src/local-storage.ts

@@ -586,7 +586,7 @@ function createLocalStorageSync<T extends object>(
 
   const syncConfig: SyncConfig<T> & { manualTrigger?: () => void } = {
     sync: (params: Parameters<SyncConfig<T>[`sync`]>[0]) => {
-      const { begin, write, commit } = params
+      const { begin, write, commit, markReady } = params
 
       // Store sync params for later use
       syncParams = params
@@ -608,6 +608,9 @@ function createLocalStorageSync<T extends object>(
         lastKnownData.set(key, storedItem)
       })
 
+      // Mark collection as ready after initial load
+      markReady()
+
       // Listen for storage events from other tabs
       const handleStorageEvent = (event: StorageEvent) => {
         // Only respond to changes to our specific key and from our storage

package/src/proxy.ts

@@ -40,10 +40,21 @@ interface ChangeTracker<T extends object> {
   copy_: T
   proxyCount: number
   assigned_: Record<string | symbol, boolean>
-  parent?: {
-    tracker: ChangeTracker<Record<string | symbol, unknown>>
-    prop: string | symbol
-  }
+  parent?:
+    | {
+        tracker: ChangeTracker<Record<string | symbol, unknown>>
+        prop: string | symbol
+      }
+    | {
+        tracker: ChangeTracker<Record<string | symbol, unknown>>
+        prop: string | symbol
+        updateMap: (newValue: unknown) => void
+      }
+    | {
+        tracker: ChangeTracker<Record<string | symbol, unknown>>
+        prop: unknown
+        updateSet: (newValue: unknown) => void
+      }
   target: T
 }
 
@@ -330,9 +341,18 @@ export function createChangeProxy<
     if (state.parent) {
       debugLog(`propagating change to parent`)
 
-      // Update parent's copy with this object's current state
-      state.parent.tracker.copy_[state.parent.prop] = state.copy_
-      state.parent.tracker.assigned_[state.parent.prop] = true
+      // Check if this is a special Map parent with updateMap function
+      if (`updateMap` in state.parent) {
+        // Use the special updateMap function for Maps
+        state.parent.updateMap(state.copy_)
+      } else if (`updateSet` in state.parent) {
+        // Use the special updateSet function for Sets
+        state.parent.updateSet(state.copy_)
+      } else {
+        // Update parent's copy with this object's current state
+        state.parent.tracker.copy_[state.parent.prop] = state.copy_
+        state.parent.tracker.assigned_[state.parent.prop] = true
+      }
 
       // Mark parent as changed
       markChanged(state.parent.tracker)
@@ -410,7 +430,7 @@ export function createChangeProxy<
   // Update parent status based on child changes
   function checkParentStatus(
     parentState: ChangeTracker<Record<string | symbol, unknown>>,
-    childProp: string | symbol
+    childProp: string | symbol | unknown
   ) {
     debugLog(`checkParentStatus called for child prop:`, childProp)
 
@@ -461,6 +481,30 @@ export function createChangeProxy<
 
         // If the value is a function, bind it to the ptarget
         if (typeof value === `function`) {
+          // For Array methods that modify the array
+          if (Array.isArray(ptarget)) {
+            const methodName = prop.toString()
+            const modifyingMethods = new Set([
+              `pop`,
+              `push`,
+              `shift`,
+              `unshift`,
+              `splice`,
+              `sort`,
+              `reverse`,
+              `fill`,
+              `copyWithin`,
+            ])
+
+            if (modifyingMethods.has(methodName)) {
+              return function (...args: Array<unknown>) {
+                const result = value.apply(changeTracker.copy_, args)
+                markChanged(changeTracker)
+                return result
+              }
+            }
+          }
+
           // For Map and Set methods that modify the collection
           if (ptarget instanceof Map || ptarget instanceof Set) {
             const methodName = prop.toString()
@@ -541,6 +585,28 @@ export function createChangeProxy<
                   // to track changes when the values are accessed and potentially modified
                   const originalIterator = result
 
+                  // For values() iterator on Maps, we need to create a value-to-key mapping
+                  const valueToKeyMap = new Map()
+                  if (methodName === `values` && ptarget instanceof Map) {
+                    // Build a mapping from value to key for reverse lookup
+                    // Use the copy_ (which is the current state) to build the mapping
+                    for (const [
+                      key,
+                      mapValue,
+                    ] of changeTracker.copy_.entries()) {
+                      valueToKeyMap.set(mapValue, key)
+                    }
+                  }
+
+                  // For Set iterators, we need to create an original-to-modified mapping
+                  const originalToModifiedMap = new Map()
+                  if (ptarget instanceof Set) {
+                    // Initialize with original values
+                    for (const setValue of changeTracker.copy_.values()) {
+                      originalToModifiedMap.set(setValue, setValue)
+                    }
+                  }
+
                   // Create a proxy for the iterator that will mark changes when next() is called
                   return {
                     next() {
@@ -563,15 +629,25 @@ export function createChangeProxy<
                             nextResult.value[1] &&
                             typeof nextResult.value[1] === `object`
                           ) {
+                            const mapKey = nextResult.value[0]
+                            // Create a special parent tracker that knows how to update the Map
+                            const mapParent = {
+                              tracker: changeTracker,
+                              prop: mapKey,
+                              updateMap: (newValue: unknown) => {
+                                // Update the Map in the copy
+                                if (changeTracker.copy_ instanceof Map) {
+                                  changeTracker.copy_.set(mapKey, newValue)
+                                }
+                              },
+                            }
+
                             // Create a proxy for the value and replace it in the result
                             const { proxy: valueProxy } =
-                              memoizedCreateChangeProxy(nextResult.value[1], {
-                                tracker: changeTracker,
-                                prop:
-                                  typeof nextResult.value[0] === `symbol`
-                                    ? nextResult.value[0]
-                                    : String(nextResult.value[0]),
-                              })
+                              memoizedCreateChangeProxy(
+                                nextResult.value[1],
+                                mapParent
+                              )
                             nextResult.value[1] = valueProxy
                           }
                         } else if (
@@ -584,16 +660,68 @@ export function createChangeProxy<
                             typeof nextResult.value === `object` &&
                             nextResult.value !== null
                           ) {
-                            // For Set, we need to track the whole object
-                            // For Map, we would need the key, but we don't have it here
-                            // So we'll use a symbol as a placeholder
-                            const tempKey = Symbol(`iterator-value`)
-                            const { proxy: valueProxy } =
-                              memoizedCreateChangeProxy(nextResult.value, {
+                            // For Map values(), try to find the key using our mapping
+                            if (
+                              methodName === `values` &&
+                              ptarget instanceof Map
+                            ) {
+                              const mapKey = valueToKeyMap.get(nextResult.value)
+                              if (mapKey !== undefined) {
+                                // Create a special parent tracker for this Map value
+                                const mapParent = {
+                                  tracker: changeTracker,
+                                  prop: mapKey,
+                                  updateMap: (newValue: unknown) => {
+                                    // Update the Map in the copy
+                                    if (changeTracker.copy_ instanceof Map) {
+                                      changeTracker.copy_.set(mapKey, newValue)
+                                    }
+                                  },
+                                }
+
+                                const { proxy: valueProxy } =
+                                  memoizedCreateChangeProxy(
+                                    nextResult.value,
+                                    mapParent
+                                  )
+                                nextResult.value = valueProxy
+                              }
+                            } else if (ptarget instanceof Set) {
+                              // For Set, we need to track modifications and update the Set accordingly
+                              const setOriginalValue = nextResult.value
+                              const setParent = {
                                 tracker: changeTracker,
-                                prop: tempKey,
-                              })
-                            nextResult.value = valueProxy
+                                prop: setOriginalValue, // Use the original value as the prop
+                                updateSet: (newValue: unknown) => {
+                                  // Update the Set in the copy by removing old value and adding new one
+                                  if (changeTracker.copy_ instanceof Set) {
+                                    changeTracker.copy_.delete(setOriginalValue)
+                                    changeTracker.copy_.add(newValue)
+                                    // Update our mapping for future iterations
+                                    originalToModifiedMap.set(
+                                      setOriginalValue,
+                                      newValue
+                                    )
+                                  }
+                                },
+                              }
+
+                              const { proxy: valueProxy } =
+                                memoizedCreateChangeProxy(
+                                  nextResult.value,
+                                  setParent
+                                )
+                              nextResult.value = valueProxy
+                            } else {
+                              // For other cases, use a symbol as a placeholder
+                              const tempKey = Symbol(`iterator-value`)
+                              const { proxy: valueProxy } =
+                                memoizedCreateChangeProxy(nextResult.value, {
+                                  tracker: changeTracker,
+                                  prop: tempKey,
+                                })
+                              nextResult.value = valueProxy
+                            }
                           }
                         }
                       }

package/src/query/builder/index.ts

@@ -184,6 +184,110 @@ export class BaseQueryBuilder<TContext extends Context = Context> {
     }) as any
   }
 
+  /**
+   * Perform a LEFT JOIN with another table or subquery
+   *
+   * @param source - An object with a single key-value pair where the key is the table alias and the value is a Collection or subquery
+   * @param onCallback - A function that receives table references and returns the join condition
+   * @returns A QueryBuilder with the left joined table available
+   *
+   * @example
+   * ```ts
+   * // Left join users with posts
+   * query
+   *   .from({ users: usersCollection })
+   *   .leftJoin({ posts: postsCollection }, ({users, posts}) => eq(users.id, posts.userId))
+   * ```
+   */
+  leftJoin<TSource extends Source>(
+    source: TSource,
+    onCallback: JoinOnCallback<
+      MergeContext<TContext, SchemaFromSource<TSource>>
+    >
+  ): QueryBuilder<
+    MergeContextWithJoinType<TContext, SchemaFromSource<TSource>, `left`>
+  > {
+    return this.join(source, onCallback, `left`)
+  }
+
+  /**
+   * Perform a RIGHT JOIN with another table or subquery
+   *
+   * @param source - An object with a single key-value pair where the key is the table alias and the value is a Collection or subquery
+   * @param onCallback - A function that receives table references and returns the join condition
+   * @returns A QueryBuilder with the right joined table available
+   *
+   * @example
+   * ```ts
+   * // Right join users with posts
+   * query
+   *   .from({ users: usersCollection })
+   *   .rightJoin({ posts: postsCollection }, ({users, posts}) => eq(users.id, posts.userId))
+   * ```
+   */
+  rightJoin<TSource extends Source>(
+    source: TSource,
+    onCallback: JoinOnCallback<
+      MergeContext<TContext, SchemaFromSource<TSource>>
+    >
+  ): QueryBuilder<
+    MergeContextWithJoinType<TContext, SchemaFromSource<TSource>, `right`>
+  > {
+    return this.join(source, onCallback, `right`)
+  }
+
+  /**
+   * Perform an INNER JOIN with another table or subquery
+   *
+   * @param source - An object with a single key-value pair where the key is the table alias and the value is a Collection or subquery
+   * @param onCallback - A function that receives table references and returns the join condition
+   * @returns A QueryBuilder with the inner joined table available
+   *
+   * @example
+   * ```ts
+   * // Inner join users with posts
+   * query
+   *   .from({ users: usersCollection })
+   *   .innerJoin({ posts: postsCollection }, ({users, posts}) => eq(users.id, posts.userId))
+   * ```
+   */
+  innerJoin<TSource extends Source>(
+    source: TSource,
+    onCallback: JoinOnCallback<
+      MergeContext<TContext, SchemaFromSource<TSource>>
+    >
+  ): QueryBuilder<
+    MergeContextWithJoinType<TContext, SchemaFromSource<TSource>, `inner`>
+  > {
+    return this.join(source, onCallback, `inner`)
+  }
+
+  /**
+   * Perform a FULL JOIN with another table or subquery
+   *
+   * @param source - An object with a single key-value pair where the key is the table alias and the value is a Collection or subquery
+   * @param onCallback - A function that receives table references and returns the join condition
+   * @returns A QueryBuilder with the full joined table available
+   *
+   * @example
+   * ```ts
+   * // Full join users with posts
+   * query
+   *   .from({ users: usersCollection })
+   *   .fullJoin({ posts: postsCollection }, ({users, posts}) => eq(users.id, posts.userId))
+   * ```
+   */
+  fullJoin<TSource extends Source>(
+    source: TSource,
+    onCallback: JoinOnCallback<
+      MergeContext<TContext, SchemaFromSource<TSource>>
+    >
+  ): QueryBuilder<
+    MergeContextWithJoinType<TContext, SchemaFromSource<TSource>, `full`>
+  > {
+    return this.join(source, onCallback, `full`)
+  }
+
   /**
    * Filter rows based on a condition
    *