@tanstack/db 0.0.12 → 0.0.13

package/src/index.ts

@@ -7,6 +7,7 @@ export * from "./errors"
 export * from "./utils"
 export * from "./proxy"
 export * from "./query/index.js"
+export * from "./optimistic-action"
 
 // Re-export some stuff explicitly to ensure the type & value is exported
 export type { Collection } from "./collection"

package/src/optimistic-action.ts

@@ -0,0 +1,65 @@
+import { createTransaction } from "./transactions"
+import type { CreateOptimisticActionsOptions, Transaction } from "./types"
+
+/**
+ * Creates an optimistic action function that applies local optimistic updates immediately
+ * before executing the actual mutation on the server.
+ *
+ * This pattern allows for responsive UI updates while the actual mutation is in progress.
+ * The optimistic update is applied via the `onMutate` callback, and the server mutation
+ * is executed via the `mutationFn`.
+ *
+ * @example
+ * ```ts
+ * const addTodo = createOptimisticAction<string>({
+ *   onMutate: (text) => {
+ *     // Instantly applies local optimistic state
+ *     todoCollection.insert({
+ *       id: uuid(),
+ *       text,
+ *       completed: false
+ *     })
+ *   },
+ *   mutationFn: async (text, params) => {
+ *     // Persist the todo to your backend
+ *     const response = await fetch('/api/todos', {
+ *       method: 'POST',
+ *       body: JSON.stringify({ text, completed: false }),
+ *     })
+ *     return response.json()
+ *   }
+ * })
+ *
+ * // Usage
+ * const transaction = addTodo('New Todo Item')
+ * ```
+ *
+ * @template TVariables - The type of variables that will be passed to the action function
+ * @param options - Configuration options for the optimistic action
+ * @returns A function that accepts variables of type TVariables and returns a Transaction
+ */
+export function createOptimisticAction<TVariables = unknown>(
+  options: CreateOptimisticActionsOptions<TVariables>
+) {
+  const { mutationFn, onMutate, ...config } = options
+
+  return (variables: TVariables): Transaction => {
+    // Create transaction with the original config
+    const transaction = createTransaction({
+      ...config,
+      // Wire the mutationFn to use the provided variables
+      mutationFn: async (params) => {
+        return await mutationFn(variables, params)
+      },
+    })
+
+    // Execute the transaction. The mutationFn is called once mutate()
+    // is finished.
+    transaction.mutate(() => {
+      // Call onMutate with variables to apply optimistic updates
+      onMutate(variables)
+    })
+
+    return transaction
+  }
+}

package/src/query/compiled-query.ts

@@ -1,6 +1,7 @@
 import { D2, MultiSet, output } from "@electric-sql/d2mini"
 import { createCollection } from "../collection.js"
 import { compileQueryPipeline } from "./pipeline-compiler.js"
