Implementation Plan

This is the current plan of attack for the Local module work.

Phase 1: Document the model

• define when Local is a good fit
• define the difference between default collections and on-demand collections
• write down the non-goals before the API hardens

This section in the docs is that first phase.

Phase 2: Standardize shared helpers

• use the shared parseLoadSubsetFilters, parseLoadSubsetSorting, and parseLoadSubsetPagination helpers for translating loadSubsetOptions
• standardize a reusable server list input contract
• keep one filter implementation per module instead of separate suspense and live query logic

This is the most important API boundary to keep consistent as modules adopt local collections.

Phase 3: Integrate with Tulip components

• make sure components can consume both server-first and local-first data flows
• keep module UI APIs stable regardless of sync mode
• avoid leaking collection internals into every component boundary

Phase 4: Add windowed live-query support

• design a table strategy for paginated and infinite local windows
• make server counts and pagination work together with collection-backed optimistic updates
• validate the behavior on a high-volume module such as time

Phase 5: Pilot and refine

• apply the approach to one or two modules first
• document what needed custom glue and turn repeated patterns into shared APIs
• only then promote the docs from beta planning to stable package documentation

Beta exit criteria

Before Local should be considered stable, these points should be true:

• Local remains opt-in
• both default and on-demand sync modes are supported intentionally
• one server filter contract works for suspense query and live query flows
• Tulip tables can handle paginated or infinite local windows
• at least one real module proves the API is ergonomic

Additional suggestions

• start by standardizing helper boundaries before naming a high-level createLocalModule() style API
• prefer one good server contract over multiple convenience wrappers
• validate memory and invalidation behavior on a large dataset early, not after the API is public