react-listing-engine 0.6.4 → 0.6.6

package/dist/url-sync.controller-DX67JivW.d.ts

@@ -1,89 +0,0 @@
-import { Q as QueryParams } from './entity-adapter.interface-BDgbSxhq.js';
-
-/**
- * DOM-agnostic abstraction over "the URL's query string" — or, in tests/SSR,
- * an in-memory stand-in (`MemoryHistoryPort`). `UrlSyncController` talks to
- * this interface only, never to `window.location`/`history` directly, so it
- * stays framework- and environment-free like the rest of `src/core`.
- */
-interface HistoryPort {
-    getQuery(): QueryParams;
-    setQuery(params: QueryParams): void;
-    subscribe(cb: () => void): () => void;
-}
-
-interface UrlSyncEngine<TFilters> {
-    subscribe(cb: () => void): () => void;
-    readonly state: {
-        readonly filters: TFilters;
-    };
-    applyFilters(patch: Partial<TFilters>): Promise<void> | void;
-}
-interface UrlSyncOptions<TFilters> {
-    history: HistoryPort;
-    toQuery(filters: TFilters): QueryParams;
-    toFilters(query: QueryParams): Partial<TFilters>;
-    hydrateOnStart?: boolean;
-}
-/**
- * Bidirectional, DOM-agnostic sync between an engine's `filters` and a
- * `HistoryPort`'s query params. Framework-free: talks to `UrlSyncEngine`
- * (a structural subset `ListingEngine` satisfies) and `HistoryPort`, nothing
- * else — no `window`, no React.
- *
- * OPTIONAL, not the primary path: `styled/listing-app.tsx`'s turnkey
- * `ListingApp` (the package's main-entry default) does NOT wire this up —
- * it uses an event-based URL API instead (`initialFilters` in,
- * `onFiltersChange` out; see that file's doc comment), so the library never
- * touches `window.history` by default. This class remains exported for
- * consumers who explicitly want the library to own history writes/reads
- * itself (e.g. via `/shadcn`'s `ListingApp.urlSync`, or wiring it directly
- * against a hand-built engine).
- *
- * Echo-loop guard: both subscriptions below are driven by the SAME
- * `isSyncing` flag. `ListingEngine.applyFilters()` and `MemoryHistoryPort`
- * (and any real browser HistoryPort) both notify their subscribers
- * SYNCHRONOUSLY as part of the write (`store.setFilters()` -> `notify()`
- * happens before any debounce timer, and `MemoryHistoryPort.setQuery()`
- * notifies before returning) — so when this controller initiates a write on
- * one side, the reciprocal subscription on the other side fires within the
- * very same call stack, before `isSyncing` is reset. Wrapping each
- * controller-initiated write in `isSyncing = true; ...; isSyncing = false`
- * (via try/finally, so a throwing `toQuery`/`toFilters`/notify can't leave it
- * stuck) means that reciprocal callback observes `isSyncing === true` and
- * short-circuits instead of writing back — one hop each direction, never a
- * cascade. `hydrateOnStart`'s initial engine write is wrapped the same way,
- * since it must not immediately echo the just-hydrated filters back out to
- * history as a redundant `setQuery`.
- *
- * `isSyncing` only covers that SYNCHRONOUS window, though — the real
- * `ListingEngine.applyFilters()` notifies AGAIN, asynchronously: after
- * `await adapter.list(...)` resolves, `store.setResults()` and
- * `store.setLoading(false)` each call `notify()`, well after `isSyncing` has
- * already been reset to `false` by the `withSyncGuard` that kicked the query
- * off. Left unguarded, that async tail would fire the engine subscription
- * below and echo an identical (but spurious) `history.setQuery(...)` on
- * every completed query. Rather than widening `isSyncing` to cover the whole
- * async query (which would also swallow legitimate concurrent history
- * changes that land mid-query), `syncEngineToHistory` is idempotent BY
- * VALUE instead: it computes the target query and skips the write entirely
- * when it already matches `history.getQuery()` — timing-independent, so it
- * suppresses the async-tail echo without touching `isSyncing` at all.
- */
-declare class UrlSyncController<TFilters> {
-    private readonly history;
-    private readonly toQueryFn;
-    private readonly toFiltersFn;
-    private readonly hydrateOnStart;
-    private isSyncing;
-    private unsubscribeEngine;
-    private unsubscribeHistory;
-    constructor(opts: UrlSyncOptions<TFilters>);
-    start(engine: UrlSyncEngine<TFilters>): void;
-    stop(): void;
-    private syncEngineToHistory;
-    private applyFiltersSafely;
-    private withSyncGuard;
-}
-
-export { type HistoryPort as H, UrlSyncController as U, type UrlSyncEngine as a, type UrlSyncOptions as b };