@rindle/react 0.1.3 → 0.2.0

package/README.md

@@ -3,7 +3,8 @@
 React bindings for Rindle stores.
 
 ```tsx
-import { Rindle, useQuery } from "@rindle/react";
+import { Rindle, fragmentKey, useFragment, useRoot } from "@rindle/react";
+import { IssueCardFragment, issuesPageQuery, type IssueCardRef } from "./IssueListItem.queries.ts";
 
 createRoot(root).render(
   <Rindle store={app.store}>
@@ -12,12 +13,22 @@ createRoot(root).render(
 );
 
 function Issues() {
-  const issues = useQuery(queries.issuesPage(null));
-  return issues.map((issue) => <div key={issue.id}>{issue.title}</div>);
+  const [issues, { status }] = useRoot(issuesPageQuery, { limit: 50 }, IssueCardFragment);
+  if (status !== "complete" && issues.length === 0) return <p>Loading...</p>;
+  return issues.map((issue) => <IssueRow key={fragmentKey(issue)} issue={issue} />);
+}
+
+function IssueRow({ issue }: { issue: IssueCardRef }) {
+  const data = useFragment(IssueCardFragment, issue);
+  if (!data) return null;
+  return <div>{data.title}</div>;
 }
 ```
 
-`useQuery(query)` returns live `data`, subscribes on mount, and releases on unmount.
+`useRoot(namedQuery, args?, ...ctx?, RootFragment?)` retains the full named root query for sync
+coverage and returns local React-facing data. Passing a root fragment returns opaque refs for the
+root rows; child components read those refs with `useFragment(fragment, ref)`. `useQuery(query)` is
+still available for direct live query reads that do not need fragment-local boundaries.
 
 For local-first backends, the React-facing data view is shared by compiled local AST. Each
 mounted hook still retains its own `name`/`args` lease through the Store, so backend-level
@@ -33,10 +44,20 @@ cannot split local views from remote subscriptions keep the older materialized-v
   answered. A pending optimistic mutation no longer moves it — "is a write pending here?" is a
   separate axis on the backend (`backend.pending(qid)` / `onPending`), and `error` is reserved
   and currently unproduced. Shares `useQuery`'s leased view, so reading both is one subscription.
-- `useFragment(fragment, ref)` — a pure read of an already-projected fragment slice off the root
-  query's view (FRAGMENT-COMPOSITION-DESIGN.md §7). Adds no lease and never re-renders on its own;
-  it keeps a component tree waterfall-free by letting descendants read the one query the root opened.
+- `useSyncQuery(query)` — retains a named remote query for normalized/local-first sync coverage
+  without subscribing React to the broad result tree; returns only `ResultType`.
+- `useRoot(namedQuery, args?, ...ctx?)` — retains the full root coverage query and returns
+  `[data, details]`, where `details.status` distinguishes loading from completed-not-found.
+  Without a fragment argument, `data` is the root query's local React-facing data. Fragment child
+  relationships are surfaced as `FragmentRef`s, so children can keep owning their own reads.
+  Passing a fragment as the final argument switches `data` to root-ref mode:
+  `useRoot(namedQuery, args, RootFragment)`.
+- `useFragment(fragment, ref)` — reads an opaque local fragment ref. It opens a narrow local-only
+  query for that fragment and returns `null` until the local row is available. Child relationships
+  composed as `sub(alias, rel, ChildFragment)` are refs; inline child builders remain inline data.
+- `fragmentKey(ref)` — stable key for opaque fragment refs, useful for React list keys.
 - `useRindleStore()` — the `Store` from context, for imperative writes/reads inside components.
