@tanstack/svelte-db 0.2.1 → 0.3.0

package/dist/DbProvider.svelte

@@ -0,0 +1,17 @@
+<script lang="ts">
+  import { setDbClientContext } from './db-context.js'
+  import type { DbClient } from '@tanstack/db'
+  import type { Snippet } from 'svelte'
+
+  let {
+    client,
+    children,
+  }: {
+    client: DbClient
+    children?: Snippet
+  } = $props()
+
+  setDbClientContext(() => client)
+</script>
+
+{@render children?.()}

package/dist/DbProvider.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { DbClient } from '@tanstack/db';
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    client: DbClient;
+    children?: Snippet;
+};
+declare const DbProvider: import("svelte").Component<$$ComponentProps, {}, "">;
+type DbProvider = ReturnType<typeof DbProvider>;
+export default DbProvider;

package/dist/db-context.d.ts

@@ -0,0 +1,6 @@
+import type { DbClient } from '@tanstack/db';
+type DbClientContext = () => DbClient;
+export declare function setDbClientContext(client: DbClientContext): DbClientContext;
+export declare function useDbClient(): DbClient;
+export declare function useOptionalDbClient(): DbClient | undefined;
+export {};

package/dist/db-context.js

@@ -0,0 +1,21 @@
+import { getContext, setContext } from 'svelte';
+const dbClientContext = Symbol.for(`@tanstack/svelte-db.DbClient`);
+export function setDbClientContext(client) {
+    return setContext(dbClientContext, client);
+}
+export function useDbClient() {
+    const client = useOptionalDbClient();
+    if (!client) {
+        throw new Error(`useDbClient must be used within a DbProvider.`);
+    }
+    return client;
+}
+export function useOptionalDbClient() {
+    try {
+        return getContext(dbClientContext)?.();
+    }
+    catch {
+        // Legacy helpers may be called from a rune root rather than a component.
+        return undefined;
+    }
+}

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export * from './useLiveQuery.svelte.js';
 export * from './useLiveInfiniteQuery.svelte.js';
+export { useDbClient, useOptionalDbClient } from './db-context.js';
+export { default as DbProvider } from './DbProvider.svelte';
 export * from '@tanstack/db';
 export type { Collection } from '@tanstack/db';
 export { createTransaction } from '@tanstack/db';

package/dist/index.js

@@ -1,6 +1,8 @@
 // Re-export all public APIs
 export * from './useLiveQuery.svelte.js';
 export * from './useLiveInfiniteQuery.svelte.js';
+export { useDbClient, useOptionalDbClient } from './db-context.js';
+export { default as DbProvider } from './DbProvider.svelte';
 // Re-export everything from @tanstack/db
 export * from '@tanstack/db';
 export { createTransaction } from '@tanstack/db';

package/dist/useLiveQuery.svelte.d.ts

@@ -1,4 +1,4 @@
-import type { Collection, CollectionStatus, Context, GetResult, InferResultType, InitialQueryBuilder, LiveQueryCollectionConfig, NonSingleResult, QueryBuilder, SingleResult } from '@tanstack/db';
+import type { Collection, CollectionStatus, Context, DbClient, GetResult, InferResultType, InitialQueryBuilder, LiveQueryCollectionConfig, LiveQueryKey, NonSingleResult, QueryBuilder, SingleResult } from '@tanstack/db';
 /**
  * Return type for useLiveQuery hook
  * @property state - Reactive Map of query results (key → item)
@@ -34,6 +34,10 @@ export interface UseLiveQueryReturnWithCollection<T extends object, TKey extends
     isCleanedUp: boolean;
 }
 type MaybeGetter<T> = T | (() => T);
+export type UseLiveQueryConfig<TContext extends Context> = LiveQueryCollectionConfig<TContext> & {
+    queryKey?: MaybeGetter<LiveQueryKey>;
+    client?: DbClient;
+};
 /**
  * Create a live query using a query function
  * @param queryFn - Query function that defines what data to fetch
@@ -161,7 +165,7 @@ export declare function useLiveQuery<TContext extends Context>(queryFn: (q: Init
  * //   <div>{itemsQuery.data.length} items loaded</div>
  * // {/if}
  */
