@tanstack/svelte-db 0.1.94 → 0.2.0

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,143 @@
+import { createLiveQueryCollection, createLiveQueryWindowController, isCollection, } from '@tanstack/db';
+import { untrack } from 'svelte';
+const DEFAULT_PAGE_SIZE = 20;
+const DEFAULT_GC_TIME_MS = 1;
+function hasSetWindow(collection) {
+    return typeof collection.utils.setWindow === `function`;
+}
+function normalizePageSize(pageSize) {
+    if (pageSize === undefined ||
+        !Number.isSafeInteger(pageSize) ||
+        pageSize <= 0) {
+        return DEFAULT_PAGE_SIZE;
+    }
+    return pageSize;
+}
+function resolveInput(input) {
+    if (isCollection(input)) {
+        return { kind: `collection`, collection: input };
+    }
+    if (typeof input !== `function`) {
+        throw new Error(`useLiveInfiniteQuery: First argument must be either a pre-created live query collection or a query function. ` +
+            `Received: ${typeof input}`);
+    }
+    // A zero-argument function can be a reactive collection getter. Query
+    // callbacks conventionally accept the builder, so avoid probing those.
+    if (input.length === 0) {
+        try {
+            const collection = input();
+            if (isCollection(collection)) {
+                return { kind: `collection`, collection };
+            }
+        }
+        catch {
+            // Query callbacks that close over their builder can still have arity 0.
+        }
+    }
+    return {
+        kind: `query`,
+        query: input,
+    };
+}
+export function useLiveInfiniteQuery(queryFnOrCollection, config, deps = []) {
+    let validatedCollection = null;
+    const pageSize = $derived(normalizePageSize(config.pageSize));
+    const initialPageParam = $derived(config.initialPageParam ?? 0);
+    const controller = $derived.by(() => {
+        for (const dependency of deps)
+            dependency();
+        const input = resolveInput(queryFnOrCollection);
+        if (input.kind === `collection`) {
+            const collection = input.collection;
+            if (!hasSetWindow(collection)) {
+                throw new Error(`useLiveInfiniteQuery: Pre-created live query collection must have an orderBy clause for infinite pagination to work. ` +
+                    `Please add .orderBy() to your createLiveQueryCollection query.`);
+            }
+            if (validatedCollection !== collection) {
+                validatedCollection = collection;
+                const currentWindow = collection.utils.getWindow?.();
+                const expectedLimit = pageSize + 1;
+                if (currentWindow &&
+                    (currentWindow.offset !== 0 || currentWindow.limit !== expectedLimit)) {
+                    console.warn(`useLiveInfiniteQuery: Pre-created collection has window {offset: ${currentWindow.offset}, limit: ${currentWindow.limit}} ` +
+                        `but the hook expects {offset: 0, limit: ${expectedLimit}}. Adjusting window now.`);
+                }
+            }
+            return createLiveQueryWindowController(collection, {
+                pageSize,
+                initialPageParam,
+            });
+        }
+        const collection = createLiveQueryCollection({
+            query: (q) => input
+                .query(q)
+                .limit(pageSize + 1)
+                .offset(0),
+            startSync: false,
+            gcTime: DEFAULT_GC_TIME_MS,
+        });
+        return createLiveQueryWindowController(collection, {
+            pageSize,
+            initialPageParam,
+        });
+    });
+    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 = () => controller.fetchNextPage();
+    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.0",
   "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.0"
   },
   "peerDependencies": {
     "svelte": "^5.0.0"