+- `SyncQueryCache` — the per-provider cache that dedupes sync-only coverage retains.
 - `QueryCache` — the per-provider cache that dedupes a query's materialized view across hooks.
 - `queryCacheKey(query)` — the stable string key (`@rindle/client`'s `stableKey(ast)`) under which
   the cache stores that view. Same AST → same key → one shared entry, and it matches the SSR seed

package/dist/index.d.ts

@@ -1,9 +1,17 @@
 import type { ReactNode } from "react";
-import type { ColsMap, Fragment, FragmentRef, Query, ResultType, Store } from "@rindle/client";
-type AnyQuery = Query<any, any, any>;
+import type { AnyQuery, ColsMap, Fragment, FragmentData, FragmentRef, NamedQuery, QueryLocalData, ResultType, Store } from "@rindle/client";
+type AnyFragment = Fragment<any, any, any, any>;
 export type QueryData<Q extends AnyQuery> = ReturnType<Q["materialize"]>["data"];
+export type RootData<Q extends AnyQuery> = QueryLocalData<Q>;
+export type RootRefData<Q extends AnyQuery, F extends Fragment<any, any, any, any>> = QueryData<Q> extends readonly unknown[] ? readonly FragmentRef<F>[] : FragmentRef<F> | null;
+export interface RootDetails {
+    readonly status: ResultType;
+}
+export type RootResult<Q extends AnyQuery> = readonly [data: RootData<Q>, details: RootDetails];
+export type RootRefResult<Q extends AnyQuery, F extends Fragment<any, any, any, any>> = readonly [data: RootRefData<Q, F>, details: RootDetails];
 export type { ResultType } from "@rindle/client";
-export type { Fragment, FragmentRef } from "@rindle/client";
+export type { Fragment, FragmentData, FragmentRef } from "@rindle/client";
+export { fragmentKey } from "@rindle/client";
 export interface RindleProps<S extends ColsMap = ColsMap> {
     store: Store<S>;
     children?: ReactNode;
@@ -12,9 +20,14 @@ interface QueryLease {
     id: number;
     viewKey: string;
 }
+interface SyncLease {
+    id: number;
+    coverageKey: string;
+}
 declare class RindleContextValue {
     readonly store: Store<ColsMap>;
     readonly cache: QueryCache;
+    readonly syncCache: SyncQueryCache;
     constructor(store: Store<ColsMap>);
 }
 export declare function Rindle<S extends ColsMap>({ store, children }: RindleProps<S>): import("react").FunctionComponentElement<import("react").ProviderProps<RindleContextValue | null>>;
@@ -28,22 +41,44 @@ export declare function useQuery<Q extends AnyQuery>(query: Q): QueryData<Q>;
  *  as {@link useQuery} (so reading both for one query is one subscription), and re-renders only when
  *  the status changes. */
 export declare function useQueryStatus(query: AnyQuery): ResultType;
+/** Retain a named server query for normalized/local-first sync coverage without subscribing React
+ *  to that query's broad result tree. The returned value is lifecycle state only; it is `unknown`
+ *  until the backend reports that the retained coverage has hydrated. */
+export declare function useSyncQuery(query: AnyQuery): ResultType;
+/** Run a named root query and expose its local React-facing data. Fragment child relationships are
+ *  refs, so child components can keep owning their own local reads. Passing a root fragment as the
+ *  final argument switches the result to opaque root refs for that fragment. */
+export declare function useRoot<Q extends AnyQuery>(query: Q): RootResult<Q>;
+export declare function useRoot<Q extends AnyQuery, F extends AnyFragment>(query: Q, fragment: F): RootRefResult<Q, F>;
+export declare function useRoot<Q extends AnyQuery>(query: NamedQuery<void, [], Q>): RootResult<Q>;
+export declare function useRoot<Q extends AnyQuery, F extends AnyFragment>(query: NamedQuery<void, [], Q>, fragment: F): RootRefResult<Q, F>;
+export declare function useRoot<Args, Ctx extends readonly unknown[], Q extends AnyQuery>(query: NamedQuery<Args, Ctx, Q>, args: Args, ...ctx: Ctx): RootResult<Q>;
+export declare function useRoot<Args, Ctx extends readonly unknown[], Q extends AnyQuery, F extends AnyFragment>(query: NamedQuery<Args, Ctx, Q>, args: Args, ...ctxAndFragment: [...ctx: Ctx, fragment: F]): RootRefResult<Q, F>;
 /**
- * Read a {@link Fragment}'s slice off the shared root view (FRAGMENT-COMPOSITION-DESIGN.md §7).
+ * Read a {@link Fragment}'s local data from an opaque ref.
  *
- * The waterfall-free contract: the ROOT component `useQuery`s the composed query (every child
- * fragment spread into it), and every descendant calls `useFragment` — a PURE READ of the
- * already-projected node at this fragment's alias — instead of opening its own `useQuery`. So a
- * whole component tree resolves through the ONE query the root opened, with no request waterfall;
- * a descendant that opens its own `useQuery` reintroduces the waterfall at that boundary.
+ * The query boundary calls {@link useRoot} with a fragment argument to retain the full named
+ * coverage query and receive root refs. Descendants call `useFragment` with those refs (or child
+ * refs returned by a parent fragment read) to open narrow local-only reads for the fields their
+ * fragment owns.
  *
- * Phase 0 is a typed pass-through: `ref` already IS the projected node (the parent got it from
- * `useQuery` and handed the slice down), so this returns it typed as the fragment's
- * {@link FragmentRef}. `fragment` declares *which* selection this component reads (co-location +
- * the seam masking plugs into); masking (Phase 2) narrows the returned shape with no call-site
- * change. Not a subscription — it adds no lease and never re-renders on its own.
+ * `ref` is an opaque token created by {@link useRoot} or returned from another local fragment read.
+ * The hook opens a narrow local-only query for this exact fragment and keeps the root coverage
+ * lease retained while mounted. Passing a legacy projected data object is unsupported.
  */
-export declare function useFragment<F extends Fragment<any, any, any>>(fragment: F, ref: FragmentRef<F>): FragmentRef<F>;
+export declare function useFragment<F extends Fragment<any, any, any, any>>(fragment: F, ref: FragmentRef<F> | null | undefined): FragmentData<F> | null;
+export declare class SyncQueryCache {
+    private readonly entries;
+    private nextLeaseId;
+    private readonly store;
+    constructor(store: Store<ColsMap>);
+    retain(coverageKey: string, query: AnyQuery): SyncLease;
+    release(lease: SyncLease): void;
+    subscribe(coverageKey: string, listener: () => void): () => void;
+    resultType(coverageKey: string): ResultType;
+    size(): number;
+    private createHandle;
+}
 export declare class QueryCache {
     private readonly entries;
     private nextLeaseId;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,12 +1,15 @@
 import { createContext, createElement, useCallback, useContext, useMemo, useRef, useSyncExternalStore, } from "react";
-import { stableKey } from "@rindle/client";
+import { createLocalFragmentRefForTable, fragmentAst, isFragment, isFragmentRelationship, localQueryReadAst, localFragmentReadAst, localRootFragmentRefsAst, queryFromAst, stableKey, tableMeta, } from "@rindle/client";
+export { fragmentKey } from "@rindle/client";
 const EMPTY_ARRAY = Object.freeze([]);
 class RindleContextValue {
     store;
     cache;
+    syncCache;
     constructor(store) {
         this.store = store;
         this.cache = new QueryCache(store);
+        this.syncCache = new SyncQueryCache(store);
     }
 }
 const RindleContext = createContext(null);
@@ -62,24 +65,450 @@ export function useQueryStatus(query) {
     const getServerSnapshot = useCallback(() => ctx.cache.serverResultType(descriptor.viewKey), [ctx.cache, descriptor.viewKey]);
     return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
 }
+/** Retain a named server query for normalized/local-first sync coverage without subscribing React
+ *  to that query's broad result tree. The returned value is lifecycle state only; it is `unknown`
+ *  until the backend reports that the retained coverage has hydrated. */
+export function useSyncQuery(query) {
+    const ctx = useRindleContext();
+    const descriptor = useMemo(() => describeQuery(query), [query]);
+    const queryRef = useRef(query);
+    queryRef.current = query;
+    const subscribe = useCallback((onStoreChange) => {
+        const lease = ctx.syncCache.retain(descriptor.leaseKey, queryRef.current);
+        const unsubscribe = ctx.syncCache.subscribe(descriptor.leaseKey, onStoreChange);
+        return () => {
+            unsubscribe();
+            ctx.syncCache.release(lease);
+        };
+    }, [ctx.syncCache, descriptor.leaseKey]);
+    const getSnapshot = useCallback(() => {
+        const live = ctx.syncCache.resultType(descriptor.leaseKey);
+        return live === "unknown" && ctx.cache.serverResultType(descriptor.viewKey) === "complete" ? "complete" : live;
+    }, [ctx.cache, ctx.syncCache, descriptor.leaseKey, descriptor.viewKey]);
+    const getServerSnapshot = useCallback(() => ctx.cache.serverResultType(descriptor.viewKey), [ctx.cache, descriptor.viewKey]);
+    return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
+export function useRoot(queryOrNamed, ...args) {
+    const { query, fragment } = resolveRootQueryInput(queryOrNamed, args, "useRoot");
+    const stableQuery = useStableQuery(query);
+    const status = useSyncQuery(stableQuery);
+    const data = fragment === undefined
+        ? useLocalRootQueryData(stableQuery)
+        : useRootRefData(stableQuery, fragment);
+    const details = useMemo(() => ({ status }), [status]);
+    return useMemo(() => [data, details], [data, details]);
+}
+function resolveRootQueryInput(queryOrNamed, args, hookName) {
+    const last = args[args.length - 1];
+    const fragment = isFragment(last) ? last : undefined;
+    const queryArgs = fragment === undefined ? args : args.slice(0, -1);
+    if (isNamedQuery(queryOrNamed)) {
+        const query = queryArgs.length === 0
+            ? queryOrNamed()
+            : queryOrNamed(queryArgs[0], ...queryArgs.slice(1));
+        return { query, fragment };
+    }
+    if (queryArgs.length !== 0)
+        throw new Error(`${hookName}(): expected (query) or (query, fragment).`);
+    return { query: queryOrNamed, fragment };
+}
+function isNamedQuery(v) {
+    return typeof v === "function"
+        && typeof v.queryName === "string"
+        && typeof v.resolve === "function";
+}
+function useStableQuery(query) {
+    const descriptor = describeQuery(query);
+    const ref = useRef(undefined);
+    if (ref.current === undefined || ref.current.leaseKey !== descriptor.leaseKey) {
+        ref.current = { leaseKey: descriptor.leaseKey, query };
+    }
+    return ref.current.query;
+}
+function useLocalRootQueryData(query) {
+    const ctx = useRindleContext();
+    const descriptor = useMemo(() => describeQuery(query), [query]);
+    const ast = useMemo(() => localQueryReadAst(query, (table) => ctx.store.primaryKeyFor(table)), [ctx.store, query]);
+    const localQuery = useMemo(() => queryFromAst(ast), [ast]);
+    const localDescriptor = useMemo(() => describeQuery(localQuery), [localQuery]);
+    const projection = useMemo(() => new LocalFragmentProjection(ast, { key: descriptor.leaseKey, query }, (table) => ctx.store.primaryKeyFor(table)), [ctx.store, ast, descriptor.leaseKey, query]);
+    const subscribe = useCallback((onStoreChange) => {
+        const localLease = ctx.cache.retain(localDescriptor.viewKey, localQuery);
+        const unsubscribeLocal = ctx.cache.subscribe(localDescriptor.viewKey, onStoreChange);
+        return () => {
+            unsubscribeLocal();
+            ctx.cache.release(localLease);
+        };
+    }, [ctx.cache, localDescriptor.viewKey, localQuery]);
+    // Stale-while-revalidate: render whatever the local IVM view already holds (synced rows,
+    // optimistic writes, partially-covered rows) rather than blanking to empty until the server
+    // confirms coverage. `status` (from useSyncQuery) stays a SEPARATE signal callers can gate on;
+    // the data itself never waits on the round-trip, so navigating to a view that's locally warm
+    // shows rows immediately instead of flashing a loading state. (Eviction-on-release still drops
+    // a cold view; a release TTL to keep views warm across nav is future work.)
+    const getSnapshot = useCallback(() => {
+        if (ctx.cache.serverResultType(descriptor.viewKey) === "complete") {
+            return projectLocalRootSnapshot(ctx.cache.serverSnapshot(descriptor.viewKey, descriptor.one), descriptor.one, projection);
+        }
+        return projectLocalRootSnapshot(ctx.cache.snapshot(localDescriptor.viewKey, descriptor.one), descriptor.one, projection);
+    }, [ctx.cache, descriptor.one, descriptor.viewKey, localDescriptor.viewKey, projection]);
+    const getServerSnapshot = useCallback(() => projectLocalRootSnapshot(ctx.cache.serverSnapshot(descriptor.viewKey, descriptor.one), descriptor.one, projection), [ctx.cache, descriptor.one, descriptor.viewKey, projection]);
+    return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
+function useRootRefData(query, fragment) {
+    const ctx = useRindleContext();
+    const descriptor = useMemo(() => describeQuery(query), [query]);
+    const ast = useMemo(() => localRootFragmentRefsAst(fragment, query, (table) => ctx.store.primaryKeyFor(table)), [ctx.store, fragment, query]);
+    const localQuery = useMemo(() => queryFromAst(ast), [ast]);
+    const localDescriptor = useMemo(() => describeQuery(localQuery), [localQuery]);
+    const projection = useMemo(() => new RootRefProjection(fragment, { key: descriptor.leaseKey, query }, (table) => ctx.store.primaryKeyFor(table)), [ctx.store, descriptor.leaseKey, fragment, query]);
+    const subscribe = useCallback((onStoreChange) => {
+        const localLease = ctx.cache.retain(localDescriptor.viewKey, localQuery);
+        const unsubscribeLocal = ctx.cache.subscribe(localDescriptor.viewKey, onStoreChange);
+        return () => {
+            unsubscribeLocal();
+            ctx.cache.release(localLease);
+        };
+    }, [ctx.cache, localDescriptor.viewKey, localQuery]);
+    // Stale-while-revalidate (see useLocalRootQueryData): the root rows render from the live local
+    // view as soon as it holds anything; `status` is the separate axis for "server-authoritative yet".
+    const getSnapshot = useCallback(() => {
+        if (ctx.cache.serverResultType(descriptor.viewKey) === "complete") {
+            return projectRootRefSnapshot(ctx.cache.serverSnapshot(descriptor.viewKey, descriptor.one), descriptor.one, projection);
+        }
+        const raw = ctx.cache.snapshot(localDescriptor.viewKey, descriptor.one);
+        return descriptor.one ? projection.projectOne(raw) : projection.projectMany(raw);
+    }, [ctx.cache, descriptor.one, descriptor.viewKey, localDescriptor.viewKey, projection]);
+    const getServerSnapshot = useCallback(() => projectRootRefSnapshot(ctx.cache.serverSnapshot(descriptor.viewKey, descriptor.one), descriptor.one, projection), [ctx.cache, descriptor.one, descriptor.viewKey, projection]);
+    return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
 /**
- * Read a {@link Fragment}'s slice off the shared root view (FRAGMENT-COMPOSITION-DESIGN.md §7).
+ * Read a {@link Fragment}'s local data from an opaque ref.
  *
- * The waterfall-free contract: the ROOT component `useQuery`s the composed query (every child
- * fragment spread into it), and every descendant calls `useFragment` — a PURE READ of the
- * already-projected node at this fragment's alias — instead of opening its own `useQuery`. So a
- * whole component tree resolves through the ONE query the root opened, with no request waterfall;
- * a descendant that opens its own `useQuery` reintroduces the waterfall at that boundary.
+ * The query boundary calls {@link useRoot} with a fragment argument to retain the full named
+ * coverage query and receive root refs. Descendants call `useFragment` with those refs (or child
+ * refs returned by a parent fragment read) to open narrow local-only reads for the fields their
+ * fragment owns.
  *
- * Phase 0 is a typed pass-through: `ref` already IS the projected node (the parent got it from
- * `useQuery` and handed the slice down), so this returns it typed as the fragment's
- * {@link FragmentRef}. `fragment` declares *which* selection this component reads (co-location +
- * the seam masking plugs into); masking (Phase 2) narrows the returned shape with no call-site
- * change. Not a subscription — it adds no lease and never re-renders on its own.
+ * `ref` is an opaque token created by {@link useRoot} or returned from another local fragment read.
+ * The hook opens a narrow local-only query for this exact fragment and keeps the root coverage
+ * lease retained while mounted. Passing a legacy projected data object is unsupported.
  */
 export function useFragment(fragment, ref) {
-    void fragment;
-    return ref;
+    return useLocalFragment(fragment, ref);
+}
+function useLocalFragment(fragment, ref) {
+    const ctx = useRindleContext();
+    const coverage = ref?.coverage;
+    const coverageDescriptor = useMemo(() => (coverage ? describeQuery(coverage.query) : undefined), [coverage]);
+    const ast = useMemo(() => (ref ? localFragmentReadAst(fragment, ref, (table) => ctx.store.primaryKeyFor(table)) : undefined), [ctx.store, fragment, ref]);
+    const query = useMemo(() => (ast ? queryFromAst(ast) : undefined), [ast]);
+    const descriptor = useMemo(() => (query ? describeQuery(query) : undefined), [query]);
+    const projection = useMemo(() => (coverage ? new LocalFragmentProjection(fragmentAst(fragment), coverage, (table) => ctx.store.primaryKeyFor(table)) : undefined), [ctx.store, coverage, fragment]);
+    const subscribe = useCallback((onStoreChange) => {
+        if (!coverage || !descriptor || !query)
+            return () => { };
+        const syncLease = ctx.syncCache.retain(coverage.key, coverage.query);
+        const localLease = ctx.cache.retain(descriptor.viewKey, query);
+        const unsubscribeSync = ctx.syncCache.subscribe(coverage.key, onStoreChange);
+        const unsubscribeLocal = ctx.cache.subscribe(descriptor.viewKey, onStoreChange);
+        return () => {
+            unsubscribeLocal();
+            unsubscribeSync();
+            ctx.cache.release(localLease);
+            ctx.syncCache.release(syncLease);
+        };
+    }, [ctx.cache, ctx.syncCache, coverage, descriptor, query]);
+    // Stale-while-revalidate (see useLocalRootQueryData): project the fragment's local view as soon
+    // as the row exists locally instead of returning null until its coverage is server-complete —
+    // otherwise every nested fragment (UserBadge, TagChip, CommentCard, …) flashes empty for a
+    // round-trip on each navigation. A field not yet synced simply reads absent, not "loading".
+    const getSnapshot = useCallback(() => {
+        if (!coverage || !descriptor || !projection)
+            return null;
+        if (coverageDescriptor && ctx.cache.serverResultType(coverageDescriptor.viewKey) === "complete") {
+            return projectFragmentSeed(ctx, coverage.query.ast(), coverageDescriptor, ref, projection);
+        }
+        const data = projection.project(ctx.cache.snapshot(descriptor.viewKey, true));
+        return data;
+    }, [ctx, coverage, coverageDescriptor, descriptor, projection, ref]);
+    const getServerSnapshot = useCallback(() => projectFragmentSeed(ctx, coverage?.query.ast(), coverageDescriptor, ref, projection), [ctx, coverage, coverageDescriptor, projection, ref]);
+    return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
+function projectRootRefSnapshot(raw, one, projection) {
+    return one ? projection.projectOne(raw) : projection.projectMany(raw);
+}
+function projectLocalRootSnapshot(raw, one, projection) {
+    return one ? projection.projectOne(raw) : projection.projectMany(raw);
+}
+function projectFragmentSeed(ctx, coverageAst, coverageDescriptor, ref, projection) {
+    if (!coverageAst || !coverageDescriptor || !ref || !projection)
+        return null;
+    const raw = ctx.cache.serverSnapshot(coverageDescriptor.viewKey, coverageDescriptor.one);
+    const row = findFragmentSeedRow(coverageAst, raw, ref.table, ref.pk, (table) => ctx.store.primaryKeyFor(table));
+    return projection.project(row);
+}
+function findFragmentSeedRow(ast, raw, table, pk, primaryKeyFor) {
+    if (Array.isArray(raw)) {
+        for (const row of raw) {
+            const found = findFragmentSeedRowInObject(ast, row, table, pk, primaryKeyFor);
+            if (found !== null)
+                return found;
+        }
+        return null;
+    }
+    return findFragmentSeedRowInObject(ast, raw, table, pk, primaryKeyFor);
+}
+function findFragmentSeedRowInObject(ast, raw, table, pk, primaryKeyFor) {
+    if (raw === null || raw === undefined || typeof raw !== "object")
+        return null;
+    const row = raw;
+    if (ast.table === table && rowMatchesPk(row, pk, primaryKeyFor(table)))
+        return row;
+    for (const rel of ast.related ?? []) {
+        if (rel.subquery.aggregate !== undefined)
+            continue;
+        const alias = rel.subquery.alias;
+        if (alias === undefined)
+            continue;
+        const found = findFragmentSeedRow(rel.subquery, row[alias], table, pk, primaryKeyFor);
+        if (found !== null)
+            return found;
+    }
+    return null;
+}
+function rowMatchesPk(row, pk, primaryKey) {
+    for (const col of primaryKey) {
+        if (!Object.prototype.hasOwnProperty.call(row, col))
+            return false;
+        if (stableKey(row[col]) !== stableKey(pk[col]))
+            return false;
+    }
+    return true;
+}
+class LocalFragmentProjection {
+    manyCache = new WeakMap();
+    cache = new WeakMap();
+    refCache = new Map();
+    ast;
+    coverage;
+    primaryKeyFor;
+    constructor(ast, coverage, primaryKeyFor) {
+        this.ast = ast;
+        this.coverage = coverage;
+        this.primaryKeyFor = primaryKeyFor;
+    }
+    projectOne(raw) {
+        return this.project(raw);
+    }
+    projectMany(raw) {
+        if (!Array.isArray(raw))
+            return EMPTY_ARRAY;
+        const cached = this.manyCache.get(raw);
+        if (cached)
+            return cached;
+        const out = raw.map((row) => this.project(row));
+        this.manyCache.set(raw, out);
+        return out;
+    }
+    project(raw) {
+        if (raw === null || raw === undefined || typeof raw !== "object")
+            return null;
+        const cached = this.cache.get(raw);
+        if (cached !== undefined)
+            return cached;
+        const out = this.projectRow(this.ast, raw);
+        this.cache.set(raw, out);
+        return out;
+    }
+    projectRow(ast, raw) {
+        if (raw === null || raw === undefined || typeof raw !== "object")
+            return null;
+        const row = raw;
+        const out = {};
+        const relationshipAliases = new Set((ast.related ?? []).map((rel) => rel.subquery.alias).filter((a) => a !== undefined));
+        if (ast.select === undefined) {
+            for (const [key, value] of Object.entries(row)) {
+                if (!relationshipAliases.has(key))
+                    out[key] = value;
+            }
+        }
+        else {
+            for (const col of ast.select) {
+                if (Object.prototype.hasOwnProperty.call(row, col))
+                    out[col] = row[col];
+            }
+        }
+        for (const rel of ast.related ?? []) {
+            const alias = rel.subquery.alias;
+            if (alias === undefined)
+                continue;
+            const value = row[alias];
+            if (rel.subquery.aggregate !== undefined) {
+                out[alias] = value;
+                continue;
+            }
+            out[alias] = isFragmentRelationship(rel) ? this.projectRelatedRefs(rel.subquery, value) : this.projectInline(rel.subquery, value);
+        }
+        return out;
+    }
+    projectInline(childAst, value) {
+        if (Array.isArray(value))
+            return value.map((row) => this.projectRow(childAst, row));
+        if (value === null || value === undefined)
+            return value ?? null;
+        return this.projectRow(childAst, value);
+    }
+    projectRelatedRefs(childAst, value) {
+        if (Array.isArray(value))
+            return value.map((row) => this.refForRow(childAst.table, row));
+        if (value === null || value === undefined)
+            return value ?? null;
+        return this.refForRow(childAst.table, value);
+    }
+    refForRow(table, value) {
+        if (value === null || typeof value !== "object") {
+            throw new Error(`useFragment(): cannot build a local fragment ref for "${table}" from a non-object row.`);
+        }
+        const row = value;
+        const pk = {};
+        for (const col of this.primaryKeyFor(table)) {
+            if (!Object.prototype.hasOwnProperty.call(row, col)) {
+                throw new Error(`useFragment(): local relationship row for "${table}" is missing primary key column "${col}".`);
+            }
+            pk[col] = row[col];
+        }
+        const key = stableKey({ table, pk });
+        const cached = this.refCache.get(key);
+        if (cached)
+            return cached;
+        const ref = createLocalFragmentRefForTable(table, pk, this.coverage);
+        this.refCache.set(key, ref);
+        return ref;
+    }
+}
+class RootRefProjection {
+    cache = new WeakMap();
+    rowCache = new WeakMap();
+    keyCache = new Map();
+    table;
+    coverage;
+    primaryKeyFor;
+    constructor(fragment, coverage, primaryKeyFor) {
+        this.table = tableMeta(fragment.table).name;
+        this.coverage = coverage;
+        this.primaryKeyFor = primaryKeyFor;
+    }
+    projectOne(raw) {
+        if (raw === null || raw === undefined)
+            return null;
+        return this.refForRow(raw);
+    }
+    projectMany(raw) {
+        if (!Array.isArray(raw))
+            return EMPTY_ARRAY;
+        const cached = this.cache.get(raw);
+        if (cached)
+            return cached;
+        const refs = raw.map((row) => this.refForRow(row));
+        this.cache.set(raw, refs);
+        return refs;
+    }
+    refForRow(value) {
+        if (value === null || typeof value !== "object") {
+            throw new Error(`useRoot(): cannot build a fragment ref for "${this.table}" from a non-object row.`);
+        }
+        const cached = this.rowCache.get(value);
+        if (cached)
+            return cached;
+        const row = value;
+        const pk = {};
+        for (const col of this.primaryKeyFor(this.table)) {
+            if (!Object.prototype.hasOwnProperty.call(row, col)) {
+                throw new Error(`useRoot(): local root row for "${this.table}" is missing primary key column "${col}".`);
+            }
+            pk[col] = row[col];
+        }
+        const key = stableKey({ table: this.table, pk });
+        const existing = this.keyCache.get(key);
+        if (existing) {
+            this.rowCache.set(value, existing);
+            return existing;
+        }
+        const ref = createLocalFragmentRefForTable(this.table, pk, this.coverage);
+        this.keyCache.set(key, ref);
+        this.rowCache.set(value, ref);
+        return ref;
+    }
+}
+export class SyncQueryCache {
+    entries = new Map();
+    nextLeaseId = 1;
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    retain(coverageKey, query) {
+        let entry = this.entries.get(coverageKey);
+        if (!entry) {
+            const handle = this.createHandle(query);
+            entry = {
+                handle,
+                leases: [],
+                listeners: new Set(),
+                unsubscribe: () => { },
+            };
+            entry.unsubscribe = handle.subscribe(() => {
+                for (const listener of entry.listeners)
+                    listener();
+            });
+            this.entries.set(coverageKey, entry);
+        }
+        const lease = { id: this.nextLeaseId++, coverageKey };
+        entry.leases.push(lease);
+        return lease;
+    }
+    release(lease) {
+        const entry = this.entries.get(lease.coverageKey);
+        if (!entry)
+            return;
+        const index = entry.leases.findIndex((l) => l.id === lease.id);
+        if (index < 0)
+            return;
+        entry.leases.splice(index, 1);
+        if (entry.leases.length > 0)
+            return;
+        entry.unsubscribe();
+        entry.handle.release();
+        this.entries.delete(lease.coverageKey);
+    }
+    subscribe(coverageKey, listener) {
+        const entry = this.entries.get(coverageKey);
+        if (!entry)
+            return () => { };
+        entry.listeners.add(listener);
+        return () => {
+            entry.listeners.delete(listener);
+        };
+    }
+    resultType(coverageKey) {
+        return this.entries.get(coverageKey)?.handle.resultType ?? "unknown";
+    }
+    size() {
+        return this.entries.size;
+    }
+    createHandle(query) {
+        if (this.store.canRetainRemoteQueries())
+            return this.store.retainSyncQuery(query);
+        const view = this.store.materialize(query);
+        return {
+            get resultType() {
+                return view.resultType;
+            },
+            subscribe: (listener) => view.subscribe(listener),
+            release: () => view.destroy(),
+        };
+    }
 }
 export class QueryCache {
     entries = new Map();