-export declare function useLiveQuery<TContext extends Context>(config: LiveQueryCollectionConfig<TContext>, deps?: Array<() => unknown>): UseLiveQueryReturn<GetResult<TContext>, InferResultType<TContext>>;
+export declare function useLiveQuery<TContext extends Context>(config: UseLiveQueryConfig<TContext>, deps?: Array<() => unknown>): UseLiveQueryReturn<GetResult<TContext>, InferResultType<TContext>>;
 /**
  * Subscribe to an existing query collection (can be reactive)
  * @param liveQueryCollection - Pre-created query collection to subscribe to (can be a getter)

package/dist/useLiveQuery.svelte.js

@@ -2,7 +2,8 @@
 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, createLiveQueryObserver, isCollection, isSingleResultCollection, } from '@tanstack/db';
+import { BaseQueryBuilder, UnhashableQueryIRError, createLiveQueryCollection, createLiveQueryObserver, getLiveQueryHash, getStableValueHash, isCollection, isSingleResultCollection, prepareLiveQueryValue, } from '@tanstack/db';
+import { useOptionalDbClient } from './db-context.js';
 function toValue(value) {
     if (typeof value === `function`) {
         return value();
@@ -11,7 +12,8 @@ function toValue(value) {
 }
 // Implementation
 export function useLiveQuery(configOrQueryOrCollection, deps = []) {
-    const collection = $derived.by(() => {
+    const contextDbClient = useOptionalDbClient();
+    const resolved = $derived.by(() => {
         // First check if the original parameter might be a getter
         // by seeing if toValue returns something different than the original
         let unwrappedParam = configOrQueryOrCollection;
@@ -27,6 +29,10 @@ export function useLiveQuery(configOrQueryOrCollection, deps = []) {
         }
         // Check if it's already a collection by checking for specific collection methods
         const inputIsCollection = isCollection(unwrappedParam);
+        const dbClient = inputIsCollection
+            ? contextDbClient
+            : (unwrappedParam?.client ??
+                contextDbClient);
         if (inputIsCollection) {
             // Warn when passing a collection directly with on-demand sync mode
             // In on-demand mode, data is only loaded when queries with predicates request it
@@ -45,109 +51,128 @@ export function useLiveQuery(configOrQueryOrCollection, deps = []) {
             if (unwrappedParam.status === `idle`) {
                 unwrappedParam.startSyncImmediate();
             }
-            return unwrappedParam;
+            return {
+                collection: unwrappedParam,
+                client: dbClient,
+                queryHash: getStableValueHash([`collection`, unwrappedParam.id], `queryKey`),
+                resumeDeferredCollections: () => { },
+            };
         }
         // Reference deps to make computed reactive to them
-        deps.forEach((dep) => toValue(dep));
-        // Ensure we always start sync for Svelte helpers
-        if (typeof unwrappedParam === `function`) {
-            // Check if query function returns null/undefined (disabled query)
-            const queryBuilder = new BaseQueryBuilder();
-            const result = unwrappedParam(queryBuilder);
-            if (result === undefined || result === null) {
-                // Disabled query - return null
-                return null;
-            }
-            return createLiveQueryCollection({
-                query: unwrappedParam,
+        const dependencyValues = deps.map((dep) => toValue(dep));
+        const deferredCollections = new Set();
+        const preparedValue = prepareLiveQueryValue(unwrappedParam, dbClient, deferredCollections);
+        const configuredQueryKey = unwrappedParam?.queryKey;
+        const queryKey = configuredQueryKey
+            ? toValue(configuredQueryKey)
+            : undefined;
+        let queryHash;
+        try {
+            queryHash =
+                deps.length > 0 && !queryKey
+                    ? getStableValueHash([`deps`, dependencyValues, getLiveQueryHash(preparedValue)], `queryKey`)
+                    : getLiveQueryHash(preparedValue, queryKey);
+        }
+        catch (error) {
+            if (!(error instanceof UnhashableQueryIRError))
+                throw error;
+            if (queryKey !== undefined)
+                throw error;
+        }
+        let collection;
+        if (preparedValue === undefined || preparedValue === null) {
+            collection = null;
+        }
+        else if (isCollection(preparedValue)) {
+            collection = preparedValue;
+        }
+        else if (preparedValue instanceof BaseQueryBuilder) {
+            collection = createLiveQueryCollection({
+                query: preparedValue,
                 startSync: true,
             });
         }
         else {
-            // A reactive getter (or param-driven query fn) can resolve to null/undefined
-            // to mean "disabled". `toValue` above already called it, so guard here —
-            // otherwise `{ ...null }` reaches createLiveQueryCollection and throws.
-            if (unwrappedParam === undefined || unwrappedParam === null) {
-                return null;
-            }
-            return createLiveQueryCollection({
-                ...unwrappedParam,
+            collection = createLiveQueryCollection({
+                ...preparedValue,
                 startSync: true,
             });
         }
+        return {
+            collection,
+            client: dbClient,
+            queryHash,
+            resumeDeferredCollections: () => {
+                for (const deferredCollection of deferredCollections) {
+                    deferredCollection._resumeSyncStart();
+                }
+                deferredCollections.clear();
+            },
+        };
     });
+    let currentResolved = untrack(() => resolved);
+    let currentObserver = createLiveQueryObserver(currentResolved.collection, {
+        client: currentResolved.client,
+        queryHash: currentResolved.queryHash,
+        onPreload: currentResolved.resumeDeferredCollections,
+    });
+    const initialSnapshot = currentObserver.getServerSnapshot();
     // Reactive state that gets updated granularly through change events
-    const state = new SvelteMap();
+    const state = new SvelteMap(initialSnapshot.state ?? []);
     // Reactive data array that maintains sorted order
-    let internalData = $state([]);
+    let internalData = $state(Array.from(initialSnapshot.state?.values() ?? []));
     // Track collection status reactively
-    let status = $state(collection ? collection.status : `disabled`);
-    // Helper to sync data array from collection in correct order
-    const syncDataFromCollection = (currentCollection) => {
+    let status = $state(initialSnapshot.status);
+    const syncFromObserver = (observer, changes) => {
+        const snapshot = observer.getSnapshot();
+        status = snapshot.status;
         untrack(() => {
-            internalData = [];
-            internalData.push(...Array.from(currentCollection.values()));
+            if (changes && changes.length > 0) {
+                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 {
+                state.clear();
+                for (const [key, value] of snapshot.state ?? []) {
+                    state.set(key, value);
+                }
+            }
+            internalData = Array.from(snapshot.state?.values() ?? []);
         });
     };
-    // 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`;
-            untrack(() => {
-                state.clear();
-                internalData = [];
+        const nextResolved = resolved;
+        if (nextResolved !== currentResolved) {
+            currentObserver.dispose();
+            currentResolved = nextResolved;
+            currentObserver = createLiveQueryObserver(nextResolved.collection, {
+                client: nextResolved.client,
+                queryHash: nextResolved.queryHash,
+                onPreload: nextResolved.resumeDeferredCollections,
             });
-            return;
+            syncFromObserver(currentObserver);
         }
-        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 observer = currentObserver;
         const unsubscribe = observer.subscribe((changes) => {
-            untrack(() => {
-                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);
-                    }
-                }
-            });
-            syncFromObserver(observer, currentCollection);
+            syncFromObserver(observer, changes);
         });
-        syncFromObserver(observer, currentCollection);
+        currentResolved.resumeDeferredCollections();
+        syncFromObserver(observer);
         // Cleanup when effect is invalidated
         return () => {
             unsubscribe();
-            observer.dispose();
-            currentObserver = null;
+            if (observer === currentObserver)
+                observer.dispose();
         };
     });
     return {
@@ -155,14 +180,14 @@ export function useLiveQuery(configOrQueryOrCollection, deps = []) {
             return state;
         },
         get data() {
-            const currentCollection = collection;
+            const currentCollection = resolved.collection;
             if (currentCollection && isSingleResultCollection(currentCollection)) {
                 return internalData[0];
             }
             return internalData;
         },
         get collection() {
-            return collection;
+            return resolved.collection;
         },
         get status() {
             return status;

package/package.json

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

package/skills/svelte-db/SKILL.md

@@ -10,7 +10,7 @@ description: >
 type: framework
 library: db
 framework: svelte
-library_version: '0.6.0'
+library_version: '0.6.17'
 requires:
   - db-core
 sources: