Pattern: Populating a collection "as needed" with multiple Queries throughout app - no "base" query.

const dispatchCollection = createLiveQueryCollection({
  startSync: true,
  query: (q) =>
    q.from({ todo: graphqlCollection }).where(({ item }) => eq(item.type, `dispatch`)),
})

const dispatchCollection = createLiveQueryCollection({
  startSync: true,
  query: (q) =>
    q.from({ todo: graphqlCollection }).where(({ item }) => eq(item.type, `dispatch`)),
})

export const dbDispatchDateQueryCollection = createCollection(
  queryCollectionOptions({
    queryKey: [GET_DB_DISPATCH_DATE_QUERY_KEY, { date }],
    queryFn: async ({ date }: { date: string }) => {
      const result = await mainGraphQLClient.request(GET_DB_DISPATCH_DATE, { date })

      return result.dbDispatchesForDispatchDate
    },
    getKey: item => item.id,
    enabled: !!date,
  })
)

export const dbDispatchDateQueryCollection = createCollection(
  queryCollectionOptions({
    queryKey: [GET_DB_DISPATCH_DATE_QUERY_KEY, { date }],
    queryFn: async ({ date }: { date: string }) => {
      const result = await mainGraphQLClient.request(GET_DB_DISPATCH_DATE, { date })

      return result.dbDispatchesForDispatchDate
    },
    getKey: item => item.id,
    enabled: !!date,
  })
)

// src/lib/createCollectionFactory.ts (NEW UTILITY FILE)
import { Collection } from '@tanstack/react-db';

// The TTL should be slightly longer than the collection's gcTime to avoid race conditions.
const CACHE_TTL = 6000; // 6 seconds for a 5-second gcTime

// This is a higher-order function: a function that creates a factory function.
export function createCollectionFactory<TItem, TParams extends string | number>(
  creatorFn: (params: TParams) => Collection<TItem>
) {
  const cache = new Map<TParams, Collection<TItem>>();
  const timeouts = new Map<TParams, NodeJS.Timeout>();

  return (params: TParams): Collection<TItem> => {
    // If a cleanup timer was set for this key, cancel it because we're using it again.
    if (timeouts.has(params)) {
      clearTimeout(timeouts.get(params));
      timeouts.delete(params);
    }

    // If the collection is already in the cache, return it.
    if (cache.has(params)) {
      return cache.get(params)!;
    }

    // Otherwise, create a new collection instance.
    const newCollection = creatorFn(params);
    cache.set(params, newCollection);

    // IMPORTANT: Listen for when the collection is cleaned up by Tanstack DB's gcTime.
    // When it is, we remove it from our factory's cache to prevent memory leaks.
    const unsubscribe = newCollection.subscribe(() => {
      if (newCollection.status === 'cleaned-up') {
        cache.delete(params);
        timeouts.delete(params); // Clean up any stray timeout
        unsubscribe(); // Clean up the subscription itself
      }
    });

    return newCollection;
  };
}

// src/lib/createCollectionFactory.ts (NEW UTILITY FILE)
import { Collection } from '@tanstack/react-db';

// The TTL should be slightly longer than the collection's gcTime to avoid race conditions.
const CACHE_TTL = 6000; // 6 seconds for a 5-second gcTime

// This is a higher-order function: a function that creates a factory function.
export function createCollectionFactory<TItem, TParams extends string | number>(
  creatorFn: (params: TParams) => Collection<TItem>
) {
  const cache = new Map<TParams, Collection<TItem>>();
  const timeouts = new Map<TParams, NodeJS.Timeout>();

  return (params: TParams): Collection<TItem> => {
    // If a cleanup timer was set for this key, cancel it because we're using it again.
    if (timeouts.has(params)) {
      clearTimeout(timeouts.get(params));
      timeouts.delete(params);
    }

    // If the collection is already in the cache, return it.
    if (cache.has(params)) {
      return cache.get(params)!;
    }

    // Otherwise, create a new collection instance.
    const newCollection = creatorFn(params);
    cache.set(params, newCollection);

    // IMPORTANT: Listen for when the collection is cleaned up by Tanstack DB's gcTime.
    // When it is, we remove it from our factory's cache to prevent memory leaks.
    const unsubscribe = newCollection.subscribe(() => {
      if (newCollection.status === 'cleaned-up') {
        cache.delete(params);
        timeouts.delete(params); // Clean up any stray timeout
        unsubscribe(); // Clean up the subscription itself
      }
    });

    return newCollection;
  };
}