+import type { StandardSchemaV1 } from "@standard-schema/spec"
 import type { Collection } from "../collection.js"
 import type { ChangeMessage, ResolveType, SyncConfig } from "../types.js"
 import type {
@@ -114,10 +115,36 @@ export class CompiledQuery<TResults extends object = Record<string, unknown>> {
 
     this.graph = graph
     this.inputs = inputs
+
+    const compare = query.orderBy
+      ? (
+          val1: ResolveType<
+            TResults,
+            StandardSchemaV1,
+            Record<string, unknown>
+          >,
+          val2: ResolveType<TResults, StandardSchemaV1, Record<string, unknown>>
+        ): number => {
+          // The query builder always adds an _orderByIndex property if the results are ordered
+          const x = val1 as TResults & { _orderByIndex: number }
+          const y = val2 as TResults & { _orderByIndex: number }
+          if (x._orderByIndex < y._orderByIndex) {
+            return -1
+          } else if (x._orderByIndex > y._orderByIndex) {
+            return 1
+          } else {
+            return 0
+          }
+        }
+      : undefined
+
     this.resultCollection = createCollection<TResults>({
       getKey: (val: unknown) => {
         return (val as any)._key
       },
+      gcTime: 0,
+      startSync: true,
+      compare,
       sync: {
         sync: sync as unknown as (params: {
           collection: Collection<
@@ -178,26 +205,21 @@ export class CompiledQuery<TResults extends object = Record<string, unknown>> {
       throw new Error(`Query is stopped`)
     }
 
-    // Send initial state
-    Object.entries(this.inputCollections).forEach(([key, collection]) => {
-      this.sendChangesToInput(
-        key,
-        collection.currentStateAsChanges(),
-        collection.config.getKey
-      )
-    })
-    this.runGraph()
-
     // Subscribe to changes
     Object.entries(this.inputCollections).forEach(([key, collection]) => {
-      const unsubscribe = collection.subscribeChanges((changes) => {
-        this.sendChangesToInput(key, changes, collection.config.getKey)
-        this.runGraph()
-      })
+      const unsubscribe = collection.subscribeChanges(
+        (changes) => {
+          this.sendChangesToInput(key, changes, collection.config.getKey)
+          this.runGraph()
+        },
+        { includeInitialState: true }
+      )
 
       this.unsubscribeCallbacks.push(unsubscribe)
     })
 
+    this.runGraph()
+
     this.state = `running`
     return () => {
       this.stop()

package/src/query/query-builder.ts

@@ -268,7 +268,7 @@ export class BaseQueryBuilder<TContext extends Context<Schema>> {
     // Ensure we have an orderByIndex in the select if we have an orderBy
     // This is required if select is called after orderBy
     if (this._query.orderBy) {
-      validatedSelects.push({ _orderByIndex: { ORDER_INDEX: `numeric` } })
+      validatedSelects.push({ _orderByIndex: { ORDER_INDEX: `fractional` } })
     }
 
     const newBuilder = new BaseQueryBuilder<TContext>(
@@ -735,7 +735,7 @@ export class BaseQueryBuilder<TContext extends Context<Schema>> {
     // This is required if select is called before orderBy
     newBuilder.query.select = [
       ...(newBuilder.query.select ?? []),
-      { _orderByIndex: { ORDER_INDEX: `numeric` } },
+      { _orderByIndex: { ORDER_INDEX: `fractional` } },
     ]
 
     return newBuilder as QueryBuilder<TContext>

package/src/transactions.ts

@@ -156,7 +156,12 @@ export class Transaction<T extends object = Record<string, unknown>> {
     for (const mutation of this.mutations) {
       if (!hasCalled.has(mutation.collection.id)) {
         mutation.collection.onTransactionStateChange()
-        mutation.collection.commitPendingTransactions()
+
+        // Only call commitPendingTransactions if there are pending sync transactions
+        if (mutation.collection.pendingSyncedTransactions.length > 0) {
+          mutation.collection.commitPendingTransactions()
+        }
+
         hasCalled.add(mutation.collection.id)
       }
     }

package/src/types.ts

@@ -111,6 +111,17 @@ export interface TransactionConfig<T extends object = Record<string, unknown>> {
   metadata?: Record<string, unknown>
 }
 
+/**
+ * Options for the createOptimisticAction helper
+ */
+export interface CreateOptimisticActionsOptions<TVars = unknown>
+  extends Omit<TransactionConfig, `mutationFn`> {
+  /** Function to apply optimistic updates locally before the mutation completes */
+  onMutate: (vars: TVars) => void
+  /** Function to execute the mutation on the server */
+  mutationFn: (vars: TVars, params: MutationFnParams) => Promise<any>
+}
+
 export type { Transaction }
 
 type Value<TExtensions = never> =
@@ -216,6 +227,21 @@ export type DeleteMutationFn<T extends object = Record<string, unknown>> = (
   params: DeleteMutationFnParams<T>
 ) => Promise<any>
 
+/**
+ * Collection status values for lifecycle management
+ */
+export type CollectionStatus =
+  /** Collection is created but sync hasn't started yet (when startSync config is false) */
+  | `idle`
+  /** Sync has started but hasn't received the first commit yet */
+  | `loading`
+  /** Collection has received at least one commit and is ready for use */
+  | `ready`
+  /** An error occurred during sync initialization */
+  | `error`
+  /** Collection has been cleaned up and resources freed */
+  | `cleaned-up`
+
 export interface CollectionConfig<
   T extends object = Record<string, unknown>,
   TKey extends string | number = string | number,
@@ -236,6 +262,27 @@ export interface CollectionConfig<
    * getKey: (item) => item.uuid
    */
   getKey: (item: T) => TKey
+  /**
+   * Time in milliseconds after which the collection will be garbage collected
+   * when it has no active subscribers. Defaults to 5 minutes (300000ms).
+   */
+  gcTime?: number
+  /**
+   * Whether to start syncing immediately when the collection is created.
+   * Defaults to false for lazy loading. Set to true to immediately sync.
+   */
+  startSync?: boolean
+  /**
+   * Optional function to compare two items.
+   * This is used to order the items in the collection.
+   * @param x The first item to compare
+   * @param y The second item to compare
+   * @returns A number indicating the order of the items
+   * @example
+   * // For a collection with a 'createdAt' field
+   * compare: (x, y) => x.createdAt.getTime() - y.createdAt.getTime()
+   */
+  compare?: (x: T, y: T) => number
   /**
    * Optional asynchronous handler function called before an insert operation
    * @param params Object containing transaction and mutation information