@tanstack/db 0.3.2 → 0.4.0

package/src/{change-events.ts → collection/change-events.ts}

@@ -1,17 +1,17 @@
 import {
   createSingleRowRefProxy,
   toExpression,
-} from "./query/builder/ref-proxy"
-import { compileSingleRowExpression } from "./query/compiler/evaluators.js"
-import { optimizeExpressionWithIndexes } from "./utils/index-optimization.js"
+} from "../query/builder/ref-proxy"
+import { compileSingleRowExpression } from "../query/compiler/evaluators.js"
+import { optimizeExpressionWithIndexes } from "../utils/index-optimization.js"
 import type {
   ChangeMessage,
   CurrentStateAsChangesOptions,
   SubscribeChangesOptions,
-} from "./types"
-import type { Collection } from "./collection"
-import type { SingleRowRefProxy } from "./query/builder/ref-proxy"
-import type { BasicExpression } from "./query/ir.js"
+} from "../types"
+import type { Collection } from "./index.js"
+import type { SingleRowRefProxy } from "../query/builder/ref-proxy"
+import type { BasicExpression } from "../query/ir.js"
 
 /**
  * Interface for a collection-like object that provides the necessary methods
@@ -46,8 +46,8 @@ export function currentStateAsChanges<
   TKey extends string | number,
 >(
   collection: CollectionLike<T, TKey>,
-  options: CurrentStateAsChangesOptions<T> = {}
-): Array<ChangeMessage<T>> {
+  options: CurrentStateAsChangesOptions = {}
+): Array<ChangeMessage<T>> | void {
   // Helper function to collect filtered results
   const collectFilteredResults = (
     filterFn?: (value: T) => boolean
@@ -66,31 +66,17 @@ export function currentStateAsChanges<
     return result
   }
 
-  if (!options.where && !options.whereExpression) {
+  // TODO: handle orderBy and limit options
+  //       by calling optimizeOrderedLimit
+
+  if (!options.where) {
     // No filtering, return all items
     return collectFilteredResults()
   }
 
   // There's a where clause, let's see if we can use an index
   try {
-    let expression: BasicExpression<boolean>
-
-    if (options.whereExpression) {
-      // Use the pre-compiled expression directly
-      expression = options.whereExpression
-    } else if (options.where) {
-      // Create the single-row refProxy for the callback
-      const singleRowRefProxy = createSingleRowRefProxy<T>()
-
-      // Execute the callback to get the expression
-      const whereExpression = options.where(singleRowRefProxy)
-
-      // Convert the result to a BasicExpression
-      expression = toExpression(whereExpression)
-    } else {
-      // This should never happen due to the check above, but TypeScript needs it
-      return []
-    }
+    const expression: BasicExpression<boolean> = options.where
 
     // Try to optimize the query using indexes
     const optimizationResult = optimizeExpressionWithIndexes(
@@ -113,11 +99,11 @@ export function currentStateAsChanges<
       }
       return result
     } else {
-      // No index found or complex expression, fall back to full scan with filter
-      const filterFn = options.where
-        ? createFilterFunction(options.where)
-        : createFilterFunctionFromExpression(expression)
+      if (options.optimizedOnly) {
+        return
+      }
 
+      const filterFn = createFilterFunctionFromExpression(expression)
       return collectFilteredResults(filterFn)
     }
   } catch (error) {
@@ -127,9 +113,11 @@ export function currentStateAsChanges<
       error
     )
 
-    const filterFn = options.where
-      ? createFilterFunction(options.where)
-      : createFilterFunctionFromExpression(options.whereExpression!)
+    const filterFn = createFilterFunctionFromExpression(options.where)
+
+    if (options.optimizedOnly) {
+      return
+    }
 
     return collectFilteredResults(filterFn)
   }
@@ -201,11 +189,9 @@ export function createFilterFunctionFromExpression<T extends object>(
  */
 export function createFilteredCallback<T extends object>(
   originalCallback: (changes: Array<ChangeMessage<T>>) => void,
-  options: SubscribeChangesOptions<T>
+  options: SubscribeChangesOptions
 ): (changes: Array<ChangeMessage<T>>) => void {
-  const filterFn = options.whereExpression
-    ? createFilterFunctionFromExpression(options.whereExpression)
-    : createFilterFunction(options.where!)
+  const filterFn = createFilterFunctionFromExpression(options.whereExpression!)
 
   return (changes: Array<ChangeMessage<T>>) => {
     const filteredChanges: Array<ChangeMessage<T>> = []

package/src/collection/changes.ts

@@ -0,0 +1,163 @@
+import { NegativeActiveSubscribersError } from "../errors"
+import { CollectionSubscription } from "./subscription.js"
+import type { StandardSchemaV1 } from "@standard-schema/spec"
+import type { ChangeMessage, SubscribeChangesOptions } from "../types"
+import type { CollectionLifecycleManager } from "./lifecycle.js"
+import type { CollectionSyncManager } from "./sync.js"
+import type { CollectionEventsManager } from "./events.js"
+import type { CollectionImpl } from "./index.js"
+
+export class CollectionChangesManager<
+  TOutput extends object = Record<string, unknown>,
+  TKey extends string | number = string | number,
+  TSchema extends StandardSchemaV1 = StandardSchemaV1,
+  TInput extends object = TOutput,
+> {
+  private lifecycle!: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>
+  private sync!: CollectionSyncManager<TOutput, TKey, TSchema, TInput>
+  private events!: CollectionEventsManager
+  private collection!: CollectionImpl<TOutput, TKey, any, TSchema, TInput>
+
+  public activeSubscribersCount = 0
+  public changeSubscriptions = new Set<CollectionSubscription>()
+  public batchedEvents: Array<ChangeMessage<TOutput, TKey>> = []
+  public shouldBatchEvents = false
+
+  /**
+   * Creates a new CollectionChangesManager instance
+   */
+  constructor() {}
+
+  public setDeps(deps: {
+    lifecycle: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>
+    sync: CollectionSyncManager<TOutput, TKey, TSchema, TInput>
+    events: CollectionEventsManager
+    collection: CollectionImpl<TOutput, TKey, any, TSchema, TInput>
+  }) {
+    this.lifecycle = deps.lifecycle
+    this.sync = deps.sync
+    this.events = deps.events
+    this.collection = deps.collection
+  }
+
+  /**
+   * Emit an empty ready event to notify subscribers that the collection is ready
+   * This bypasses the normal empty array check in emitEvents
+   */
+  public emitEmptyReadyEvent(): void {
+    // Emit empty array directly to all subscribers
+    for (const subscription of this.changeSubscriptions) {
+      subscription.emitEvents([])
+    }
+  }
+
+  /**
+   * Emit events either immediately or batch them for later emission
+   */
+  public emitEvents(
+    changes: Array<ChangeMessage<TOutput, TKey>>,
+    forceEmit = false
+  ): void {
+    // Skip batching for user actions (forceEmit=true) to keep UI responsive
+    if (this.shouldBatchEvents && !forceEmit) {
+      // Add events to the batch
+      this.batchedEvents.push(...changes)
+      return
+    }
+
+    // Either we're not batching, or we're forcing emission (user action or ending batch cycle)
+    let eventsToEmit = changes
+
+    // If we have batched events and this is a forced emit, combine them
+    if (this.batchedEvents.length > 0 && forceEmit) {
+      eventsToEmit = [...this.batchedEvents, ...changes]
+      this.batchedEvents = []
+      this.shouldBatchEvents = false
+    }
+
+    if (eventsToEmit.length === 0) return
+
+    // Emit to all listeners
+    for (const subscription of this.changeSubscriptions) {
+      subscription.emitEvents(eventsToEmit)
+    }
+  }
+
+  /**
+   * Subscribe to changes in the collection
+   */
+  public subscribeChanges(
+    callback: (changes: Array<ChangeMessage<TOutput>>) => void,
+    options: SubscribeChangesOptions = {}
+  ): CollectionSubscription {
+    // Start sync and track subscriber
+    this.addSubscriber()
+
+    const subscription = new CollectionSubscription(this.collection, callback, {
+      ...options,
+      onUnsubscribe: () => {
+        this.removeSubscriber()
+        this.changeSubscriptions.delete(subscription)
+      },
+    })
+
+    if (options.includeInitialState) {
+      subscription.requestSnapshot()
+    }
+
+    // Add to batched listeners
+    this.changeSubscriptions.add(subscription)
+
+    return subscription
+  }
+
+  /**
+   * Increment the active subscribers count and start sync if needed
+   */
+  private addSubscriber(): void {
+    const previousSubscriberCount = this.activeSubscribersCount
+    this.activeSubscribersCount++
+    this.lifecycle.cancelGCTimer()
+
+    // Start sync if collection was cleaned up
+    if (
+      this.lifecycle.status === `cleaned-up` ||
+      this.lifecycle.status === `idle`
+    ) {
+      this.sync.startSync()
+    }
+
+    this.events.emitSubscribersChange(
+      this.activeSubscribersCount,
+      previousSubscriberCount
+    )
+  }
+
+  /**
+   * Decrement the active subscribers count and start GC timer if needed
+   */
+  private removeSubscriber(): void {
+    const previousSubscriberCount = this.activeSubscribersCount
+    this.activeSubscribersCount--
+
+    if (this.activeSubscribersCount === 0) {
+      this.lifecycle.startGCTimer()
+    } else if (this.activeSubscribersCount < 0) {
+      throw new NegativeActiveSubscribersError()
+    }
+
+    this.events.emitSubscribersChange(
+      this.activeSubscribersCount,
+      previousSubscriberCount
+    )
+  }
+
+  /**
+   * Clean up the collection by stopping sync and clearing data
+   * This can be called manually or automatically by garbage collection
+   */
+  public cleanup(): void {
+    this.batchedEvents = []
+    this.shouldBatchEvents = false
+  }
+}

package/src/{collection-events.ts → collection/events.ts}

@@ -1,5 +1,5 @@
-import type { Collection } from "./collection"
-import type { CollectionStatus } from "./types"
+import type { Collection } from "./index.js"
+import type { CollectionStatus } from "../types.js"
 
 /**
  * Event emitted when the collection status changes
@@ -47,15 +47,17 @@ export type CollectionEventHandler<T extends keyof AllCollectionEvents> = (
   event: AllCollectionEvents[T]
 ) => void
 
-export class CollectionEvents {
-  private collection: Collection<any, any, any, any, any>
+export class CollectionEventsManager {
+  private collection!: Collection<any, any, any, any, any>
   private listeners = new Map<
     keyof AllCollectionEvents,
     Set<CollectionEventHandler<any>>
   >()
 
-  constructor(collection: Collection<any, any, any, any, any>) {
-    this.collection = collection
+  constructor() {}
+
+  setDeps(deps: { collection: Collection<any, any, any, any, any> }) {
+    this.collection = deps.collection
   }
 
   on<T extends keyof AllCollectionEvents>(