// src/features/dispatch/dispatch.source-collections.ts (REVISED FACTORY)
import { createCollection } from '@tanstack/react-db';
import { queryCollectionOptions } from '@tanstack/query-db-collection';
import { createCollectionFactory } from '@/lib/createCollectionFactory'; // <-- IMPORT THE NEW UTILITY

// ... other imports and type definitions ...
type SourceItem = DispatchType | VehicleDispatchType | WorkOrderType;

// --- Factory for the Date-based Query ---
export const getSourceCollectionByDate = createCollectionFactory((date: string) => {
  return createCollection(
    queryCollectionOptions<SourceItem>({
      queryKey: ['dbDispatchDate', { date }],
      queryFn: async () => { /* ... fetch and flatten data ... */ },
      getKey: (item) => `${item.__typename}:${item.id}`,
      // You can configure gcTime here if you want it to be longer or shorter than 5s
      // gcTime: 30000, // e.g., 30 seconds
    })
  );
});

// --- Factory for the Job-based Query ---
export const getSourceCollectionByJob = createCollectionFactory((jobId: string) => {
  return createCollection(
    queryCollectionOptions<SourceItem>({
      queryKey: ['dispatchesByJob', { jobId }],
      queryFn: async () => { /* ... fetch and flatten data ... */ },
      getKey: (item) => `${item.__typename}:${item.id}`,
    })
  );
});

// src/features/dispatch/dispatch.source-collections.ts (REVISED FACTORY)
import { createCollection } from '@tanstack/react-db';
import { queryCollectionOptions } from '@tanstack/query-db-collection';
import { createCollectionFactory } from '@/lib/createCollectionFactory'; // <-- IMPORT THE NEW UTILITY

// ... other imports and type definitions ...
type SourceItem = DispatchType | VehicleDispatchType | WorkOrderType;

// --- Factory for the Date-based Query ---
export const getSourceCollectionByDate = createCollectionFactory((date: string) => {
  return createCollection(
    queryCollectionOptions<SourceItem>({
      queryKey: ['dbDispatchDate', { date }],
      queryFn: async () => { /* ... fetch and flatten data ... */ },
      getKey: (item) => `${item.__typename}:${item.id}`,
      // You can configure gcTime here if you want it to be longer or shorter than 5s
      // gcTime: 30000, // e.g., 30 seconds
    })
  );
});

// --- Factory for the Job-based Query ---
export const getSourceCollectionByJob = createCollectionFactory((jobId: string) => {
  return createCollection(
    queryCollectionOptions<SourceItem>({
      queryKey: ['dispatchesByJob', { jobId }],
      queryFn: async () => { /* ... fetch and flatten data ... */ },
      getKey: (item) => `${item.__typename}:${item.id}`,
    })
  );
});

// src/hooks/useRegisterSourceCollection.ts
// ...imports

export type SourceItem = DispatchType | VehicleDispatchType | WorkOrderType;
export const activeSourceCollectionsAtom = atom<Collection<SourceItem>[]>([]);

// A module-level map to keep track of removal timers for each collection instance.
const removalTimers = new Map<Collection<SourceItem>, NodeJS.Timeout>();

export const useRegisterSourceCollection = (collection: Collection<SourceItem> | null) => {
  const setActiveSourceCollections = useSetAtom(activeSourceCollectionsAtom);

  useEffect(() => {
    if (!collection) return;

    // Check if a removal timer is pending for this collection.
    // If so, the user has returned to a view using this collection before it was GC'd.
    if (removalTimers.has(collection)) {
      // Cancel the pending removal.
      clearTimeout(removalTimers.get(collection)!);
      removalTimers.delete(collection);
    }

    // Add the collection to the global registry if it's not already there.
    setActiveSourceCollections((prev) => {
      if (prev.includes(collection)) {
        return prev;
      }
      return [...prev, collection];
    });

    // On unmount, schedule the collection for removal from the global registry.
    return () => {
      // Set a timer to remove the collection after the delay.
      const timerId = setTimeout(() => {
        console.log(`Removing collection from active registry due to gcTime expiration...`);
        setActiveSourceCollections((prev) => prev.filter((c) => c !== collection));
        removalTimers.delete(collection);
      }, REMOVAL_DELAY_MS);

      removalTimers.set(collection, timerId);
    };
  }, [collection, setActiveSourceCollections]);
};

