@tanstack/db 0.0.11 → 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,8 +1,9 @@
 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, SyncConfig } from "../types.js"
+import type { ChangeMessage, ResolveType, SyncConfig } from "../types.js"
 import type {
   IStreamBuilder,
   MultiSetArray,
@@ -42,7 +43,13 @@ export class CompiledQuery<TResults extends object = Record<string, unknown>> {
       Object.entries(collections).map(([key]) => [key, graph.newInput<any>()])
     )
 
-    const sync: SyncConfig<TResults>[`sync`] = ({ begin, write, commit }) => {
+    // Use TResults directly to ensure type compatibility
+    const sync: SyncConfig<TResults>[`sync`] = ({
+      begin,
+      write,
+      commit,
+      collection,
+    }) => {
       compileQueryPipeline<IStreamBuilder<[unknown, TResults]>>(
         query,
         inputs
@@ -69,21 +76,35 @@ export class CompiledQuery<TResults extends object = Record<string, unknown>> {
             .forEach((changes, rawKey) => {
               const { deletes, inserts, value } = changes
               const valueWithKey = { ...value, _key: rawKey }
-              if (inserts && !deletes) {
+
+              // Simple singular insert.
+              if (inserts && deletes === 0) {
                 write({
                   value: valueWithKey,
                   type: `insert`,
                 })
-              } else if (inserts >= deletes) {
+              } else if (
+                // Insert & update(s) (updates are a delete & insert)
+                inserts > deletes ||
+                // Just update(s) but the item is already in the collection (so
+                // was inserted previously).
+                (inserts === deletes &&
+                  collection.has(valueWithKey._key as string | number))
+              ) {
                 write({
                   value: valueWithKey,
                   type: `update`,
                 })
+                // Only delete is left as an option
               } else if (deletes > 0) {
                 write({
                   value: valueWithKey,
                   type: `delete`,
                 })
+              } else {
+                throw new Error(
+                  `This should never happen ${JSON.stringify(changes)}`
+                )
               }
             })
           commit()
@@ -94,15 +115,57 @@ 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>({
-      id: crypto.randomUUID(), // TODO: remove when we don't require any more
       getKey: (val: unknown) => {
         return (val as any)._key
       },
+      gcTime: 0,
+      startSync: true,
+      compare,
       sync: {
-        sync,
+        sync: sync as unknown as (params: {
+          collection: Collection<
+            ResolveType<TResults, never, Record<string, unknown>>,
+            string | number,
+            {}
+          >
+          begin: () => void
+          write: (
+            message: Omit<
+              ChangeMessage<
+                ResolveType<TResults, never, Record<string, unknown>>,
+                string | number
+              >,
+              `key`
+            >
+          ) => void
+          commit: () => void
+        }) => void,
       },
-    })
+    }) as unknown as Collection<TResults, string | number, {}>
   }
 
   get results() {
@@ -142,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

@@ -3,6 +3,39 @@ import type { Collection } from "./collection"
 import type { StandardSchemaV1 } from "@standard-schema/spec"
 import type { Transaction } from "./transactions"
 
+/**
+ * Helper type to extract the output type from a standard schema
+ *
+ * @internal This is used by the type resolution system
+ */
+export type InferSchemaOutput<T> = T extends StandardSchemaV1
+  ? StandardSchemaV1.InferOutput<T> extends object
+    ? StandardSchemaV1.InferOutput<T>
+    : Record<string, unknown>
+  : Record<string, unknown>
+
+/**
+ * Helper type to determine the final type based on priority:
+ * 1. Explicit generic TExplicit (if not 'unknown')
+ * 2. Schema output type (if schema provided)
+ * 3. Fallback type TFallback
+ *
+ * @remarks
+ * This type is used internally to resolve the collection item type based on the provided generics and schema.
+ * Users should not need to use this type directly, but understanding the priority order helps when defining collections.
+ */
+export type ResolveType<
+  TExplicit,
+  TSchema extends StandardSchemaV1 = never,
+  TFallback extends object = Record<string, unknown>,
+> = unknown extends TExplicit
+  ? [TSchema] extends [never]
+    ? TFallback
+    : InferSchemaOutput<TSchema>
+  : TExplicit extends object
+    ? TExplicit
+    : Record<string, unknown>
+
 export type TransactionState = `pending` | `persisting` | `completed` | `failed`
 
 /**
@@ -19,11 +52,18 @@ export type UtilsRecord = Record<string, Fn>
  * Represents a pending mutation within a transaction
  * Contains information about the original and modified data, as well as metadata
  */
-export interface PendingMutation<T extends object = Record<string, unknown>> {
+export interface PendingMutation<
+  T extends object = Record<string, unknown>,
+  TOperation extends OperationType = OperationType,
+> {
   mutationId: string
-  original: Partial<T>
+  original: TOperation extends `insert` ? {} : T
   modified: T
-  changes: Partial<T>
+  changes: TOperation extends `insert`
+    ? T
+    : TOperation extends `delete`
+      ? T
+      : Partial<T>
   globalKey: string
   key: any
   type: OperationType
@@ -56,8 +96,9 @@ export type NonEmptyArray<T> = [T, ...Array<T>]
  */
 export type TransactionWithMutations<
   T extends object = Record<string, unknown>,
+  TOperation extends OperationType = OperationType,
 > = Transaction<T> & {
-  mutations: NonEmptyArray<PendingMutation<T>>
+  mutations: NonEmptyArray<PendingMutation<T, TOperation>>
 }
 
 export interface TransactionConfig<T extends object = Record<string, unknown>> {
@@ -70,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> =
@@ -148,15 +200,58 @@ export interface InsertConfig {
   metadata?: Record<string, unknown>
 }
 
+export type UpdateMutationFnParams<T extends object = Record<string, unknown>> =
+  {
+    transaction: TransactionWithMutations<T, `update`>
+  }
+
+export type InsertMutationFnParams<T extends object = Record<string, unknown>> =
+  {
+    transaction: TransactionWithMutations<T, `insert`>
+  }
+
+export type DeleteMutationFnParams<T extends object = Record<string, unknown>> =
+  {
+    transaction: TransactionWithMutations<T, `delete`>
+  }
+
+export type InsertMutationFn<T extends object = Record<string, unknown>> = (
+  params: InsertMutationFnParams<T>
+) => Promise<any>
+
+export type UpdateMutationFn<T extends object = Record<string, unknown>> = (
+  params: UpdateMutationFnParams<T>
+) => Promise<any>
+
+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,
+  TSchema extends StandardSchemaV1 = StandardSchemaV1,
 > {
   // If an id isn't passed in, a UUID will be
   // generated for it.
   id?: string
   sync: SyncConfig<T, TKey>
-  schema?: StandardSchema<T>
+  schema?: TSchema
   /**
    * Function to extract the ID from an object
    * This is required for update/delete operations which now only accept IDs
@@ -167,24 +262,45 @@ 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
    * @returns Promise resolving to any value
    */
-  onInsert?: MutationFn<T>
+  onInsert?: InsertMutationFn<T>
   /**
    * Optional asynchronous handler function called before an update operation
    * @param params Object containing transaction and mutation information
    * @returns Promise resolving to any value
    */
-  onUpdate?: MutationFn<T>
+  onUpdate?: UpdateMutationFn<T>
   /**
    * Optional asynchronous handler function called before a delete operation
    * @param params Object containing transaction and mutation information
    * @returns Promise resolving to any value
    */
-  onDelete?: MutationFn<T>
+  onDelete?: DeleteMutationFn<T>
 }
 
 export type ChangesPayload<T extends object = Record<string, unknown>> = Array<