@tanstack/svelte-db 0.1.94 → 0.2.1

package/README.md

@@ -1,3 +1,20 @@
+<div align="center">
+  <picture>
+    <source
+      media="(prefers-color-scheme: dark)"
+      srcset="https://tanstack.com/api/readme/db.png?framework=svelte&theme=dark"
+    />
+    <source
+      media="(prefers-color-scheme: light)"
+      srcset="https://tanstack.com/api/readme/db.png?framework=svelte"
+    />
+    <img
+      src="https://tanstack.com/api/readme/db.png?framework=svelte"
+      alt="TanStack Svelte DB"
+      width="900"
+    />
+  </picture>
+</div>
 # @tanstack/svelte-db
 
 Svelte helpers for TanStack DB. See [TanStack/db](https://github.com/TanStack/db) for more details.

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './useLiveQuery.svelte.js';
+export * from './useLiveInfiniteQuery.svelte.js';
 export * from '@tanstack/db';
 export type { Collection } from '@tanstack/db';
 export { createTransaction } from '@tanstack/db';

package/dist/index.js

@@ -1,5 +1,6 @@
 // Re-export all public APIs
 export * from './useLiveQuery.svelte.js';
+export * from './useLiveInfiniteQuery.svelte.js';
 // Re-export everything from @tanstack/db
 export * from '@tanstack/db';
 export { createTransaction } from '@tanstack/db';

package/dist/useLiveInfiniteQuery.svelte.d.ts

@@ -0,0 +1,40 @@
+import type { UseLiveQueryReturnWithCollection, useLiveQuery } from './useLiveQuery.svelte.js';
+import type { Collection, Context, InferResultType, InitialQueryBuilder, NonSingleResult, QueryBuilder } from '@tanstack/db';
+type MaybeGetter<T> = T | (() => T);
+type InfiniteQueryOptions = {
+    pageSize?: number;
+    initialPageParam?: number;
+};
+export type LiveInfiniteQueryConfig<TRow> = InfiniteQueryOptions & {
+    /**
+     * @deprecated Pagination uses the shared controller's peek-ahead strategy.
+     * This remains for compatibility with TanStack Query conventions.
+     */
+    getNextPageParam?: (lastPage: Array<TRow>, allPages: Array<Array<TRow>>, lastPageParam: number, allPageParams: Array<number>) => number | undefined;
+};
+export type UseLiveInfiniteQueryConfig<TContext extends Context> = LiveInfiniteQueryConfig<InferResultType<TContext>[number]>;
+export type UseLiveInfiniteQueryReturn<TContext extends Context> = Omit<ReturnType<typeof useLiveQuery<TContext>>, `data`> & {
+    data: InferResultType<TContext>;
+    pages: Array<Array<InferResultType<TContext>[number]>>;
+    pageParams: Array<number>;
+    fetchNextPage: () => Promise<void>;
+    hasNextPage: boolean;
+    isFetchingNextPage: boolean;
+    error: unknown;
+};
+export type UseLiveInfiniteQueryReturnWithCollection<TResult extends object, TKey extends string | number, TUtils extends Record<string, any>> = Omit<UseLiveQueryReturnWithCollection<TResult, TKey, TUtils, Array<TResult>>, `data`> & {
+    data: Array<TResult>;
+    pages: Array<Array<TResult>>;
+    pageParams: Array<number>;
+    fetchNextPage: () => Promise<void>;
+    hasNextPage: boolean;
+    isFetchingNextPage: boolean;
+    error: unknown;
+};
+/**
+ * Create a Svelte-native reactive view over the shared live-query window
+ * controller. The query must include an `orderBy` clause.
+ */
+export declare function useLiveInfiniteQuery<TResult extends object, TKey extends string | number, TUtils extends Record<string, any>>(liveQueryCollection: MaybeGetter<Collection<TResult, TKey, TUtils> & NonSingleResult>, config: LiveInfiniteQueryConfig<TResult>): UseLiveInfiniteQueryReturnWithCollection<TResult, TKey, TUtils>;
+export declare function useLiveInfiniteQuery<TContext extends Context>(queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>, config: UseLiveInfiniteQueryConfig<TContext>, deps?: Array<() => unknown>): UseLiveInfiniteQueryReturn<TContext>;
+export {};

package/dist/useLiveInfiniteQuery.svelte.js

@@ -0,0 +1,136 @@
+import { assertLiveQueryWindowManyResult, compareLiveQueryWindowDependencies, createLiveQueryCollection, createLiveQueryWindowController, fetchNextLiveQueryWindowPage, getLiveQueryWindowCollectionWarning, normalizeLiveQueryWindowPageSize, resolveLiveQueryWindowInput, shouldPreserveLiveQueryWindowPageCount, } from '@tanstack/db';
+import { tick, untrack } from 'svelte';
+const DEFAULT_GC_TIME_MS = 1;
+export function useLiveInfiniteQuery(queryFnOrCollection, config, deps = []) {
+    let validatedCollection = null;
+    let previousController = null;
+    let previousInput = null;
+    let previousDependencies = null;
+    let previousPageSize = null;
+    let previousInitialPageParam = null;
+    const pageSize = $derived(normalizeLiveQueryWindowPageSize(config.pageSize));
+    const initialPageParam = $derived(config.initialPageParam ?? 0);
+    const controller = $derived.by(() => {
+        const dependencies = deps.map((dependency) => dependency());
+        const input = resolveLiveQueryWindowInput(queryFnOrCollection);
+        const dependencyComparison = compareLiveQueryWindowDependencies(previousDependencies, dependencies);
+        const dependenciesChanged = dependencyComparison.changed;
+        const dependenciesStructurallyEqual = dependencyComparison.structurallyEqual;
+        const pageShapeChanged = previousPageSize !== pageSize ||
+            previousInitialPageParam !== initialPageParam;
+        const sameCollection = input.kind === `collection` &&
+            previousInput?.kind === `collection` &&
+            previousInput.collection === input.collection;
+        const canPreservePageCount = shouldPreserveLiveQueryWindowPageCount({
+            hasPreviousController: previousController !== null,
+            previousInputKind: previousInput?.kind,
+            inputKind: input.kind,
+            sameCollection,
+            dependenciesChanged,
+            dependenciesStructurallyEqual,
+            pageShapeChanged,
+        });
+        const previousPageCount = previousController
+            ? Math.max(1, previousController.getSnapshot().pages.length)
+            : 1;
+        const initialPageCount = canPreservePageCount ? previousPageCount : 1;
+        previousInput = input;
+        previousDependencies = [...dependencies];
+        previousPageSize = pageSize;
+        previousInitialPageParam = initialPageParam;
+        if (input.kind === `collection`) {
+            const collection = input.collection;
+            const warning = getLiveQueryWindowCollectionWarning(collection, pageSize + 1);
+            if (validatedCollection !== collection) {
+                validatedCollection = collection;
+                if (warning)
+                    console.warn(warning);
+            }
+            const currentController = createLiveQueryWindowController(collection, {
+                pageSize,
+                initialPageParam,
+                initialPageCount,
+            });
+            previousController = currentController;
+            return currentController;
+        }
+        const collection = createLiveQueryCollection({
+            query: input.query.limit(pageSize + 1).offset(0),
+            startSync: false,
+            gcTime: DEFAULT_GC_TIME_MS,
+        });
+        assertLiveQueryWindowManyResult(collection);
+        const currentController = createLiveQueryWindowController(collection, {
+            pageSize,
+            initialPageParam,
+            initialPageCount,
+        });
+        previousController = currentController;
+        return currentController;
+    });
+    let snapshot = $state.raw(untrack(() => controller.getSnapshot()));
+    $effect(() => {
+        const currentController = controller;
+        snapshot = currentController.getSnapshot();
+        const unsubscribe = currentController.subscribe(() => {
+            snapshot = currentController.getSnapshot();
+        });
+        snapshot = currentController.getSnapshot();
+        return () => {
+            unsubscribe();
+            currentController.dispose();
+        };
+    });
+    const fetchNextPage = async () => {
+        // A dependency can invalidate the derived controller before Svelte runs the
+        // effect that subscribes it. Queue the imperative call until that handoff
+        // has completed so it cannot target an inactive controller.
+        await tick();
+        await fetchNextLiveQueryWindowPage(controller);
+    };
+    return {
+        get state() {
+            return snapshot.state;
+        },
+        get data() {
+            return snapshot.data;
+        },
+        get collection() {
+            return snapshot.collection;
+        },
+        get status() {
+            return snapshot.status;
+        },
+        get isLoading() {
+            return snapshot.isLoading;
+        },
+        get isReady() {
+            return snapshot.isReady;
+        },
+        get isIdle() {
+            return snapshot.isIdle;
+        },
+        get isError() {
+            return snapshot.isError;
+        },
+        get isCleanedUp() {
+            return snapshot.isCleanedUp;
+        },
+        get pages() {
+            return snapshot.pages;
+        },
+        get pageParams() {
+            return snapshot.pageParams;
+        },
+        get hasNextPage() {
+            return snapshot.hasNextPage;
+        },
+        get isFetchingNextPage() {
+            return snapshot.isFetchingNextPage;
+        },
+        get error() {
+            return snapshot.error;
+        },
+        fetchNextPage,
+    };
+}

package/dist/useLiveQuery.svelte.js

@@ -2,7 +2,7 @@
 import { untrack } from 'svelte';
 // eslint-disable-next-line import/no-duplicates -- See https://github.com/un-ts/eslint-plugin-import-x/issues/308
 import { SvelteMap } from 'svelte/reactivity';
-import { BaseQueryBuilder, createLiveQueryCollection, isCollection, isSingleResultCollection, } from '@tanstack/db';
+import { BaseQueryBuilder, createLiveQueryCollection, createLiveQueryObserver, isCollection, isSingleResultCollection, } from '@tanstack/db';
 function toValue(value) {
     if (typeof value === `function`) {
         return value();
@@ -89,11 +89,19 @@ export function useLiveQuery(configOrQueryOrCollection, deps = []) {
             internalData.push(...Array.from(currentCollection.values()));
         });
     };
-    // Track current unsubscribe function
-    let currentUnsubscribe = null;
+    // The shared observer owns subscription, the ready-race, and status; Svelte
+    // materializes into its own rune-backed map (granular) + ordered array.
+    let currentObserver = null;
+    const syncFromObserver = (observer, currentCollection) => {
+        status = observer.getSnapshot().status;
+        syncDataFromCollection(currentCollection);
+    };
     // Watch for collection changes and subscribe to updates
     $effect(() => {
         const currentCollection = collection;
+        // Tear down any previous observer.
+        currentObserver?.dispose();
+        currentObserver = null;
         // Handle null collection (disabled query)
         if (!currentCollection) {
             status = `disabled`;
@@ -101,68 +109,45 @@ export function useLiveQuery(configOrQueryOrCollection, deps = []) {
                 state.clear();
                 internalData = [];
             });
-            if (currentUnsubscribe) {
-                currentUnsubscribe();
-                currentUnsubscribe = null;
-            }
             return;
         }
-        // Update status state whenever the effect runs
-        status = currentCollection.status;
-        // Clean up previous subscription
-        if (currentUnsubscribe) {
-            currentUnsubscribe();
-        }
-        // Initialize state with current collection data
-        untrack(() => {
-            state.clear();
-            for (const [key, value] of currentCollection.entries()) {
-                state.set(key, value);
-            }
-        });
-        // Initialize data array in correct order
-        syncDataFromCollection(currentCollection);
-        // Listen for the first ready event to catch status transitions
-        // that might not trigger change events (fixes async status transition bug)
-        currentCollection.onFirstReady(() => {
-            // Update status directly - Svelte's reactivity system handles the update automatically
-            // Note: We cannot use flushSync here as it's disallowed inside effects in async mode
-            status = currentCollection.status;
-        });
-        // Subscribe to collection changes with granular updates
-        const subscription = currentCollection.subscribeChanges((changes) => {
-            // Apply each change individually to the reactive state
+        const observer = createLiveQueryObserver(currentCollection);
+        currentObserver = observer;
+        // Initial rows arrive as the observer's first delta (includeInitialState);
+        // apply them and every subsequent delta granularly to the rune-backed map.
+        untrack(() => state.clear());
+        const unsubscribe = observer.subscribe((changes) => {
             untrack(() => {
-                for (const change of changes) {
-                    switch (change.type) {
-                        case `insert`:
-                        case `update`:
-                            state.set(change.key, change.value);
-                            break;
-                        case `delete`:
-                            state.delete(change.key);
-                            break;
+                if (changes) {
+                    for (const change of changes) {
+                        switch (change.type) {
+                            case `insert`:
+                            case `update`:
+                                state.set(change.key, change.value);
+                                break;
+                            case `delete`:
+                                state.delete(change.key);
+                                break;
+                        }
+                    }
+                }
+                else {
+                    // Cleanup and other status-only publications carry no row deltas.
+                    // Rebuild the keyed view so it cannot diverge from ordered data.
+                    state.clear();
+                    for (const [key, value] of observer.getSnapshot().state ?? []) {
+                        state.set(key, value);
                     }
                 }
             });
-            // Update the data array to maintain sorted order
-            syncDataFromCollection(currentCollection);
-            // Update status state on every change
-            status = currentCollection.status;
-        }, {
-            includeInitialState: true,
+            syncFromObserver(observer, currentCollection);
         });
-        currentUnsubscribe = subscription.unsubscribe.bind(subscription);
-        // Preload collection data if not already started
-        if (currentCollection.status === `idle`) {
-            currentCollection.preload().catch(console.error);
-        }
+        syncFromObserver(observer, currentCollection);
         // Cleanup when effect is invalidated
         return () => {
-            if (currentUnsubscribe) {
-                currentUnsubscribe();
-                currentUnsubscribe = null;
-            }
+            unsubscribe();
+            observer.dispose();
+            currentObserver = null;
         };
     });
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/svelte-db",
-  "version": "0.1.94",
+  "version": "0.2.1",
   "description": "Svelte integration for @tanstack/db",
   "author": "Kyle Mathews",
   "license": "MIT",
@@ -35,7 +35,7 @@
     "skills"
   ],
   "dependencies": {
-    "@tanstack/db": "0.6.17"
+    "@tanstack/db": "0.7.1"
   },
   "peerDependencies": {
     "svelte": "^5.0.0"