// src/hooks/useRegisterSourceCollection.ts
// ...imports

export type SourceItem = DispatchType | VehicleDispatchType | WorkOrderType;
export const activeSourceCollectionsAtom = atom<Collection<SourceItem>[]>([]);

// A module-level map to keep track of removal timers for each collection instance.
const removalTimers = new Map<Collection<SourceItem>, NodeJS.Timeout>();

export const useRegisterSourceCollection = (collection: Collection<SourceItem> | null) => {
  const setActiveSourceCollections = useSetAtom(activeSourceCollectionsAtom);

  useEffect(() => {
    if (!collection) return;

    // Check if a removal timer is pending for this collection.
    // If so, the user has returned to a view using this collection before it was GC'd.
    if (removalTimers.has(collection)) {
      // Cancel the pending removal.
      clearTimeout(removalTimers.get(collection)!);
      removalTimers.delete(collection);
    }

    // Add the collection to the global registry if it's not already there.
    setActiveSourceCollections((prev) => {
      if (prev.includes(collection)) {
        return prev;
      }
      return [...prev, collection];
    });

    // On unmount, schedule the collection for removal from the global registry.
    return () => {
      // Set a timer to remove the collection after the delay.
      const timerId = setTimeout(() => {
        console.log(`Removing collection from active registry due to gcTime expiration...`);
        setActiveSourceCollections((prev) => prev.filter((c) => c !== collection));
        removalTimers.delete(collection);
      }, REMOVAL_DELAY_MS);

      removalTimers.set(collection, timerId);
    };
  }, [collection, setActiveSourceCollections]);
};

// src/features/dispatch/hooks/useUnifiedDispatches.ts
// ...imports 

export const useUnifiedDispatches = () => {
  // 1. Subscribe to the list of active source collections
  const activeSources = useAtomValue(activeSourceCollectionsAtom);

  // 2. Create a live query that depends on the list of active sources
  const { data, ...rest } = useLiveQuery(
    (q) => {
      // Handle edge cases: no sources active yet
      if (activeSources.length === 0) {
        return q.from({ empty: [] }).select(() => ({} as DispatchType));
      }

      // Dynamically build the query with full outer joins
      let query = q.from({ s0: activeSources[0] });
      const aliases = ['s0'];

      // Chain full joins for all other active sources
      for (let i = 1; i < activeSources.length; i++) {
        const alias = `s${i}`;
        aliases.push(alias);
        query = query.fullJoin({ [alias]: activeSources[i] }, (row) =>
          // Join on our unique composite key
          eq(row.s0.id, row[alias].id)
        );
      }

      // Merge the results and filter for only Dispatches
      return query
        .select((row) => {
          // Coalesce finds the first non-null value, effectively merging the rows.
          // We reverse the aliases to prioritize sources added later.
          const aliasedSources = aliases.reverse().map(alias => row[alias]);
          return coalesce(...aliasedSources) as SourceItem;
        })
        .where((merged) => eq(merged.__typename, 'Dispatch'))
        .select((merged) => merged as DispatchType); // Final cast to the correct type
    },
    [activeSources] // CRITICAL: Rerun the query builder when the list of sources changes
  );

  return { data: data ?? [], ...rest };
};

// src/features/dispatch/hooks/useUnifiedDispatches.ts
// ...imports 

export const useUnifiedDispatches = () => {
  // 1. Subscribe to the list of active source collections
  const activeSources = useAtomValue(activeSourceCollectionsAtom);

  // 2. Create a live query that depends on the list of active sources
  const { data, ...rest } = useLiveQuery(
    (q) => {
      // Handle edge cases: no sources active yet
      if (activeSources.length === 0) {
        return q.from({ empty: [] }).select(() => ({} as DispatchType));
      }

      // Dynamically build the query with full outer joins
      let query = q.from({ s0: activeSources[0] });
      const aliases = ['s0'];

      // Chain full joins for all other active sources
      for (let i = 1; i < activeSources.length; i++) {
        const alias = `s${i}`;
        aliases.push(alias);
        query = query.fullJoin({ [alias]: activeSources[i] }, (row) =>
          // Join on our unique composite key
          eq(row.s0.id, row[alias].id)
        );
      }

      // Merge the results and filter for only Dispatches
      return query
        .select((row) => {
          // Coalesce finds the first non-null value, effectively merging the rows.
          // We reverse the aliases to prioritize sources added later.
          const aliasedSources = aliases.reverse().map(alias => row[alias]);
          return coalesce(...aliasedSources) as SourceItem;
        })
        .where((merged) => eq(merged.__typename, 'Dispatch'))
        .select((merged) => merged as DispatchType); // Final cast to the correct type
    },
    [activeSources] // CRITICAL: Rerun the query builder when the list of sources changes
  );

  return { data: data ?? [], ...rest };
};

import { useLiveQuery } from '@tanstack/react-db';
import { getSourceCollectionByDate } from '../dispatch.source-collections';
import { useRegisterSourceCollection } from '../hooks/useRegisterSourceCollection';
import { useUnifiedDispatches } from '../hooks/useUnifiedDispatches';

function DispatchScreen({ dateString }) {
  // 1. Get the source collection instance for this specific date from the factory.
  const sourceCollection = getSourceCollectionByDate(dateString);

  // 2. Register this source collection with our global store.
  //    It will be automatically removed when this component unmounts.
  useRegisterSourceCollection(sourceCollection);
  
  // 3. Any component in the app can now use this hook to get ALL dispatches.
  const { data: allKnownDispatches, isLoading } = useUnifiedDispatches();

  // You can still perform additional client-side filtering if needed for the view
  const dispatchesForThisDate = allKnownDispatches.filter(d => d.date === dateString);

  if (isLoading) return <Spinner />;
  
  // ... render your UI with `dispatchesForThisDate`
}

// In your Job Details Component
function JobDetails({ jobId }) {
  // 1. This component gets and registers a DIFFERENT source collection.
  const sourceCollection = getSourceCollectionByJob(jobId);
  useRegisterSourceCollection(sourceCollection);

  // 2. It can also use the SAME unified hook to get all known dispatches.
  const { data: allKnownDispatches } = useUnifiedDispatches();
  
  // This component's data need is different, so it filters differently.
  const dispatchesForThisJob = allKnownDispatches.filter(d => d.workOrder?.jobId === jobId);

  // ... render UI
}

import { useLiveQuery } from '@tanstack/react-db';
import { getSourceCollectionByDate } from '../dispatch.source-collections';
import { useRegisterSourceCollection } from '../hooks/useRegisterSourceCollection';
import { useUnifiedDispatches } from '../hooks/useUnifiedDispatches';

function DispatchScreen({ dateString }) {
  // 1. Get the source collection instance for this specific date from the factory.
  const sourceCollection = getSourceCollectionByDate(dateString);

  // 2. Register this source collection with our global store.
  //    It will be automatically removed when this component unmounts.
  useRegisterSourceCollection(sourceCollection);
  
  // 3. Any component in the app can now use this hook to get ALL dispatches.
  const { data: allKnownDispatches, isLoading } = useUnifiedDispatches();

  // You can still perform additional client-side filtering if needed for the view
  const dispatchesForThisDate = allKnownDispatches.filter(d => d.date === dateString);

  if (isLoading) return <Spinner />;
  
  // ... render your UI with `dispatchesForThisDate`
}

// In your Job Details Component
function JobDetails({ jobId }) {
  // 1. This component gets and registers a DIFFERENT source collection.
  const sourceCollection = getSourceCollectionByJob(jobId);
  useRegisterSourceCollection(sourceCollection);

  // 2. It can also use the SAME unified hook to get all known dispatches.
  const { data: allKnownDispatches } = useUnifiedDispatches();
  
  // This component's data need is different, so it filters differently.
  const dispatchesForThisJob = allKnownDispatches.filter(d => d.workOrder?.jobId === jobId);

  // ... render UI
}