@gaganref/confect-react 10.3.1-fork.3 → 10.3.1-fork.31

package/dist/StreamPagination.d.ts

@@ -13,7 +13,9 @@
  * Pinning a freshly loaded page, loading more, and splitting an overgrown page
  * are the same transition shape: the affected page keeps rendering while its
  * replacement subscriptions ("ongoing split") load, and is swapped out once all
- * of them have results.
+ * of them have results. A failed replacement fails the render at once, still
+ * showing the affected page and the pages after it, and the swap waits for a
+ * retry.
  *
  * This module is framework-free (it imports only `effect/*` and a type from
  * `convex/server`); it lives here for now because the React hook is its only
@@ -116,9 +118,14 @@ export type Results = Record.ReadonlyRecord<string, PageResult | Error | undefin
 export type PageResult = PaginationResult<unknown>;
 /**
  * What one render pass derives from the subscribed pages' results: the items to
- * show, the trailing complete result (absent while the tail is loading or
- * force-splitting), state transitions to apply, and whether a failure or an
- * invalid cursor was hit.
+ * show, whether the first page has loaded, the trailing complete result (absent
+ * while the tail is loading or force-splitting), state transitions to apply
+ * (also while a failure shows, so the other pages keep splitting and swapping),
+ * and whether a failure or an invalid cursor was hit.
+ *
+ * `firstPageLoaded` holds once the head page has its full result. Splits can
+ * leave several pages ahead of the first loaded item, so neither the item count
+ * nor the page count tells a loading first page apart from a loaded empty one.
  */
 export type Interpretation = {
     readonly _tag: "ResetRequired";
@@ -126,15 +133,21 @@ export type Interpretation = {
     readonly _tag: "Failed";
     readonly error: unknown;
     /**
-     * Encoded items loaded before the failing page.
+     * Encoded items across the loaded pages, in order. A page whose
+     * replacement failed is still shown, and stays subscribed with the
+     * replacement so that a retry re-requests only the replacement. A page
+     * whose own result failed ends the items, since its range is unknown.
      */
     readonly items: ReadonlyArray<unknown>;
+    readonly firstPageLoaded: boolean;
+    readonly transitions: ReadonlyArray<(state: State) => State>;
 } | {
     readonly _tag: "Interpreted";
     /**
      * Encoded items across the loaded pages, in order.
      */
     readonly items: ReadonlyArray<unknown>;
+    readonly firstPageLoaded: boolean;
     /**
      * The last page's result, when every page has loaded completely.
      */

package/dist/StreamPagination.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"StreamPagination.d.ts","sourceRoot":"","sources":["../src/StreamPagination.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"StreamPagination.d.ts","sourceRoot":"","sources":["../src/StreamPagination.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChD;AAoBD,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACzC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC3D;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;CAC9E;AAED;;GAEG;AACH,eAAO,MAAM,KAAK,EAAE,KAKnB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,OAAO,oBACD,MAAM,WACf,UAAU,KACjB,KAKD,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,GAAG,QACR,MAAM,aAAa,MAAM,KAAG,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,KAAK,CAmBtD,CAAC;AAEP;;;;GAIG;AACH,eAAO,MAAM,QAAQ,mBAED,MAAM,YACZ,MAAM,WACR,UAAU,KACjB,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,KAAK,CA8CxB,CAAC;AAEN;;;;;GAKG;AACH,eAAO,MAAM,KAAK,QACV,MAAM,eAAe,MAAM,KAAG,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,KAAK,CAqBxD,CAAC;AAEP;;GAEG;AACH,eAAO,MAAM,aAAa,QAClB,MAAM,KAAG,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,KAAK,CAYnC,CAAC;AAEP;;GAEG;AACH,eAAO,MAAM,mBAAmB,UAAW,KAAK,KAAG,OAGhD,CAAC;AAEJ;;GAEG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,SACrB,KAAK,KACT,CAAC,IAAI,EAAE,WAAW,KAAK,CAAC,KAC1B,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,CAAC,CAA+B,CAAC;AAElE;;GAEG;AACH,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,cAAc,CACzC,MAAM,EACN,UAAU,GAAG,KAAK,GAAG,SAAS,CAC/B,CAAC;AAMF;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;AAEnD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;CAAE,GAClC;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IACvC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,KAAK,CAAC,CAAC;CAC9D,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IACvC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAC/C;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,KAAK,CAAC,CAAC;CAC9D,CAAC;AAEN;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,UACb,KAAK,WACH,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,KAAK,GAAG,SAAS,CAAC,WAC7D;IACP,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,oBAAoB,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;CAC1D,KACA,cA4HF,CAAC"}

package/dist/StreamPagination.js

@@ -140,12 +140,6 @@ const isLastPageSplitting = (state) => Option.exists(Array.last(state.pageKeys),
 * Build one subscription request per subscribed page.
 */
 const pageRequests = (state, f) => Record.map(state.pages, f);
-const interpreted = (items, lastResult, transitions) => ({
-	_tag: "Interpreted",
-	items,
-	lastResult,
-	transitions
-});
 /**
 * Walk the pages in display order, concatenating their items and collecting the
 * transitions to apply (completed split swaps, recommended splits, eager splits
@@ -155,26 +149,48 @@ const interpreted = (items, lastResult, transitions) => ({
 * rather than a failure (the cursor no longer matches the query).
 */
 const interpret = (state, results, options) => {
-	const go = (remaining, items, transitions, lastResult) => Option.match(Array.head(remaining), {
-		onNone: () => interpreted(items, lastResult, transitions),
+	const resultOf = (key) => Record.get(results, key).pipe(Option.flatMap(Option.fromNullishOr), Option.getOrUndefined);
+	const firstPageLoaded = Option.exists(Array.head(state.pageKeys), (key) => {
+		const result = resultOf(key);
+		return result !== void 0 && !(result instanceof Error) && result.pageStatus !== "SplitRequired";
+	});
+	const finish = (items, lastResult, transitions, errors) => Array.some(errors, options.isInvalidCursorError) ? { _tag: "ResetRequired" } : Option.match(Array.head(errors), {
+		onNone: () => ({
+			_tag: "Interpreted",
+			items,
+			firstPageLoaded,
+			lastResult,
+			transitions
+		}),
+		onSome: (error) => ({
+			_tag: "Failed",
+			error,
+			items,
+			firstPageLoaded,
+			transitions
+		})
+	});
+	const go = (remaining, items, transitions, lastResult, errors) => Option.match(Array.head(remaining), {
+		onNone: () => finish(items, lastResult, transitions, errors),
 		onSome: (pageKey) => {
-			const result = Record.get(results, pageKey).pipe(Option.flatMap(Option.fromNullishOr), Option.getOrUndefined);
-			if (result === void 0) return interpreted(items, Option.none(), transitions);
-			if (result instanceof Error) return options.isInvalidCursorError(result) ? { _tag: "ResetRequired" } : {
-				_tag: "Failed",
-				error: result,
-				items
-			};
-			const hasResult = (key) => Record.get(results, key).pipe(Option.flatMap(Option.fromNullishOr), Option.isSome);
+			const result = resultOf(pageKey);
+			if (result === void 0) return finish(items, Option.none(), transitions, errors);
+			if (result instanceof Error) return finish(items, Option.none(), transitions, Array.append(errors, result));
+			const shown = result.pageStatus === "SplitRequired" ? items : Array.appendAll(items, result.page);
 			const ongoingSplit = Record.get(state.ongoingSplits, pageKey);
+			const replacementResults = Option.match(ongoingSplit, {
+				onNone: () => [],
+				onSome: Array.map(resultOf)
+			});
+			const nextErrors = Array.appendAll(errors, Array.filter(replacementResults, (replacement) => replacement instanceof Error));
 			const nextTransitions = Option.match(ongoingSplit, {
-				onSome: (replacements) => Array.every(replacements, hasResult) ? Array.append(transitions, completeSplit(pageKey)) : transitions,
+				onSome: () => Array.every(replacementResults, (replacement) => replacement !== void 0 && !(replacement instanceof Error)) ? Array.append(transitions, completeSplit(pageKey)) : transitions,
 				onNone: () => typeof result.splitCursor === "string" && (result.pageStatus === "SplitRecommended" || result.pageStatus === "SplitRequired" || result.page.length > options.initialNumItems) ? Array.append(transitions, split(pageKey, result.splitCursor)) : Option.exists(Record.get(state.pages, pageKey), (request) => request.endCursor === void 0) && result.pageStatus !== "SplitRequired" ? Array.append(transitions, pin(pageKey, result.continueCursor)) : transitions
 			});
-			return result.pageStatus === "SplitRequired" ? interpreted(items, Option.none(), nextTransitions) : go(Array.drop(remaining, 1), Array.appendAll(items, result.page), nextTransitions, Option.some(result));
+			return result.pageStatus === "SplitRequired" ? finish(shown, Option.none(), nextTransitions, nextErrors) : go(Array.drop(remaining, 1), shown, nextTransitions, Option.some(result), nextErrors);
 		}
 	});
-	return go(state.pageKeys, [], [], Option.none());
+	return go(state.pageKeys, [], [], Option.none(), []);
 };
 //#endregion
 export { StreamPagination_exports, completeSplit, empty, initial, interpret, isLastPageSplitting, loadMore, pageRequests, pin, split };

package/dist/StreamPagination.js.map

@@ -1 +1 @@
-{"version":3,"file":"StreamPagination.js","names":[],"sources":["../src/StreamPagination.ts"],"sourcesContent":["/**\n * EXPERIMENTAL—the pure state machine behind {@link useStreamPaginatedQuery}\n * (see `notes/stream-based-querying.md` in the repo root).\n *\n * Reactive pagination without the query journal: every loaded page—including\n * the first—is pinned to a fixed index range by echoing its `continueCursor`\n * back as the next subscription's `endCursor` (the last page pins to the\n * end-of-stream sentinel once exhausted), so adjacent pages stay exactly\n * contiguous and pages never shed items as data changes—the \"range-defined\n * pages\" the Fully Reactive Pagination article calls for, and the mechanism of\n * `convex-helpers/react`'s `usePaginatedQuery`.\n *\n * Pinning a freshly loaded page, loading more, and splitting an overgrown page\n * are the same transition shape: the affected page keeps rendering while its\n * replacement subscriptions (\"ongoing split\") load, and is swapped out once all\n * of them have results.\n *\n * This module is framework-free (it imports only `effect/*` and a type from\n * `convex/server`); it lives here for now because the React hook is its only\n * consumer—a second client (e.g. `@confect/foldkit`) should prompt a move down\n * to `@confect/js`.\n */\nimport type { PaginationResult } from \"convex/server\";\nimport * as Array from \"effect/Array\";\nimport * as Option from \"effect/Option\";\nimport { pipe } from \"effect/Function\";\nimport * as Record from \"effect/Record\";\n\n/**\n * The `paginationOpts` one subscribed page queries with.\n */\nexport interface PageRequest {\n  readonly numItems: number;\n  readonly cursor: string | null;\n  /**\n   * Present once the page is pinned to a fixed range.\n   */\n  readonly endCursor?: string;\n  /**\n   * Per-page read budgets, forwarded to the server so a scan-heavy page fails\n   * over to `SplitRequired` instead of exceeding query limits.\n   */\n  readonly maximumRowsRead?: number;\n  readonly maximumBytesRead?: number;\n}\n\n/**\n * The per-page read budgets every growing page is requested with.\n */\nexport interface ReadBudget {\n  readonly maximumRowsRead?: number | undefined;\n  readonly maximumBytesRead?: number | undefined;\n}\n\n/**\n * A fresh growing-page request (no `endCursor`).\n */\nconst growingRequest = (\n  numItems: number,\n  cursor: string | null,\n  budget: ReadBudget,\n): PageRequest => ({\n  numItems,\n  cursor,\n  ...(budget.maximumRowsRead === undefined\n    ? {}\n    : { maximumRowsRead: budget.maximumRowsRead }),\n  ...(budget.maximumBytesRead === undefined\n    ? {}\n    : { maximumBytesRead: budget.maximumBytesRead }),\n});\n\nexport interface State {\n  readonly nextPageKey: number;\n  /**\n   * Page keys in display order.\n   */\n  readonly pageKeys: ReadonlyArray<string>;\n  /**\n   * The request each subscribed page queries with, by page key.\n   */\n  readonly pages: Record.ReadonlyRecord<string, PageRequest>;\n  /**\n   * Pages being replaced by one (a pin) or two (a split) narrower\n   * subscriptions: the original stays subscribed (and rendered) until every\n   * replacement has a result.\n   */\n  readonly ongoingSplits: Record.ReadonlyRecord<string, ReadonlyArray<string>>;\n}\n\n/**\n * The skipped state: nothing subscribed.\n */\nexport const empty: State = {\n  nextPageKey: 0,\n  pageKeys: [],\n  pages: Record.empty(),\n  ongoingSplits: Record.empty(),\n};\n\n/**\n * One growing (unpinned) page from the start of the stream.\n */\nexport const initial = (\n  initialNumItems: number,\n  budget: ReadBudget = {},\n): State => ({\n  nextPageKey: 1,\n  pageKeys: [\"0\"],\n  pages: Record.singleton(\"0\", growingRequest(initialNumItems, null, budget)),\n  ongoingSplits: Record.empty(),\n});\n\n/**\n * Pin a freshly loaded growing page at its `continueCursor` (or, once\n * exhausted, at the end-of-stream sentinel), so it stops being a sliding\n * window: a pinned page grows and shrinks with the data in its range but never\n * sheds items past its edges. Modeled as a one-replacement split so the\n * original keeps rendering until the pinned twin has a result.\n */\nexport const pin =\n  (key: string, endCursor: string): ((state: State) => State) =>\n  (state) =>\n    Option.match(Record.get(state.pages, key), {\n      onNone: () => state,\n      onSome: (page) => {\n        if (\n          page.endCursor !== undefined ||\n          Record.has(state.ongoingSplits, key)\n        ) {\n          return state;\n        }\n        const pinnedKey = String(state.nextPageKey);\n        return {\n          nextPageKey: state.nextPageKey + 1,\n          pageKeys: state.pageKeys,\n          pages: Record.set(state.pages, pinnedKey, { ...page, endCursor }),\n          ongoingSplits: Record.set(state.ongoingSplits, key, [pinnedKey]),\n        };\n      },\n    });\n\n/**\n * Pin the growing last page at `continueCursor` and start a new growing page\n * from there. Modeled as a split of the last page into its pinned replacement\n * and the new page, so the swap waits for both.\n */\nexport const loadMore =\n  (\n    continueCursor: string,\n    numItems: number,\n    budget: ReadBudget = {},\n  ): ((state: State) => State) =>\n  (state) =>\n    pipe(\n      Option.Do,\n      Option.bind(\"lastKey\", () => Array.last(state.pageKeys)),\n      Option.bind(\"lastPage\", ({ lastKey }) =>\n        Record.get(state.pages, lastKey),\n      ),\n      Option.match({\n        onNone: () => state,\n        onSome: ({ lastKey, lastPage }) => {\n          if (lastPage.endCursor !== undefined) {\n            // The last page is already pinned (the usual case, since pages\n            // pin themselves on first load): just append a new growing page.\n            const nextKey = String(state.nextPageKey);\n            return {\n              nextPageKey: state.nextPageKey + 1,\n              pageKeys: Array.append(state.pageKeys, nextKey),\n              pages: Record.set(\n                state.pages,\n                nextKey,\n                growingRequest(numItems, continueCursor, budget),\n              ),\n              ongoingSplits: state.ongoingSplits,\n            };\n          }\n          const pinnedKey = String(state.nextPageKey);\n          const nextKey = String(state.nextPageKey + 1);\n          return {\n            nextPageKey: state.nextPageKey + 2,\n            pageKeys: state.pageKeys,\n            pages: pipe(\n              state.pages,\n              Record.set(pinnedKey, { ...lastPage, endCursor: continueCursor }),\n              Record.set(\n                nextKey,\n                growingRequest(numItems, continueCursor, budget),\n              ),\n            ),\n            ongoingSplits: Record.set(state.ongoingSplits, lastKey, [\n              pinnedKey,\n              nextKey,\n            ]),\n          };\n        },\n      }),\n    );\n\n/**\n * Split the page at `key` in two at `splitCursor`. The first replacement pins\n * at the split point; the second keeps the page's own `endCursor`—for a pinned\n * page its original end (so a truncated `SplitRequired` page loses none of its\n * range), and for a growing page no end at all (it keeps growing).\n */\nexport const split =\n  (key: string, splitCursor: string): ((state: State) => State) =>\n  (state) =>\n    Option.match(Record.get(state.pages, key), {\n      onNone: () => state,\n      onSome: (page) => {\n        const firstKey = String(state.nextPageKey);\n        const secondKey = String(state.nextPageKey + 1);\n        return {\n          nextPageKey: state.nextPageKey + 2,\n          pageKeys: state.pageKeys,\n          pages: pipe(\n            state.pages,\n            Record.set(firstKey, { ...page, endCursor: splitCursor }),\n            Record.set(secondKey, { ...page, cursor: splitCursor }),\n          ),\n          ongoingSplits: Record.set(state.ongoingSplits, key, [\n            firstKey,\n            secondKey,\n          ]),\n        };\n      },\n    });\n\n/**\n * Swap a completed split's replacements in for the original page.\n */\nexport const completeSplit =\n  (key: string): ((state: State) => State) =>\n  (state) =>\n    Option.match(Record.get(state.ongoingSplits, key), {\n      onNone: () => state,\n      onSome: (replacements) => ({\n        nextPageKey: state.nextPageKey,\n        pageKeys: Array.flatMap(state.pageKeys, (pageKey) =>\n          pageKey === key ? replacements : [pageKey],\n        ),\n        pages: Record.remove(state.pages, key),\n        ongoingSplits: Record.remove(state.ongoingSplits, key),\n      }),\n    });\n\n/**\n * Whether the last (rendered) page is currently being split or pinned.\n */\nexport const isLastPageSplitting = (state: State): boolean =>\n  Option.exists(Array.last(state.pageKeys), (lastKey) =>\n    Record.has(state.ongoingSplits, lastKey),\n  );\n\n/**\n * Build one subscription request per subscribed page.\n */\nexport const pageRequests = <A>(\n  state: State,\n  f: (page: PageRequest) => A,\n): Record.ReadonlyRecord<string, A> => Record.map(state.pages, f);\n\n/**\n * The per-page results a render observes, keyed like {@link pageRequests}.\n */\nexport type Results = Record.ReadonlyRecord<\n  string,\n  PageResult | Error | undefined\n>;\n\n// -----------------------------------------------------------------------------\n// Interpretation\n// -----------------------------------------------------------------------------\n\n/**\n * The wire shape of one loaded page—`PaginationResult` from `convex/server`, so\n * the protocol has a single source of truth.\n */\nexport type PageResult = PaginationResult<unknown>;\n\n/**\n * What one render pass derives from the subscribed pages' results: the items to\n * show, the trailing complete result (absent while the tail is loading or\n * force-splitting), state transitions to apply, and whether a failure or an\n * invalid cursor was hit.\n */\nexport type Interpretation =\n  | { readonly _tag: \"ResetRequired\" }\n  | {\n      readonly _tag: \"Failed\";\n      readonly error: unknown;\n      /**\n       * Encoded items loaded before the failing page.\n       */\n      readonly items: ReadonlyArray<unknown>;\n    }\n  | {\n      readonly _tag: \"Interpreted\";\n      /**\n       * Encoded items across the loaded pages, in order.\n       */\n      readonly items: ReadonlyArray<unknown>;\n      /**\n       * The last page's result, when every page has loaded completely.\n       */\n      readonly lastResult: Option.Option<PageResult>;\n      /**\n       * Split/swap transitions this render discovered.\n       */\n      readonly transitions: ReadonlyArray<(state: State) => State>;\n    };\n\nconst interpreted = (\n  items: ReadonlyArray<unknown>,\n  lastResult: Option.Option<PageResult>,\n  transitions: ReadonlyArray<(state: State) => State>,\n): Interpretation => ({ _tag: \"Interpreted\", items, lastResult, transitions });\n\n/**\n * Walk the pages in display order, concatenating their items and collecting the\n * transitions to apply (completed split swaps, recommended splits, eager splits\n * of pages that outgrew `initialNumItems`).\n *\n * `isInvalidCursorError` marks errors that call for a full pagination reset\n * rather than a failure (the cursor no longer matches the query).\n */\nexport const interpret = (\n  state: State,\n  results: Record.ReadonlyRecord<string, PageResult | Error | undefined>,\n  options: {\n    readonly initialNumItems: number;\n    readonly isInvalidCursorError: (error: Error) => boolean;\n  },\n): Interpretation => {\n  const go = (\n    remaining: ReadonlyArray<string>,\n    items: ReadonlyArray<unknown>,\n    transitions: ReadonlyArray<(s: State) => State>,\n    lastResult: Option.Option<PageResult>,\n  ): Interpretation =>\n    Option.match(Array.head(remaining), {\n      onNone: () => interpreted(items, lastResult, transitions),\n      onSome: (pageKey) => {\n        const result = Record.get(results, pageKey).pipe(\n          Option.flatMap(Option.fromNullishOr),\n          Option.getOrUndefined,\n        );\n        if (result === undefined) {\n          // The trailing pages are still loading.\n          return interpreted(items, Option.none(), transitions);\n        }\n        if (result instanceof Error) {\n          return options.isInvalidCursorError(result)\n            ? { _tag: \"ResetRequired\" }\n            : { _tag: \"Failed\", error: result, items };\n        }\n\n        const hasResult = (key: string) =>\n          Record.get(results, key).pipe(\n            Option.flatMap(Option.fromNullishOr),\n            Option.isSome,\n          );\n        const ongoingSplit = Record.get(state.ongoingSplits, pageKey);\n        const nextTransitions = Option.match(ongoingSplit, {\n          onSome: (replacements) =>\n            // Swap the replacements in once all of them have results.\n            Array.every(replacements, hasResult)\n              ? Array.append(transitions, completeSplit(pageKey))\n              : transitions,\n          onNone: () =>\n            typeof result.splitCursor === \"string\" &&\n            (result.pageStatus === \"SplitRecommended\" ||\n              result.pageStatus === \"SplitRequired\" ||\n              result.page.length > options.initialNumItems)\n              ? Array.append(transitions, split(pageKey, result.splitCursor))\n              : // A loaded growing page pins itself to the range it just\n                // served (`END_CURSOR` once exhausted), so it stops being a\n                // sliding window that sheds items as new documents arrive.\n                Option.exists(\n                    Record.get(state.pages, pageKey),\n                    (request) => request.endCursor === undefined,\n                  ) && result.pageStatus !== \"SplitRequired\"\n                ? Array.append(transitions, pin(pageKey, result.continueCursor))\n                : transitions,\n        });\n\n        // A force-split page couldn't be fetched in full: show the items\n        // before it and report the tail as still loading.\n        return result.pageStatus === \"SplitRequired\"\n          ? interpreted(items, Option.none(), nextTransitions)\n          : go(\n              Array.drop(remaining, 1),\n              Array.appendAll(items, result.page),\n              nextTransitions,\n              Option.some(result),\n            );\n      },\n    });\n\n  return go(state.pageKeys, [], [], Option.none());\n};\n"],"mappings":"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"}
+{"version":3,"file":"StreamPagination.js","names":[],"sources":["../src/StreamPagination.ts"],"sourcesContent":["/**\n * EXPERIMENTAL—the pure state machine behind {@link useStreamPaginatedQuery}\n * (see `notes/stream-based-querying.md` in the repo root).\n *\n * Reactive pagination without the query journal: every loaded page—including\n * the first—is pinned to a fixed index range by echoing its `continueCursor`\n * back as the next subscription's `endCursor` (the last page pins to the\n * end-of-stream sentinel once exhausted), so adjacent pages stay exactly\n * contiguous and pages never shed items as data changes—the \"range-defined\n * pages\" the Fully Reactive Pagination article calls for, and the mechanism of\n * `convex-helpers/react`'s `usePaginatedQuery`.\n *\n * Pinning a freshly loaded page, loading more, and splitting an overgrown page\n * are the same transition shape: the affected page keeps rendering while its\n * replacement subscriptions (\"ongoing split\") load, and is swapped out once all\n * of them have results. A failed replacement fails the render at once, still\n * showing the affected page and the pages after it, and the swap waits for a\n * retry.\n *\n * This module is framework-free (it imports only `effect/*` and a type from\n * `convex/server`); it lives here for now because the React hook is its only\n * consumer—a second client (e.g. `@confect/foldkit`) should prompt a move down\n * to `@confect/js`.\n */\nimport type { PaginationResult } from \"convex/server\";\nimport * as Array from \"effect/Array\";\nimport * as Option from \"effect/Option\";\nimport { pipe } from \"effect/Function\";\nimport * as Record from \"effect/Record\";\n\n/**\n * The `paginationOpts` one subscribed page queries with.\n */\nexport interface PageRequest {\n  readonly numItems: number;\n  readonly cursor: string | null;\n  /**\n   * Present once the page is pinned to a fixed range.\n   */\n  readonly endCursor?: string;\n  /**\n   * Per-page read budgets, forwarded to the server so a scan-heavy page fails\n   * over to `SplitRequired` instead of exceeding query limits.\n   */\n  readonly maximumRowsRead?: number;\n  readonly maximumBytesRead?: number;\n}\n\n/**\n * The per-page read budgets every growing page is requested with.\n */\nexport interface ReadBudget {\n  readonly maximumRowsRead?: number | undefined;\n  readonly maximumBytesRead?: number | undefined;\n}\n\n/**\n * A fresh growing-page request (no `endCursor`).\n */\nconst growingRequest = (\n  numItems: number,\n  cursor: string | null,\n  budget: ReadBudget,\n): PageRequest => ({\n  numItems,\n  cursor,\n  ...(budget.maximumRowsRead === undefined\n    ? {}\n    : { maximumRowsRead: budget.maximumRowsRead }),\n  ...(budget.maximumBytesRead === undefined\n    ? {}\n    : { maximumBytesRead: budget.maximumBytesRead }),\n});\n\nexport interface State {\n  readonly nextPageKey: number;\n  /**\n   * Page keys in display order.\n   */\n  readonly pageKeys: ReadonlyArray<string>;\n  /**\n   * The request each subscribed page queries with, by page key.\n   */\n  readonly pages: Record.ReadonlyRecord<string, PageRequest>;\n  /**\n   * Pages being replaced by one (a pin) or two (a split) narrower\n   * subscriptions: the original stays subscribed (and rendered) until every\n   * replacement has a result.\n   */\n  readonly ongoingSplits: Record.ReadonlyRecord<string, ReadonlyArray<string>>;\n}\n\n/**\n * The skipped state: nothing subscribed.\n */\nexport const empty: State = {\n  nextPageKey: 0,\n  pageKeys: [],\n  pages: Record.empty(),\n  ongoingSplits: Record.empty(),\n};\n\n/**\n * One growing (unpinned) page from the start of the stream.\n */\nexport const initial = (\n  initialNumItems: number,\n  budget: ReadBudget = {},\n): State => ({\n  nextPageKey: 1,\n  pageKeys: [\"0\"],\n  pages: Record.singleton(\"0\", growingRequest(initialNumItems, null, budget)),\n  ongoingSplits: Record.empty(),\n});\n\n/**\n * Pin a freshly loaded growing page at its `continueCursor` (or, once\n * exhausted, at the end-of-stream sentinel), so it stops being a sliding\n * window: a pinned page grows and shrinks with the data in its range but never\n * sheds items past its edges. Modeled as a one-replacement split so the\n * original keeps rendering until the pinned twin has a result.\n */\nexport const pin =\n  (key: string, endCursor: string): ((state: State) => State) =>\n  (state) =>\n    Option.match(Record.get(state.pages, key), {\n      onNone: () => state,\n      onSome: (page) => {\n        if (\n          page.endCursor !== undefined ||\n          Record.has(state.ongoingSplits, key)\n        ) {\n          return state;\n        }\n        const pinnedKey = String(state.nextPageKey);\n        return {\n          nextPageKey: state.nextPageKey + 1,\n          pageKeys: state.pageKeys,\n          pages: Record.set(state.pages, pinnedKey, { ...page, endCursor }),\n          ongoingSplits: Record.set(state.ongoingSplits, key, [pinnedKey]),\n        };\n      },\n    });\n\n/**\n * Pin the growing last page at `continueCursor` and start a new growing page\n * from there. Modeled as a split of the last page into its pinned replacement\n * and the new page, so the swap waits for both.\n */\nexport const loadMore =\n  (\n    continueCursor: string,\n    numItems: number,\n    budget: ReadBudget = {},\n  ): ((state: State) => State) =>\n  (state) =>\n    pipe(\n      Option.Do,\n      Option.bind(\"lastKey\", () => Array.last(state.pageKeys)),\n      Option.bind(\"lastPage\", ({ lastKey }) =>\n        Record.get(state.pages, lastKey),\n      ),\n      Option.match({\n        onNone: () => state,\n        onSome: ({ lastKey, lastPage }) => {\n          if (lastPage.endCursor !== undefined) {\n            // The last page is already pinned (the usual case, since pages\n            // pin themselves on first load): just append a new growing page.\n            const nextKey = String(state.nextPageKey);\n            return {\n              nextPageKey: state.nextPageKey + 1,\n              pageKeys: Array.append(state.pageKeys, nextKey),\n              pages: Record.set(\n                state.pages,\n                nextKey,\n                growingRequest(numItems, continueCursor, budget),\n              ),\n              ongoingSplits: state.ongoingSplits,\n            };\n          }\n          const pinnedKey = String(state.nextPageKey);\n          const nextKey = String(state.nextPageKey + 1);\n          return {\n            nextPageKey: state.nextPageKey + 2,\n            pageKeys: state.pageKeys,\n            pages: pipe(\n              state.pages,\n              Record.set(pinnedKey, { ...lastPage, endCursor: continueCursor }),\n              Record.set(\n                nextKey,\n                growingRequest(numItems, continueCursor, budget),\n              ),\n            ),\n            ongoingSplits: Record.set(state.ongoingSplits, lastKey, [\n              pinnedKey,\n              nextKey,\n            ]),\n          };\n        },\n      }),\n    );\n\n/**\n * Split the page at `key` in two at `splitCursor`. The first replacement pins\n * at the split point; the second keeps the page's own `endCursor`—for a pinned\n * page its original end (so a truncated `SplitRequired` page loses none of its\n * range), and for a growing page no end at all (it keeps growing).\n */\nexport const split =\n  (key: string, splitCursor: string): ((state: State) => State) =>\n  (state) =>\n    Option.match(Record.get(state.pages, key), {\n      onNone: () => state,\n      onSome: (page) => {\n        const firstKey = String(state.nextPageKey);\n        const secondKey = String(state.nextPageKey + 1);\n        return {\n          nextPageKey: state.nextPageKey + 2,\n          pageKeys: state.pageKeys,\n          pages: pipe(\n            state.pages,\n            Record.set(firstKey, { ...page, endCursor: splitCursor }),\n            Record.set(secondKey, { ...page, cursor: splitCursor }),\n          ),\n          ongoingSplits: Record.set(state.ongoingSplits, key, [\n            firstKey,\n            secondKey,\n          ]),\n        };\n      },\n    });\n\n/**\n * Swap a completed split's replacements in for the original page.\n */\nexport const completeSplit =\n  (key: string): ((state: State) => State) =>\n  (state) =>\n    Option.match(Record.get(state.ongoingSplits, key), {\n      onNone: () => state,\n      onSome: (replacements) => ({\n        nextPageKey: state.nextPageKey,\n        pageKeys: Array.flatMap(state.pageKeys, (pageKey) =>\n          pageKey === key ? replacements : [pageKey],\n        ),\n        pages: Record.remove(state.pages, key),\n        ongoingSplits: Record.remove(state.ongoingSplits, key),\n      }),\n    });\n\n/**\n * Whether the last (rendered) page is currently being split or pinned.\n */\nexport const isLastPageSplitting = (state: State): boolean =>\n  Option.exists(Array.last(state.pageKeys), (lastKey) =>\n    Record.has(state.ongoingSplits, lastKey),\n  );\n\n/**\n * Build one subscription request per subscribed page.\n */\nexport const pageRequests = <A>(\n  state: State,\n  f: (page: PageRequest) => A,\n): Record.ReadonlyRecord<string, A> => Record.map(state.pages, f);\n\n/**\n * The per-page results a render observes, keyed like {@link pageRequests}.\n */\nexport type Results = Record.ReadonlyRecord<\n  string,\n  PageResult | Error | undefined\n>;\n\n// -----------------------------------------------------------------------------\n// Interpretation\n// -----------------------------------------------------------------------------\n\n/**\n * The wire shape of one loaded page—`PaginationResult` from `convex/server`, so\n * the protocol has a single source of truth.\n */\nexport type PageResult = PaginationResult<unknown>;\n\n/**\n * What one render pass derives from the subscribed pages' results: the items to\n * show, whether the first page has loaded, the trailing complete result (absent\n * while the tail is loading or force-splitting), state transitions to apply\n * (also while a failure shows, so the other pages keep splitting and swapping),\n * and whether a failure or an invalid cursor was hit.\n *\n * `firstPageLoaded` holds once the head page has its full result. Splits can\n * leave several pages ahead of the first loaded item, so neither the item count\n * nor the page count tells a loading first page apart from a loaded empty one.\n */\nexport type Interpretation =\n  | { readonly _tag: \"ResetRequired\" }\n  | {\n      readonly _tag: \"Failed\";\n      readonly error: unknown;\n      /**\n       * Encoded items across the loaded pages, in order. A page whose\n       * replacement failed is still shown, and stays subscribed with the\n       * replacement so that a retry re-requests only the replacement. A page\n       * whose own result failed ends the items, since its range is unknown.\n       */\n      readonly items: ReadonlyArray<unknown>;\n      readonly firstPageLoaded: boolean;\n      readonly transitions: ReadonlyArray<(state: State) => State>;\n    }\n  | {\n      readonly _tag: \"Interpreted\";\n      /**\n       * Encoded items across the loaded pages, in order.\n       */\n      readonly items: ReadonlyArray<unknown>;\n      readonly firstPageLoaded: boolean;\n      /**\n       * The last page's result, when every page has loaded completely.\n       */\n      readonly lastResult: Option.Option<PageResult>;\n      /**\n       * Split/swap transitions this render discovered.\n       */\n      readonly transitions: ReadonlyArray<(state: State) => State>;\n    };\n\n/**\n * Walk the pages in display order, concatenating their items and collecting the\n * transitions to apply (completed split swaps, recommended splits, eager splits\n * of pages that outgrew `initialNumItems`).\n *\n * `isInvalidCursorError` marks errors that call for a full pagination reset\n * rather than a failure (the cursor no longer matches the query).\n */\nexport const interpret = (\n  state: State,\n  results: Record.ReadonlyRecord<string, PageResult | Error | undefined>,\n  options: {\n    readonly initialNumItems: number;\n    readonly isInvalidCursorError: (error: Error) => boolean;\n  },\n): Interpretation => {\n  const resultOf = (key: string) =>\n    Record.get(results, key).pipe(\n      Option.flatMap(Option.fromNullishOr),\n      Option.getOrUndefined,\n    );\n  const firstPageLoaded = Option.exists(Array.head(state.pageKeys), (key) => {\n    const result = resultOf(key);\n    return (\n      result !== undefined &&\n      !(result instanceof Error) &&\n      result.pageStatus !== \"SplitRequired\"\n    );\n  });\n  // The first error in display order is the one reported.\n  const finish = (\n    items: ReadonlyArray<unknown>,\n    lastResult: Option.Option<PageResult>,\n    transitions: ReadonlyArray<(state: State) => State>,\n    errors: ReadonlyArray<Error>,\n  ): Interpretation =>\n    Array.some(errors, options.isInvalidCursorError)\n      ? { _tag: \"ResetRequired\" }\n      : Option.match(Array.head(errors), {\n          onNone: () => ({\n            _tag: \"Interpreted\",\n            items,\n            firstPageLoaded,\n            lastResult,\n            transitions,\n          }),\n          onSome: (error) => ({\n            _tag: \"Failed\",\n            error,\n            items,\n            firstPageLoaded,\n            transitions,\n          }),\n        });\n\n  const go = (\n    remaining: ReadonlyArray<string>,\n    items: ReadonlyArray<unknown>,\n    transitions: ReadonlyArray<(s: State) => State>,\n    lastResult: Option.Option<PageResult>,\n    errors: ReadonlyArray<Error>,\n  ): Interpretation =>\n    Option.match(Array.head(remaining), {\n      onNone: () => finish(items, lastResult, transitions, errors),\n      onSome: (pageKey) => {\n        const result = resultOf(pageKey);\n        if (result === undefined) {\n          // The trailing pages are still loading.\n          return finish(items, Option.none(), transitions, errors);\n        }\n        if (result instanceof Error) {\n          return finish(\n            items,\n            Option.none(),\n            transitions,\n            Array.append(errors, result),\n          );\n        }\n        // A force-split page couldn't be fetched in full: show the items\n        // before it and report the tail as still loading.\n        const shown =\n          result.pageStatus === \"SplitRequired\"\n            ? items\n            : Array.appendAll(items, result.page);\n\n        const ongoingSplit = Record.get(state.ongoingSplits, pageKey);\n        // A failed replacement leaves this page shown and its range pinned, so\n        // the pages after it stay contiguous and the walk goes on.\n        const replacementResults = Option.match(ongoingSplit, {\n          onNone: () => [],\n          onSome: Array.map(resultOf),\n        });\n        const nextErrors = Array.appendAll(\n          errors,\n          Array.filter(\n            replacementResults,\n            (replacement) => replacement instanceof Error,\n          ),\n        );\n        const nextTransitions = Option.match(ongoingSplit, {\n          onSome: () =>\n            // Swap the replacements in once all of them have loaded.\n            Array.every(\n              replacementResults,\n              (replacement) =>\n                replacement !== undefined && !(replacement instanceof Error),\n            )\n              ? Array.append(transitions, completeSplit(pageKey))\n              : transitions,\n          onNone: () =>\n            typeof result.splitCursor === \"string\" &&\n            (result.pageStatus === \"SplitRecommended\" ||\n              result.pageStatus === \"SplitRequired\" ||\n              result.page.length > options.initialNumItems)\n              ? Array.append(transitions, split(pageKey, result.splitCursor))\n              : // A loaded growing page pins itself to the range it just\n                // served (`END_CURSOR` once exhausted), so it stops being a\n                // sliding window that sheds items as new documents arrive.\n                Option.exists(\n                    Record.get(state.pages, pageKey),\n                    (request) => request.endCursor === undefined,\n                  ) && result.pageStatus !== \"SplitRequired\"\n                ? Array.append(transitions, pin(pageKey, result.continueCursor))\n                : transitions,\n        });\n\n        return result.pageStatus === \"SplitRequired\"\n          ? finish(shown, Option.none(), nextTransitions, nextErrors)\n          : go(\n              Array.drop(remaining, 1),\n              shown,\n              nextTransitions,\n              Option.some(result),\n              nextErrors,\n            );\n      },\n    });\n\n  return go(state.pageKeys, [], [], Option.none(), []);\n};\n"],"mappings":"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"}

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 import { Ref } from "@confect/core";
 import type { usePaginatedQuery as useConvexPaginatedQuery } from "convex/react";
 import * as Result from "effect/Result";
-import * as OptimisticLocalStore from "./OptimisticLocalStore";
-import * as PaginatedQueryResult from "./PaginatedQueryResult";
-import * as QueryResult from "./QueryResult";
-import * as StreamPagination from "./StreamPagination";
+import * as OptimisticLocalStore from "./OptimisticLocalStore.js";
+import * as PaginatedQueryResult from "./PaginatedQueryResult.js";
+import * as QueryResult from "./QueryResult.js";
+import * as StreamPagination from "./StreamPagination.js";
 export { OptimisticLocalStore, PaginatedQueryResult, QueryResult, StreamPagination, };
 export type InvokeReturn<Ref_ extends Ref.Any> = [Ref.Error<Ref_>] extends [
     never

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

@@ -187,7 +187,7 @@ const useStreamPaginatedQuery = (ref, args, options) => {
 		resetKey: previous.resetKey,
 		state: freshState()
 	}));
-	else if (interpretation._tag === "Interpreted" && interpretation.transitions.length > 0) applyTransitions(interpretation.transitions);
+	else if (interpretation.transitions.length > 0) applyTransitions(interpretation.transitions);
 	const encodedItems = interpretation._tag === "ResetRequired" ? NO_ITEMS : interpretation.items;
 	const decodeCache = useMemo(() => /* @__PURE__ */ new WeakMap(), [ref]);
 	const decodedResults = useMemo(() => encodedItems.map((item) => {
@@ -215,8 +215,8 @@ const useStreamPaginatedQuery = (ref, args, options) => {
 			}
 			throw error;
 		}
+		if (!interpretation.firstPageLoaded) return loadingFirstPage({ skipped });
 		const { lastResult } = interpretation;
-		if (Option.isNone(lastResult) && current.state.pageKeys.length <= 1) return loadingFirstPage({ skipped });
 		if (Option.isNone(lastResult) || isLastPageSplitting(current.state)) return loadingMore({ results: decodedResults });
 		if (lastResult.value.isDone) return exhausted({ results: decodedResults });
 		const continueCursor = lastResult.value.continueCursor;

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["useConvexQuery","QueryResult.load","QueryResult.succeed","QueryResult.fail","convexVersion","PaginatedQueryResult.failure","PaginatedQueryResult.loadingFirstPage","PaginatedQueryResult.loadingMore","PaginatedQueryResult.canLoadMore","PaginatedQueryResult.exhausted","StreamPagination.empty","StreamPagination.initial","StreamPagination.pageRequests","useConvexQueries","StreamPagination.interpret","StreamPagination.isLastPageSplitting","StreamPagination.loadMore","OptimisticLocalStore.make","useConvexMutation","useConvexAction"],"sources":["../src/index.ts"],"sourcesContent":["import { Ref } from \"@confect/core\";\nimport { version as convexVersion } from \"convex\";\nimport type { OptimisticUpdate as ConvexOptimisticUpdate } from \"convex/browser\";\nimport * as ConvexReact from \"convex/react\";\nimport type { usePaginatedQuery as useConvexPaginatedQuery } from \"convex/react\";\nimport {\n  useAction as useConvexAction,\n  useMutation as useConvexMutation,\n  useQueries as useConvexQueries,\n  useQuery as useConvexQuery,\n  type ReactMutation as ConvexReactMutation,\n} from \"convex/react\";\nimport { getFunctionName, type FunctionReference } from \"convex/server\";\nimport { ConvexError, convexToJson, type Value } from \"convex/values\";\nimport * as Cause from \"effect/Cause\";\nimport * as Effect from \"effect/Effect\";\nimport * as Result from \"effect/Result\";\nimport * as Exit from \"effect/Exit\";\nimport * as Match from \"effect/Match\";\nimport * as Option from \"effect/Option\";\nimport { useCallback, useMemo, useState } from \"react\";\n\nimport * as OptimisticLocalStore from \"./OptimisticLocalStore\";\nimport * as PaginatedQueryResult from \"./PaginatedQueryResult\";\nimport * as QueryResult from \"./QueryResult\";\nimport * as StreamPagination from \"./StreamPagination\";\n\nexport {\n  OptimisticLocalStore,\n  PaginatedQueryResult,\n  QueryResult,\n  StreamPagination,\n};\n\nexport type InvokeReturn<Ref_ extends Ref.Any> = [Ref.Error<Ref_>] extends [\n  never,\n]\n  ? Promise<Ref.Returns<Ref_>>\n  : Promise<Result.Result<Ref.Returns<Ref_>, Ref.Error<Ref_>>>;\n\ntype UseQueryArgs<Query extends Ref.AnyPublicQuery> =\n  keyof Ref.Args<Query> extends never\n    ? [args?: Ref.Args<Query> | \"skip\"]\n    : [args: Ref.Args<Query> | \"skip\"];\n\nexport const useQuery = <Query extends Ref.AnyPublicQuery>(\n  ref: Query,\n  ...rest: UseQueryArgs<Query>\n): QueryResult.QueryResult<Ref.Returns<Query>, Ref.Error<Query>> => {\n  const functionReference = Ref.getFunctionReference(ref);\n  const args = rest[0];\n  const skipped = args === \"skip\";\n  const encodedArgs = skipped\n    ? \"skip\"\n    : Ref.encodeArgsSync(ref, (args ?? {}) as Ref.Args<Query>);\n\n  // `useConvexQuery` returns a referentially stable value while the underlying\n  // Convex result is unchanged, and throws a stable error when the query\n  // fails. We capture either outcome as a `Result` and decode/wrap it inside\n  // `useMemo` so that the returned `QueryResult` keeps a stable identity across\n  // renders when nothing has actually changed. Decoding on every render would\n  // hand consumers a fresh object each time, breaking effects and memoization\n  // that depend on the result's identity.\n  const encodedReturnsOrError: Result.Result<unknown, unknown> = Result.try(\n    () => useConvexQuery(functionReference, encodedArgs),\n  );\n\n  return useMemo(\n    () =>\n      Result.match(encodedReturnsOrError, {\n        onSuccess: (encodedReturnsOrUndefined) =>\n          encodedReturnsOrUndefined === undefined\n            ? QueryResult.load(skipped)\n            : QueryResult.succeed(\n                Ref.decodeReturnsSync(ref, encodedReturnsOrUndefined),\n              ),\n        onFailure: (error) => {\n          if (Ref.isConvexError(error)) {\n            const decoded = Ref.decodeErrorOption(ref, error.data);\n            if (Option.isSome(decoded)) {\n              return QueryResult.fail(decoded.value);\n            }\n          }\n          throw error;\n        },\n      }),\n    // `Result.try` allocates a fresh wrapper each render, so we key the memo on\n    // the stable value it carries (the Convex result or thrown error) rather\n    // than the wrapper itself; the decoded result is a function of that value,\n    // `ref`, and `skipped`.\n    [ref, skipped, Result.merge(encodedReturnsOrError)],\n  );\n};\n\n/**\n * Like `Omit`, but implemented with key remapping so that optional modifiers\n * are preserved and index signatures don't reintroduce the omitted key's\n * literal type. Mirrors `BetterOmit` from `convex/server`.\n */\ntype OmitKey<T, K extends PropertyKey> = {\n  [P in keyof T as P extends K ? never : P]: T[P];\n};\n\n/**\n * The args accepted by {@link usePaginatedQuery}: the ref's args without\n * `paginationOpts`, which the underlying Convex hook manages itself. When no\n * args remain, resolves to `Record<string, never>` (only the empty object is\n * accepted) rather than `{}`, which would accept any non-nullish value.\n */\nexport type PaginatedQueryArgs<Query extends Ref.AnyPublicPaginatedQuery> =\n  OmitKey<Ref.Args<Query>, \"paginationOpts\"> extends infer Args_\n    ? keyof Args_ extends never\n      ? Record<string, never>\n      : Args_\n    : never;\n\n/**\n * The item type for a paginated query: the element type of the `page` field of\n * the ref's returns.\n */\nexport type PaginatedQueryItem<Query extends Ref.AnyPublicPaginatedQuery> =\n  Ref.Returns<Query>[\"page\"][number];\n\n/**\n * The args parameter of {@link usePaginatedQuery}: the ref's args without\n * `paginationOpts`, or `\"skip\"` to skip the query.\n */\nexport type UsePaginatedQueryArgs<Query extends Ref.AnyPublicPaginatedQuery> =\n  | PaginatedQueryArgs<Query>\n  | \"skip\";\n\nexport type PaginatedQueryOptions = Parameters<\n  typeof useConvexPaginatedQuery\n>[2];\n\n/**\n * The `user`-facing result of `usePaginatedQueryInternal` from `convex/react`,\n * including the `\"Error\"` status its non-throwing mode can return.\n */\ninterface ConvexPaginatedQueryInternalUser {\n  readonly results: ReadonlyArray<unknown>;\n  readonly status:\n    | \"LoadingFirstPage\"\n    | \"LoadingMore\"\n    | \"CanLoadMore\"\n    | \"Exhausted\"\n    | \"Error\";\n  readonly isLoading: boolean;\n  readonly loadMore: (numItems: number) => void;\n  readonly error?: unknown;\n}\n\ntype UseConvexPaginatedQueryInternal = (\n  query: FunctionReference<\"query\">,\n  args: Record<string, Value> | \"skip\",\n  options: PaginatedQueryOptions,\n  throwOnError: boolean,\n) => { user: ConvexPaginatedQueryInternalUser };\n\n// `usePaginatedQueryInternal` is runtime-exported by convex/react but absent\n// from its public type declarations. It is the only way to observe query\n// errors as values: the public positional `usePaginatedQuery` hard-codes\n// throwOnError and throws mid-hook-sequence, which cannot be caught without\n// breaking React's hook-order invariant.\nconst useConvexPaginatedQueryInternal = (\n  ConvexReact as unknown as Record<string, unknown>\n).usePaginatedQueryInternal as UseConvexPaginatedQueryInternal | undefined;\n\nconst MINIMUM_CONVEX_VERSION = \"1.36.0\";\n\n/**\n * The non-throwing mode of `usePaginatedQueryInternal`—its fourth,\n * `throwOnError` parameter—arrived in convex 1.36.0. Convex 1.32 through 1.35\n * export the same symbol taking only three parameters, where a fourth argument\n * is silently ignored and errors are always thrown.\n *\n * The function itself cannot be interrogated for this: `Function.length` counts\n * parameters up to the first one with a default, and 1.36.0 declares\n * `throwOnError = true`, so both shapes report an arity of 3. The package\n * version is the only reliable signal.\n */\nconst supportsErrorsAsValues = ((): boolean => {\n  const [major, minor] = convexVersion.split(\".\").map(Number);\n  if (\n    major === undefined ||\n    minor === undefined ||\n    Number.isNaN(major) ||\n    Number.isNaN(minor)\n  ) {\n    return false;\n  }\n  const [minimumMajor, minimumMinor] = MINIMUM_CONVEX_VERSION.split(\".\").map(\n    Number,\n  ) as [number, number];\n  return (\n    major > minimumMajor || (major === minimumMajor && minor >= minimumMinor)\n  );\n})();\n\n/**\n * Load data reactively from a paginated query defined with\n * `FunctionSpec.publicPaginatedQuery`, mirroring the ergonomics of\n * `usePaginatedQuery` from `convex/react`.\n *\n * Args are encoded via the ref's user-args schema (`paginationOpts` is managed\n * by the Convex hook, not the caller), and each loaded page is decoded via the\n * ref's item schema.\n *\n * Returns a {@link PaginatedQueryResult.PaginatedQueryResult}: the loaded\n * variants carry `results` and `isLoading`, and `CanLoadMore` additionally\n * carries `loadMore`; if the `Ref` declares an `error` schema and the query\n * fails with that typed error, the decoded error is returned as the `Failure`\n * variant, which also carries the pages loaded before the failure. Unknown\n * errors are thrown, to be caught by an error boundary.\n */\nexport const usePaginatedQuery = <Query extends Ref.AnyPublicPaginatedQuery>(\n  ref: Query,\n  args: UsePaginatedQueryArgs<Query>,\n  options: PaginatedQueryOptions,\n): PaginatedQueryResult.PaginatedQueryResult<\n  PaginatedQueryItem<Query>,\n  Ref.Error<Query>\n> => {\n  if (\n    useConvexPaginatedQueryInternal === undefined ||\n    !supportsErrorsAsValues\n  ) {\n    throw new Error(\n      `usePaginatedQuery requires convex >= ${MINIMUM_CONVEX_VERSION}, but found ` +\n        `${convexVersion}. Earlier versions always throw paginated query errors ` +\n        \"instead of returning them, so a declared `error` schema cannot be \" +\n        \"surfaced as a `Failure`—upgrade the `convex` package.\",\n    );\n  }\n\n  const functionReference = Ref.getFunctionReference(ref);\n  const skipped = args === \"skip\";\n\n  // The encoded output is the wire form Convex's hook forwards verbatim, not\n  // the ref's decoded args type.\n  const encodedArgs = useMemo(\n    () =>\n      args === \"skip\"\n        ? (\"skip\" as const)\n        : (Ref.encodePaginatedQueryArgsSync(\n            ref,\n            args as unknown as Omit<Ref.Args<Query>, \"paginationOpts\">,\n          ) as Record<string, Value>),\n    [ref, args],\n  );\n\n  const { user: convexResult } = useConvexPaginatedQueryInternal(\n    functionReference,\n    encodedArgs,\n    options,\n    false,\n  );\n\n  // The Convex hook carries the pages loaded so far on every status,\n  // failures included, so results are decoded unconditionally.\n  //\n  // Decoding allocates fresh items, so key on the referentially stable\n  // `results` the Convex hook provides—the same identity-preservation\n  // rationale as in `useQuery` above.\n  const { results: encodedResults } = convexResult;\n  const decodedResults = useMemo(\n    () => Ref.decodePaginationPageSync(ref, encodedResults),\n    [ref, encodedResults],\n  );\n\n  const { status, loadMore } = convexResult;\n  const error = status === \"Error\" ? convexResult.error : undefined;\n\n  return useMemo(\n    (): PaginatedQueryResult.Variants<\n      PaginatedQueryItem<Query>,\n      Ref.Error<Query>\n    > =>\n      // `status` is a bare string union rather than a tagged one, so the arms\n      // match on literals.\n      Match.value(status).pipe(\n        Match.when(\"Error\", () => {\n          if (Ref.isConvexError(error)) {\n            const decoded = Ref.decodeErrorOption(ref, error.data);\n            if (Option.isSome(decoded)) {\n              return PaginatedQueryResult.failure({\n                error: decoded.value,\n                results: decodedResults,\n              });\n            }\n          }\n          // Unknown errors still throw. All hooks have run by this point, so\n          // an aborted render here is hook-order-safe.\n          throw error;\n        }),\n        Match.when(\"LoadingFirstPage\", () =>\n          PaginatedQueryResult.loadingFirstPage({ skipped }),\n        ),\n        Match.when(\"LoadingMore\", () =>\n          PaginatedQueryResult.loadingMore({ results: decodedResults }),\n        ),\n        // `CanLoadMore` is the only status whose `loadMore` does anything—the Convex hook returns an intentional no-op for all the others, so\n        // they carry no callback at all.\n        Match.when(\"CanLoadMore\", () =>\n          PaginatedQueryResult.canLoadMore({\n            results: decodedResults,\n            loadMore,\n          }),\n        ),\n        Match.when(\"Exhausted\", () =>\n          PaginatedQueryResult.exhausted({ results: decodedResults }),\n        ),\n        Match.exhaustive,\n      ),\n    // The memo produces `Variants`, the conditional return type's superset—when `E` is `never` the `Failure` arm is unreachable at runtime, which\n    // is exactly what the conditional encodes.\n    [ref, skipped, decodedResults, status, loadMore, error],\n  ) as PaginatedQueryResult.PaginatedQueryResult<\n    PaginatedQueryItem<Query>,\n    Ref.Error<Query>\n  >;\n};\n\n/**\n * Whether a paginated query error means the stored cursors no longer match the\n * query (a data-dependent query changed underneath us), calling for a full\n * pagination reset rather than a failure.\n */\nconst isInvalidCursorError = (error: Error): boolean =>\n  error.message.includes(\"InvalidCursor\") ||\n  (error instanceof ConvexError &&\n    typeof error.data === \"object\" &&\n    error.data !== null &&\n    // Both Convex's built-in pagination (which also sets\n    // `isConvexSystemError`) and `QueryStream.paginate` signal an invalid\n    // cursor with this data shape—the same check `convex/react` performs.\n    (error.data as { paginationError?: unknown }).paginationError ===\n      \"InvalidCursor\");\n\nconst NO_ITEMS: ReadonlyArray<unknown> = [];\n\n/**\n * EXPERIMENTAL—endCursor-pinned reactive pagination (see\n * `notes/stream-based-querying.md`). Use it with paginated queries whose\n * handlers paginate via `QueryStream.paginate`: those don't write the query\n * journal that {@link usePaginatedQuery}'s built-in reactivity relies on, so\n * gap-free pages must be maintained by the client instead. (It works with any\n * paginated query honoring the `endCursor` protocol field, including the\n * built-in `paginate`.)\n *\n * Each loaded page is pinned to a fixed index range by re-subscribing it with\n * its `continueCursor` echoed back as `endCursor`—pages then grow and shrink\n * reactively but always meet exactly, and a page that outgrows\n * `initialNumItems` is split in two. This is the mechanism of\n * `convex-helpers/react`'s `usePaginatedQuery`, re-expressed over the pure\n * {@link StreamPagination} state machine, with args/items/errors codec'd through\n * the ref's schemas exactly like {@link usePaginatedQuery}.\n */\nexport const useStreamPaginatedQuery = <\n  Query extends Ref.AnyPublicPaginatedQuery,\n>(\n  ref: Query,\n  args: UsePaginatedQueryArgs<Query>,\n  options: {\n    readonly initialNumItems: number;\n    /**\n     * Per-page read budgets forwarded as `paginationOpts.maximumRowsRead` and\n     * `paginationOpts.maximumBytesRead`: a page that would scan more rows, or\n     * read more bytes, than these returns truncated with `SplitRequired` (and\n     * the hook splits it) instead of exceeding Convex's query limits on a\n     * filter-heavy stream.\n     */\n    readonly maximumRowsRead?: number;\n    readonly maximumBytesRead?: number;\n  },\n): PaginatedQueryResult.PaginatedQueryResult<\n  PaginatedQueryItem<Query>,\n  Ref.Error<Query>\n> => {\n  // `useQueries` requires a *referentially stable* queries object while\n  // nothing has changed: its subscription memo keys on identity, and its\n  // `useSubscription` re-runs a render-phase state update whenever the\n  // subscription changes—an unstable input loops the render. Callers\n  // typically pass a fresh `args` literal each render, so everything that\n  // feeds the queries object is stabilized by *value* here: the function\n  // reference by `ref`, and the encoded args by their serialized form (as\n  // `convex/react`'s own paginated hook does).\n  const functionReference = useMemo(() => Ref.getFunctionReference(ref), [ref]);\n  const skipped = args === \"skip\";\n\n  const rawEncodedArgs =\n    args === \"skip\"\n      ? undefined\n      : (Ref.encodePaginatedQueryArgsSync(\n          ref,\n          args as unknown as Omit<Ref.Args<Query>, \"paginationOpts\">,\n        ) as Record<string, Value>);\n  const encodedArgsKey =\n    rawEncodedArgs === undefined\n      ? \"skip\"\n      : JSON.stringify(convexToJson(rawEncodedArgs));\n  const encodedArgs = useMemo(\n    () => rawEncodedArgs,\n    // The serialized form stands in for the freshly allocated object.\n    [ref, encodedArgsKey],\n  );\n\n  // A change of query, args, skippedness, or page size restarts pagination\n  // from scratch.\n  const resetKey = useMemo(\n    () =>\n      JSON.stringify([\n        getFunctionName(functionReference),\n        encodedArgsKey,\n        options.initialNumItems,\n        options.maximumRowsRead ?? null,\n        options.maximumBytesRead ?? null,\n      ]),\n    [\n      functionReference,\n      encodedArgsKey,\n      options.initialNumItems,\n      options.maximumRowsRead,\n      options.maximumBytesRead,\n    ],\n  );\n\n  const freshState = () =>\n    skipped\n      ? StreamPagination.empty\n      : StreamPagination.initial(options.initialNumItems, options);\n\n  const [tracked, setTracked] = useState(() => ({\n    resetKey,\n    state: freshState(),\n  }));\n  // Render-phase reset—the React-sanctioned derived-state-from-props\n  // pattern, also how `convex/react`'s own paginated hook resets.\n  let current = tracked;\n  if (current.resetKey !== resetKey) {\n    current = { resetKey, state: freshState() };\n    setTracked(current);\n  }\n\n  const applyTransitions = useCallback(\n    (\n      transitions: ReadonlyArray<\n        (state: StreamPagination.State) => StreamPagination.State\n      >,\n    ) =>\n      setTracked((previous) => ({\n        resetKey: previous.resetKey,\n        state: transitions.reduce(\n          (state, transition) => transition(state),\n          previous.state,\n        ),\n      })),\n    [],\n  );\n\n  const queries = useMemo(\n    () =>\n      StreamPagination.pageRequests(current.state, (page) => ({\n        query: functionReference,\n        args: { ...encodedArgs, paginationOpts: page },\n      })),\n    [current.state, functionReference, encodedArgs],\n  );\n\n  const resultsObject = useConvexQueries(\n    queries as unknown as Parameters<typeof useConvexQueries>[0],\n  );\n\n  const interpretation = useMemo(\n    () =>\n      StreamPagination.interpret(\n        current.state,\n        resultsObject as StreamPagination.Results,\n        { initialNumItems: options.initialNumItems, isInvalidCursorError },\n      ),\n    [current.state, resultsObject, options.initialNumItems],\n  );\n\n  // Apply the transitions this render discovered (completed split swaps,\n  // new splits of overgrown pages) or restart after an invalid cursor—render-phase state updates, as in `convex-helpers`' hook. Both settle:\n  // the updated state no longer produces the same discovery.\n  if (interpretation._tag === \"ResetRequired\") {\n    setTracked((previous) => ({\n      resetKey: previous.resetKey,\n      state: freshState(),\n    }));\n  } else if (\n    interpretation._tag === \"Interpreted\" &&\n    interpretation.transitions.length > 0\n  ) {\n    applyTransitions(interpretation.transitions);\n  }\n\n  const encodedItems =\n    interpretation._tag === \"ResetRequired\" ? NO_ITEMS : interpretation.items;\n  // Page results keep their identity while unchanged (only the page that\n  // actually updated is a fresh object), so caching decodes per encoded\n  // item makes a single-page update decode only that page's items rather\n  // than every loaded page's.\n  const decodeCache = useMemo(\n    () => new WeakMap<object, PaginatedQueryItem<Query>>(),\n    [ref],\n  );\n  const decodedResults = useMemo(\n    () =>\n      encodedItems.map((item): PaginatedQueryItem<Query> => {\n        if (typeof item !== \"object\" || item === null) {\n          return Ref.decodePaginationPageSync(ref, [\n            item,\n          ])[0] as PaginatedQueryItem<Query>;\n        }\n        const cached = decodeCache.get(item);\n        if (cached !== undefined) {\n          return cached;\n        }\n        const decoded = Ref.decodePaginationPageSync(ref, [\n          item,\n        ])[0] as PaginatedQueryItem<Query>;\n        decodeCache.set(item, decoded);\n        return decoded;\n      }),\n    [ref, encodedItems, decodeCache],\n  );\n\n  return useMemo((): PaginatedQueryResult.Variants<\n    PaginatedQueryItem<Query>,\n    Ref.Error<Query>\n  > => {\n    if (interpretation._tag === \"ResetRequired\") {\n      return PaginatedQueryResult.loadingFirstPage({ skipped });\n    }\n    if (interpretation._tag === \"Failed\") {\n      const error = interpretation.error;\n      if (Ref.isConvexError(error)) {\n        const decoded = Ref.decodeErrorOption(ref, error.data);\n        if (Option.isSome(decoded)) {\n          return PaginatedQueryResult.failure({\n            error: decoded.value,\n            results: decodedResults,\n          });\n        }\n      }\n      // Unknown errors still throw, to be caught by an error boundary.\n      throw error;\n    }\n\n    const { lastResult } = interpretation;\n    if (Option.isNone(lastResult) && current.state.pageKeys.length <= 1) {\n      return PaginatedQueryResult.loadingFirstPage({ skipped });\n    }\n    if (\n      Option.isNone(lastResult) ||\n      StreamPagination.isLastPageSplitting(current.state)\n    ) {\n      return PaginatedQueryResult.loadingMore({ results: decodedResults });\n    }\n    if (lastResult.value.isDone) {\n      return PaginatedQueryResult.exhausted({ results: decodedResults });\n    }\n\n    const continueCursor = lastResult.value.continueCursor;\n    // A per-result guard, as in `convex-helpers`: calling `loadMore`\n    // repeatedly before the next render is a single load.\n    let alreadyLoadingMore = false;\n    return PaginatedQueryResult.canLoadMore({\n      results: decodedResults,\n      loadMore: (numItems: number) => {\n        if (!alreadyLoadingMore) {\n          alreadyLoadingMore = true;\n          applyTransitions([\n            StreamPagination.loadMore(continueCursor, numItems, options),\n          ]);\n        }\n      },\n    });\n  }, [\n    interpretation,\n    decodedResults,\n    current.state,\n    skipped,\n    ref,\n    applyTransitions,\n  ]) as PaginatedQueryResult.PaginatedQueryResult<\n    PaginatedQueryItem<Query>,\n    Ref.Error<Query>\n  >;\n};\n\n/**\n * An optimistic update for a Confect mutation. Mirrors Convex's\n * `OptimisticUpdate`, but receives a Confect {@link OptimisticLocalStore} and\n * the decoded mutation `args`.\n */\nexport type OptimisticUpdate<Mutation extends Ref.AnyPublicMutation> = (\n  localStore: OptimisticLocalStore.OptimisticLocalStore,\n  args: Ref.Args<Mutation>,\n) => void;\n\n/**\n * The handle returned by {@link useMutation}. It is callable like the function\n * returned by Convex's `useMutation`, and additionally exposes\n * `withOptimisticUpdate` for attaching an optimistic update. Mirrors the\n * `ReactMutation` type from `convex/react`.\n */\nexport interface ReactMutation<Mutation extends Ref.AnyPublicMutation> {\n  (...args: Ref.OptionalArgs<Mutation>): InvokeReturn<Mutation>;\n  withOptimisticUpdate(\n    optimisticUpdate: OptimisticUpdate<Mutation>,\n  ): ReactMutation<Mutation>;\n}\n\nconst makeReactMutation = <Mutation extends Ref.AnyPublicMutation>(\n  ref: Mutation,\n  convexReactMutation: ConvexReactMutation<\n    Ref.FunctionReference<Mutation> & FunctionReference<\"mutation\">\n  >,\n): ReactMutation<Mutation> => {\n  const callable = ((...args: Ref.OptionalArgs<Mutation>) =>\n    invokeAsResult(\n      ref,\n      (_, encodedArgs) => convexReactMutation(encodedArgs as never),\n      args,\n    ).then((result) =>\n      Ref.hasErrorSchema(ref) ? result : Result.getOrThrow(result),\n    )) as (...args: Ref.OptionalArgs<Mutation>) => InvokeReturn<Mutation>;\n\n  const withOptimisticUpdate = (\n    optimisticUpdate: OptimisticUpdate<Mutation>,\n  ): ReactMutation<Mutation> => {\n    const wrappedUpdate: ConvexOptimisticUpdate<Record<string, Value>> = (\n      convexLocalStore,\n      encodedArgs,\n    ) => {\n      const decodedArgs = Ref.decodeArgsSync(ref, encodedArgs);\n      optimisticUpdate(\n        OptimisticLocalStore.make(convexLocalStore),\n        decodedArgs,\n      );\n    };\n    const nextConvexReactMutation =\n      convexReactMutation.withOptimisticUpdate(wrappedUpdate);\n    return makeReactMutation(ref, nextConvexReactMutation);\n  };\n\n  return Object.assign(callable, { withOptimisticUpdate });\n};\n\n/**\n * Returns a {@link ReactMutation} handle for the provided `Ref`'s mutation. The\n * handle is callable to invoke the mutation, and exposes `withOptimisticUpdate`\n * for attaching an optimistic update, mirroring `useMutation` from\n * `convex/react`.\n *\n * If the `Ref` declares an `error` schema, the returned promise resolves to a\n * `Result` with the decoded `returns` value in the `Success` and the decoded\n * error in the `Failure`.\n *\n * If the `Ref` does not declare an `error` schema, the promise resolves\n * directly to the decoded `returns` value, matching the behavior of\n * `useMutation` from `convex/react`.\n *\n * Any other failure rejects the promise.\n */\nexport const useMutation = <Mutation extends Ref.AnyPublicMutation>(\n  ref: Mutation,\n): ReactMutation<Mutation> => {\n  const functionReference = Ref.getFunctionReference(ref);\n  const convexReactMutation = useConvexMutation(functionReference);\n\n  return useMemo(\n    () =>\n      makeReactMutation(\n        ref,\n        convexReactMutation as ConvexReactMutation<\n          Ref.FunctionReference<Mutation> & FunctionReference<\"mutation\">\n        >,\n      ),\n    [ref, convexReactMutation],\n  );\n};\n\n/**\n * Returns a function that invokes the provided `Ref`'s action.\n *\n * If the `Ref` declares an `error` schema, the returned promise resolves to a\n * `Result` with the decoded `returns` value in the `Success` and the decoded\n * error in the `Failure`.\n *\n * If the `Ref` does not declare an `error` schema, the promise resolves\n * directly to the decoded `returns` value, matching the behavior of\n * `useMutation` from `convex/react`.\n *\n * Any other failure rejects the promise.\n */\nexport const useAction = <Action extends Ref.AnyPublicAction>(\n  ref: Action,\n): ((...args: Ref.OptionalArgs<Action>) => InvokeReturn<Action>) => {\n  const functionReference = Ref.getFunctionReference(ref);\n  const actualAction = useConvexAction(functionReference);\n\n  return useCallback(\n    ((...args: Ref.OptionalArgs<Action>) =>\n      invokeAsResult(\n        ref,\n        (_, encodedArgs) => actualAction(encodedArgs),\n        args,\n      ).then((result) =>\n        Ref.hasErrorSchema(ref) ? result : Result.getOrThrow(result),\n      )) as (...args: Ref.OptionalArgs<Action>) => InvokeReturn<Action>,\n    [ref, actualAction],\n  );\n};\n\nconst invokeAsResult = <Ref_ extends Ref.Any>(\n  ref: Ref_,\n  invoke: (\n    fnRef: Ref.FunctionReference<Ref_>,\n    encodedArgs: unknown,\n  ) => PromiseLike<unknown>,\n  args: Ref.OptionalArgs<Ref_>,\n): Promise<Result.Result<Ref.Returns<Ref_>, Ref.Error<Ref_>>> => {\n  const exitPromise = Effect.runPromiseExit(\n    Ref.runWithCodec(ref, (args[0] ?? {}) as Ref.Args<Ref_>, invoke).pipe(\n      Effect.catchTag(\"SchemaError\", Effect.die),\n      Effect.result,\n    ),\n  );\n  return exitPromise.then((exit) => {\n    if (Exit.isSuccess(exit)) return exit.value;\n    throw Cause.squash(exit.cause);\n  });\n};\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":["useConvexQuery","QueryResult.load","QueryResult.succeed","QueryResult.fail","convexVersion","PaginatedQueryResult.failure","PaginatedQueryResult.loadingFirstPage","PaginatedQueryResult.loadingMore","PaginatedQueryResult.canLoadMore","PaginatedQueryResult.exhausted","StreamPagination.empty","StreamPagination.initial","StreamPagination.pageRequests","useConvexQueries","StreamPagination.interpret","StreamPagination.isLastPageSplitting","StreamPagination.loadMore","OptimisticLocalStore.make","useConvexMutation","useConvexAction"],"sources":["../src/index.ts"],"sourcesContent":["import { Ref } from \"@confect/core\";\nimport { version as convexVersion } from \"convex\";\nimport type { OptimisticUpdate as ConvexOptimisticUpdate } from \"convex/browser\";\nimport * as ConvexReact from \"convex/react\";\nimport type { usePaginatedQuery as useConvexPaginatedQuery } from \"convex/react\";\nimport {\n  useAction as useConvexAction,\n  useMutation as useConvexMutation,\n  useQueries as useConvexQueries,\n  useQuery as useConvexQuery,\n  type ReactMutation as ConvexReactMutation,\n} from \"convex/react\";\nimport { getFunctionName, type FunctionReference } from \"convex/server\";\nimport { ConvexError, convexToJson, type Value } from \"convex/values\";\nimport * as Cause from \"effect/Cause\";\nimport * as Effect from \"effect/Effect\";\nimport * as Result from \"effect/Result\";\nimport * as Exit from \"effect/Exit\";\nimport * as Match from \"effect/Match\";\nimport * as Option from \"effect/Option\";\nimport { useCallback, useMemo, useState } from \"react\";\n\nimport * as OptimisticLocalStore from \"./OptimisticLocalStore.js\";\nimport * as PaginatedQueryResult from \"./PaginatedQueryResult.js\";\nimport * as QueryResult from \"./QueryResult.js\";\nimport * as StreamPagination from \"./StreamPagination.js\";\n\nexport {\n  OptimisticLocalStore,\n  PaginatedQueryResult,\n  QueryResult,\n  StreamPagination,\n};\n\nexport type InvokeReturn<Ref_ extends Ref.Any> = [Ref.Error<Ref_>] extends [\n  never,\n]\n  ? Promise<Ref.Returns<Ref_>>\n  : Promise<Result.Result<Ref.Returns<Ref_>, Ref.Error<Ref_>>>;\n\ntype UseQueryArgs<Query extends Ref.AnyPublicQuery> =\n  keyof Ref.Args<Query> extends never\n    ? [args?: Ref.Args<Query> | \"skip\"]\n    : [args: Ref.Args<Query> | \"skip\"];\n\nexport const useQuery = <Query extends Ref.AnyPublicQuery>(\n  ref: Query,\n  ...rest: UseQueryArgs<Query>\n): QueryResult.QueryResult<Ref.Returns<Query>, Ref.Error<Query>> => {\n  const functionReference = Ref.getFunctionReference(ref);\n  const args = rest[0];\n  const skipped = args === \"skip\";\n  const encodedArgs = skipped\n    ? \"skip\"\n    : Ref.encodeArgsSync(ref, (args ?? {}) as Ref.Args<Query>);\n\n  // `useConvexQuery` returns a referentially stable value while the underlying\n  // Convex result is unchanged, and throws a stable error when the query\n  // fails. We capture either outcome as a `Result` and decode/wrap it inside\n  // `useMemo` so that the returned `QueryResult` keeps a stable identity across\n  // renders when nothing has actually changed. Decoding on every render would\n  // hand consumers a fresh object each time, breaking effects and memoization\n  // that depend on the result's identity.\n  const encodedReturnsOrError: Result.Result<unknown, unknown> = Result.try(\n    () => useConvexQuery(functionReference, encodedArgs),\n  );\n\n  return useMemo(\n    () =>\n      Result.match(encodedReturnsOrError, {\n        onSuccess: (encodedReturnsOrUndefined) =>\n          encodedReturnsOrUndefined === undefined\n            ? QueryResult.load(skipped)\n            : QueryResult.succeed(\n                Ref.decodeReturnsSync(ref, encodedReturnsOrUndefined),\n              ),\n        onFailure: (error) => {\n          if (Ref.isConvexError(error)) {\n            const decoded = Ref.decodeErrorOption(ref, error.data);\n            if (Option.isSome(decoded)) {\n              return QueryResult.fail(decoded.value);\n            }\n          }\n          throw error;\n        },\n      }),\n    // `Result.try` allocates a fresh wrapper each render, so we key the memo on\n    // the stable value it carries (the Convex result or thrown error) rather\n    // than the wrapper itself; the decoded result is a function of that value,\n    // `ref`, and `skipped`.\n    [ref, skipped, Result.merge(encodedReturnsOrError)],\n  );\n};\n\n/**\n * Like `Omit`, but implemented with key remapping so that optional modifiers\n * are preserved and index signatures don't reintroduce the omitted key's\n * literal type. Mirrors `BetterOmit` from `convex/server`.\n */\ntype OmitKey<T, K extends PropertyKey> = {\n  [P in keyof T as P extends K ? never : P]: T[P];\n};\n\n/**\n * The args accepted by {@link usePaginatedQuery}: the ref's args without\n * `paginationOpts`, which the underlying Convex hook manages itself. When no\n * args remain, resolves to `Record<string, never>` (only the empty object is\n * accepted) rather than `{}`, which would accept any non-nullish value.\n */\nexport type PaginatedQueryArgs<Query extends Ref.AnyPublicPaginatedQuery> =\n  OmitKey<Ref.Args<Query>, \"paginationOpts\"> extends infer Args_\n    ? keyof Args_ extends never\n      ? Record<string, never>\n      : Args_\n    : never;\n\n/**\n * The item type for a paginated query: the element type of the `page` field of\n * the ref's returns.\n */\nexport type PaginatedQueryItem<Query extends Ref.AnyPublicPaginatedQuery> =\n  Ref.Returns<Query>[\"page\"][number];\n\n/**\n * The args parameter of {@link usePaginatedQuery}: the ref's args without\n * `paginationOpts`, or `\"skip\"` to skip the query.\n */\nexport type UsePaginatedQueryArgs<Query extends Ref.AnyPublicPaginatedQuery> =\n  | PaginatedQueryArgs<Query>\n  | \"skip\";\n\nexport type PaginatedQueryOptions = Parameters<\n  typeof useConvexPaginatedQuery\n>[2];\n\n/**\n * The `user`-facing result of `usePaginatedQueryInternal` from `convex/react`,\n * including the `\"Error\"` status its non-throwing mode can return.\n */\ninterface ConvexPaginatedQueryInternalUser {\n  readonly results: ReadonlyArray<unknown>;\n  readonly status:\n    | \"LoadingFirstPage\"\n    | \"LoadingMore\"\n    | \"CanLoadMore\"\n    | \"Exhausted\"\n    | \"Error\";\n  readonly isLoading: boolean;\n  readonly loadMore: (numItems: number) => void;\n  readonly error?: unknown;\n}\n\ntype UseConvexPaginatedQueryInternal = (\n  query: FunctionReference<\"query\">,\n  args: Record<string, Value> | \"skip\",\n  options: PaginatedQueryOptions,\n  throwOnError: boolean,\n) => { user: ConvexPaginatedQueryInternalUser };\n\n// `usePaginatedQueryInternal` is runtime-exported by convex/react but absent\n// from its public type declarations. It is the only way to observe query\n// errors as values: the public positional `usePaginatedQuery` hard-codes\n// throwOnError and throws mid-hook-sequence, which cannot be caught without\n// breaking React's hook-order invariant.\nconst useConvexPaginatedQueryInternal = (\n  ConvexReact as unknown as Record<string, unknown>\n).usePaginatedQueryInternal as UseConvexPaginatedQueryInternal | undefined;\n\nconst MINIMUM_CONVEX_VERSION = \"1.36.0\";\n\n/**\n * The non-throwing mode of `usePaginatedQueryInternal`—its fourth,\n * `throwOnError` parameter—arrived in convex 1.36.0. Convex 1.32 through 1.35\n * export the same symbol taking only three parameters, where a fourth argument\n * is silently ignored and errors are always thrown.\n *\n * The function itself cannot be interrogated for this: `Function.length` counts\n * parameters up to the first one with a default, and 1.36.0 declares\n * `throwOnError = true`, so both shapes report an arity of 3. The package\n * version is the only reliable signal.\n */\nconst supportsErrorsAsValues = ((): boolean => {\n  const [major, minor] = convexVersion.split(\".\").map(Number);\n  if (\n    major === undefined ||\n    minor === undefined ||\n    Number.isNaN(major) ||\n    Number.isNaN(minor)\n  ) {\n    return false;\n  }\n  const [minimumMajor, minimumMinor] = MINIMUM_CONVEX_VERSION.split(\".\").map(\n    Number,\n  ) as [number, number];\n  return (\n    major > minimumMajor || (major === minimumMajor && minor >= minimumMinor)\n  );\n})();\n\n/**\n * Load data reactively from a paginated query defined with\n * `FunctionSpec.publicPaginatedQuery`, mirroring the ergonomics of\n * `usePaginatedQuery` from `convex/react`.\n *\n * Args are encoded via the ref's user-args schema (`paginationOpts` is managed\n * by the Convex hook, not the caller), and each loaded page is decoded via the\n * ref's item schema.\n *\n * Returns a {@link PaginatedQueryResult.PaginatedQueryResult}: the loaded\n * variants carry `results` and `isLoading`, and `CanLoadMore` additionally\n * carries `loadMore`; if the `Ref` declares an `error` schema and the query\n * fails with that typed error, the decoded error is returned as the `Failure`\n * variant, which also carries the pages loaded before the failure. Unknown\n * errors are thrown, to be caught by an error boundary.\n */\nexport const usePaginatedQuery = <Query extends Ref.AnyPublicPaginatedQuery>(\n  ref: Query,\n  args: UsePaginatedQueryArgs<Query>,\n  options: PaginatedQueryOptions,\n): PaginatedQueryResult.PaginatedQueryResult<\n  PaginatedQueryItem<Query>,\n  Ref.Error<Query>\n> => {\n  if (\n    useConvexPaginatedQueryInternal === undefined ||\n    !supportsErrorsAsValues\n  ) {\n    throw new Error(\n      `usePaginatedQuery requires convex >= ${MINIMUM_CONVEX_VERSION}, but found ` +\n        `${convexVersion}. Earlier versions always throw paginated query errors ` +\n        \"instead of returning them, so a declared `error` schema cannot be \" +\n        \"surfaced as a `Failure`—upgrade the `convex` package.\",\n    );\n  }\n\n  const functionReference = Ref.getFunctionReference(ref);\n  const skipped = args === \"skip\";\n\n  // The encoded output is the wire form Convex's hook forwards verbatim, not\n  // the ref's decoded args type.\n  const encodedArgs = useMemo(\n    () =>\n      args === \"skip\"\n        ? (\"skip\" as const)\n        : (Ref.encodePaginatedQueryArgsSync(\n            ref,\n            args as unknown as Omit<Ref.Args<Query>, \"paginationOpts\">,\n          ) as Record<string, Value>),\n    [ref, args],\n  );\n\n  const { user: convexResult } = useConvexPaginatedQueryInternal(\n    functionReference,\n    encodedArgs,\n    options,\n    false,\n  );\n\n  // The Convex hook carries the pages loaded so far on every status,\n  // failures included, so results are decoded unconditionally.\n  //\n  // Decoding allocates fresh items, so key on the referentially stable\n  // `results` the Convex hook provides—the same identity-preservation\n  // rationale as in `useQuery` above.\n  const { results: encodedResults } = convexResult;\n  const decodedResults = useMemo(\n    () => Ref.decodePaginationPageSync(ref, encodedResults),\n    [ref, encodedResults],\n  );\n\n  const { status, loadMore } = convexResult;\n  const error = status === \"Error\" ? convexResult.error : undefined;\n\n  return useMemo(\n    (): PaginatedQueryResult.Variants<\n      PaginatedQueryItem<Query>,\n      Ref.Error<Query>\n    > =>\n      // `status` is a bare string union rather than a tagged one, so the arms\n      // match on literals.\n      Match.value(status).pipe(\n        Match.when(\"Error\", () => {\n          if (Ref.isConvexError(error)) {\n            const decoded = Ref.decodeErrorOption(ref, error.data);\n            if (Option.isSome(decoded)) {\n              return PaginatedQueryResult.failure({\n                error: decoded.value,\n                results: decodedResults,\n              });\n            }\n          }\n          // Unknown errors still throw. All hooks have run by this point, so\n          // an aborted render here is hook-order-safe.\n          throw error;\n        }),\n        Match.when(\"LoadingFirstPage\", () =>\n          PaginatedQueryResult.loadingFirstPage({ skipped }),\n        ),\n        Match.when(\"LoadingMore\", () =>\n          PaginatedQueryResult.loadingMore({ results: decodedResults }),\n        ),\n        // `CanLoadMore` is the only status whose `loadMore` does anything—the Convex hook returns an intentional no-op for all the others, so\n        // they carry no callback at all.\n        Match.when(\"CanLoadMore\", () =>\n          PaginatedQueryResult.canLoadMore({\n            results: decodedResults,\n            loadMore,\n          }),\n        ),\n        Match.when(\"Exhausted\", () =>\n          PaginatedQueryResult.exhausted({ results: decodedResults }),\n        ),\n        Match.exhaustive,\n      ),\n    // The memo produces `Variants`, the conditional return type's superset—when `E` is `never` the `Failure` arm is unreachable at runtime, which\n    // is exactly what the conditional encodes.\n    [ref, skipped, decodedResults, status, loadMore, error],\n  ) as PaginatedQueryResult.PaginatedQueryResult<\n    PaginatedQueryItem<Query>,\n    Ref.Error<Query>\n  >;\n};\n\n/**\n * Whether a paginated query error means the stored cursors no longer match the\n * query (a data-dependent query changed underneath us), calling for a full\n * pagination reset rather than a failure.\n */\nconst isInvalidCursorError = (error: Error): boolean =>\n  error.message.includes(\"InvalidCursor\") ||\n  (error instanceof ConvexError &&\n    typeof error.data === \"object\" &&\n    error.data !== null &&\n    // Both Convex's built-in pagination (which also sets\n    // `isConvexSystemError`) and `QueryStream.paginate` signal an invalid\n    // cursor with this data shape—the same check `convex/react` performs.\n    (error.data as { paginationError?: unknown }).paginationError ===\n      \"InvalidCursor\");\n\nconst NO_ITEMS: ReadonlyArray<unknown> = [];\n\n/**\n * EXPERIMENTAL—endCursor-pinned reactive pagination (see\n * `notes/stream-based-querying.md`). Use it with paginated queries whose\n * handlers paginate via `QueryStream.paginate`: those don't write the query\n * journal that {@link usePaginatedQuery}'s built-in reactivity relies on, so\n * gap-free pages must be maintained by the client instead. (It works with any\n * paginated query honoring the `endCursor` protocol field, including the\n * built-in `paginate`.)\n *\n * Each loaded page is pinned to a fixed index range by re-subscribing it with\n * its `continueCursor` echoed back as `endCursor`—pages then grow and shrink\n * reactively but always meet exactly, and a page that outgrows\n * `initialNumItems` is split in two. This is the mechanism of\n * `convex-helpers/react`'s `usePaginatedQuery`, re-expressed over the pure\n * {@link StreamPagination} state machine, with args/items/errors codec'd through\n * the ref's schemas exactly like {@link usePaginatedQuery}.\n */\nexport const useStreamPaginatedQuery = <\n  Query extends Ref.AnyPublicPaginatedQuery,\n>(\n  ref: Query,\n  args: UsePaginatedQueryArgs<Query>,\n  options: {\n    readonly initialNumItems: number;\n    /**\n     * Per-page read budgets forwarded as `paginationOpts.maximumRowsRead` and\n     * `paginationOpts.maximumBytesRead`: a page that would scan more rows, or\n     * read more bytes, than these returns truncated with `SplitRequired` (and\n     * the hook splits it) instead of exceeding Convex's query limits on a\n     * filter-heavy stream.\n     */\n    readonly maximumRowsRead?: number;\n    readonly maximumBytesRead?: number;\n  },\n): PaginatedQueryResult.PaginatedQueryResult<\n  PaginatedQueryItem<Query>,\n  Ref.Error<Query>\n> => {\n  // `useQueries` requires a *referentially stable* queries object while\n  // nothing has changed: its subscription memo keys on identity, and its\n  // `useSubscription` re-runs a render-phase state update whenever the\n  // subscription changes—an unstable input loops the render. Callers\n  // typically pass a fresh `args` literal each render, so everything that\n  // feeds the queries object is stabilized by *value* here: the function\n  // reference by `ref`, and the encoded args by their serialized form (as\n  // `convex/react`'s own paginated hook does).\n  const functionReference = useMemo(() => Ref.getFunctionReference(ref), [ref]);\n  const skipped = args === \"skip\";\n\n  const rawEncodedArgs =\n    args === \"skip\"\n      ? undefined\n      : (Ref.encodePaginatedQueryArgsSync(\n          ref,\n          args as unknown as Omit<Ref.Args<Query>, \"paginationOpts\">,\n        ) as Record<string, Value>);\n  const encodedArgsKey =\n    rawEncodedArgs === undefined\n      ? \"skip\"\n      : JSON.stringify(convexToJson(rawEncodedArgs));\n  const encodedArgs = useMemo(\n    () => rawEncodedArgs,\n    // The serialized form stands in for the freshly allocated object.\n    [ref, encodedArgsKey],\n  );\n\n  // A change of query, args, skippedness, or page size restarts pagination\n  // from scratch.\n  const resetKey = useMemo(\n    () =>\n      JSON.stringify([\n        getFunctionName(functionReference),\n        encodedArgsKey,\n        options.initialNumItems,\n        options.maximumRowsRead ?? null,\n        options.maximumBytesRead ?? null,\n      ]),\n    [\n      functionReference,\n      encodedArgsKey,\n      options.initialNumItems,\n      options.maximumRowsRead,\n      options.maximumBytesRead,\n    ],\n  );\n\n  const freshState = () =>\n    skipped\n      ? StreamPagination.empty\n      : StreamPagination.initial(options.initialNumItems, options);\n\n  const [tracked, setTracked] = useState(() => ({\n    resetKey,\n    state: freshState(),\n  }));\n  // Render-phase reset—the React-sanctioned derived-state-from-props\n  // pattern, also how `convex/react`'s own paginated hook resets.\n  let current = tracked;\n  if (current.resetKey !== resetKey) {\n    current = { resetKey, state: freshState() };\n    setTracked(current);\n  }\n\n  const applyTransitions = useCallback(\n    (\n      transitions: ReadonlyArray<\n        (state: StreamPagination.State) => StreamPagination.State\n      >,\n    ) =>\n      setTracked((previous) => ({\n        resetKey: previous.resetKey,\n        state: transitions.reduce(\n          (state, transition) => transition(state),\n          previous.state,\n        ),\n      })),\n    [],\n  );\n\n  const queries = useMemo(\n    () =>\n      StreamPagination.pageRequests(current.state, (page) => ({\n        query: functionReference,\n        args: { ...encodedArgs, paginationOpts: page },\n      })),\n    [current.state, functionReference, encodedArgs],\n  );\n\n  const resultsObject = useConvexQueries(\n    queries as unknown as Parameters<typeof useConvexQueries>[0],\n  );\n\n  const interpretation = useMemo(\n    () =>\n      StreamPagination.interpret(\n        current.state,\n        resultsObject as StreamPagination.Results,\n        { initialNumItems: options.initialNumItems, isInvalidCursorError },\n      ),\n    [current.state, resultsObject, options.initialNumItems],\n  );\n\n  // Apply the transitions this render discovered (completed split swaps,\n  // new splits of overgrown pages) or restart after an invalid cursor—render-phase state updates, as in `convex-helpers`' hook. Both settle:\n  // the updated state no longer produces the same discovery.\n  if (interpretation._tag === \"ResetRequired\") {\n    setTracked((previous) => ({\n      resetKey: previous.resetKey,\n      state: freshState(),\n    }));\n  } else if (interpretation.transitions.length > 0) {\n    applyTransitions(interpretation.transitions);\n  }\n\n  const encodedItems =\n    interpretation._tag === \"ResetRequired\" ? NO_ITEMS : interpretation.items;\n  // Page results keep their identity while unchanged (only the page that\n  // actually updated is a fresh object), so caching decodes per encoded\n  // item makes a single-page update decode only that page's items rather\n  // than every loaded page's.\n  const decodeCache = useMemo(\n    () => new WeakMap<object, PaginatedQueryItem<Query>>(),\n    [ref],\n  );\n  const decodedResults = useMemo(\n    () =>\n      encodedItems.map((item): PaginatedQueryItem<Query> => {\n        if (typeof item !== \"object\" || item === null) {\n          return Ref.decodePaginationPageSync(ref, [\n            item,\n          ])[0] as PaginatedQueryItem<Query>;\n        }\n        const cached = decodeCache.get(item);\n        if (cached !== undefined) {\n          return cached;\n        }\n        const decoded = Ref.decodePaginationPageSync(ref, [\n          item,\n        ])[0] as PaginatedQueryItem<Query>;\n        decodeCache.set(item, decoded);\n        return decoded;\n      }),\n    [ref, encodedItems, decodeCache],\n  );\n\n  return useMemo((): PaginatedQueryResult.Variants<\n    PaginatedQueryItem<Query>,\n    Ref.Error<Query>\n  > => {\n    if (interpretation._tag === \"ResetRequired\") {\n      return PaginatedQueryResult.loadingFirstPage({ skipped });\n    }\n    if (interpretation._tag === \"Failed\") {\n      const error = interpretation.error;\n      if (Ref.isConvexError(error)) {\n        const decoded = Ref.decodeErrorOption(ref, error.data);\n        if (Option.isSome(decoded)) {\n          return PaginatedQueryResult.failure({\n            error: decoded.value,\n            results: decodedResults,\n          });\n        }\n      }\n      // Unknown errors still throw, to be caught by an error boundary.\n      throw error;\n    }\n\n    if (!interpretation.firstPageLoaded) {\n      return PaginatedQueryResult.loadingFirstPage({ skipped });\n    }\n    const { lastResult } = interpretation;\n    if (\n      Option.isNone(lastResult) ||\n      StreamPagination.isLastPageSplitting(current.state)\n    ) {\n      return PaginatedQueryResult.loadingMore({ results: decodedResults });\n    }\n    if (lastResult.value.isDone) {\n      return PaginatedQueryResult.exhausted({ results: decodedResults });\n    }\n\n    const continueCursor = lastResult.value.continueCursor;\n    // A per-result guard, as in `convex-helpers`: calling `loadMore`\n    // repeatedly before the next render is a single load.\n    let alreadyLoadingMore = false;\n    return PaginatedQueryResult.canLoadMore({\n      results: decodedResults,\n      loadMore: (numItems: number) => {\n        if (!alreadyLoadingMore) {\n          alreadyLoadingMore = true;\n          applyTransitions([\n            StreamPagination.loadMore(continueCursor, numItems, options),\n          ]);\n        }\n      },\n    });\n  }, [\n    interpretation,\n    decodedResults,\n    current.state,\n    skipped,\n    ref,\n    applyTransitions,\n  ]) as PaginatedQueryResult.PaginatedQueryResult<\n    PaginatedQueryItem<Query>,\n    Ref.Error<Query>\n  >;\n};\n\n/**\n * An optimistic update for a Confect mutation. Mirrors Convex's\n * `OptimisticUpdate`, but receives a Confect {@link OptimisticLocalStore} and\n * the decoded mutation `args`.\n */\nexport type OptimisticUpdate<Mutation extends Ref.AnyPublicMutation> = (\n  localStore: OptimisticLocalStore.OptimisticLocalStore,\n  args: Ref.Args<Mutation>,\n) => void;\n\n/**\n * The handle returned by {@link useMutation}. It is callable like the function\n * returned by Convex's `useMutation`, and additionally exposes\n * `withOptimisticUpdate` for attaching an optimistic update. Mirrors the\n * `ReactMutation` type from `convex/react`.\n */\nexport interface ReactMutation<Mutation extends Ref.AnyPublicMutation> {\n  (...args: Ref.OptionalArgs<Mutation>): InvokeReturn<Mutation>;\n  withOptimisticUpdate(\n    optimisticUpdate: OptimisticUpdate<Mutation>,\n  ): ReactMutation<Mutation>;\n}\n\nconst makeReactMutation = <Mutation extends Ref.AnyPublicMutation>(\n  ref: Mutation,\n  convexReactMutation: ConvexReactMutation<\n    Ref.FunctionReference<Mutation> & FunctionReference<\"mutation\">\n  >,\n): ReactMutation<Mutation> => {\n  const callable = ((...args: Ref.OptionalArgs<Mutation>) =>\n    invokeAsResult(\n      ref,\n      (_, encodedArgs) => convexReactMutation(encodedArgs as never),\n      args,\n    ).then((result) =>\n      Ref.hasErrorSchema(ref) ? result : Result.getOrThrow(result),\n    )) as (...args: Ref.OptionalArgs<Mutation>) => InvokeReturn<Mutation>;\n\n  const withOptimisticUpdate = (\n    optimisticUpdate: OptimisticUpdate<Mutation>,\n  ): ReactMutation<Mutation> => {\n    const wrappedUpdate: ConvexOptimisticUpdate<Record<string, Value>> = (\n      convexLocalStore,\n      encodedArgs,\n    ) => {\n      const decodedArgs = Ref.decodeArgsSync(ref, encodedArgs);\n      optimisticUpdate(\n        OptimisticLocalStore.make(convexLocalStore),\n        decodedArgs,\n      );\n    };\n    const nextConvexReactMutation =\n      convexReactMutation.withOptimisticUpdate(wrappedUpdate);\n    return makeReactMutation(ref, nextConvexReactMutation);\n  };\n\n  return Object.assign(callable, { withOptimisticUpdate });\n};\n\n/**\n * Returns a {@link ReactMutation} handle for the provided `Ref`'s mutation. The\n * handle is callable to invoke the mutation, and exposes `withOptimisticUpdate`\n * for attaching an optimistic update, mirroring `useMutation` from\n * `convex/react`.\n *\n * If the `Ref` declares an `error` schema, the returned promise resolves to a\n * `Result` with the decoded `returns` value in the `Success` and the decoded\n * error in the `Failure`.\n *\n * If the `Ref` does not declare an `error` schema, the promise resolves\n * directly to the decoded `returns` value, matching the behavior of\n * `useMutation` from `convex/react`.\n *\n * Any other failure rejects the promise.\n */\nexport const useMutation = <Mutation extends Ref.AnyPublicMutation>(\n  ref: Mutation,\n): ReactMutation<Mutation> => {\n  const functionReference = Ref.getFunctionReference(ref);\n  const convexReactMutation = useConvexMutation(functionReference);\n\n  return useMemo(\n    () =>\n      makeReactMutation(\n        ref,\n        convexReactMutation as ConvexReactMutation<\n          Ref.FunctionReference<Mutation> & FunctionReference<\"mutation\">\n        >,\n      ),\n    [ref, convexReactMutation],\n  );\n};\n\n/**\n * Returns a function that invokes the provided `Ref`'s action.\n *\n * If the `Ref` declares an `error` schema, the returned promise resolves to a\n * `Result` with the decoded `returns` value in the `Success` and the decoded\n * error in the `Failure`.\n *\n * If the `Ref` does not declare an `error` schema, the promise resolves\n * directly to the decoded `returns` value, matching the behavior of\n * `useMutation` from `convex/react`.\n *\n * Any other failure rejects the promise.\n */\nexport const useAction = <Action extends Ref.AnyPublicAction>(\n  ref: Action,\n): ((...args: Ref.OptionalArgs<Action>) => InvokeReturn<Action>) => {\n  const functionReference = Ref.getFunctionReference(ref);\n  const actualAction = useConvexAction(functionReference);\n\n  return useCallback(\n    ((...args: Ref.OptionalArgs<Action>) =>\n      invokeAsResult(\n        ref,\n        (_, encodedArgs) => actualAction(encodedArgs),\n        args,\n      ).then((result) =>\n        Ref.hasErrorSchema(ref) ? result : Result.getOrThrow(result),\n      )) as (...args: Ref.OptionalArgs<Action>) => InvokeReturn<Action>,\n    [ref, actualAction],\n  );\n};\n\nconst invokeAsResult = <Ref_ extends Ref.Any>(\n  ref: Ref_,\n  invoke: (\n    fnRef: Ref.FunctionReference<Ref_>,\n    encodedArgs: unknown,\n  ) => PromiseLike<unknown>,\n  args: Ref.OptionalArgs<Ref_>,\n): Promise<Result.Result<Ref.Returns<Ref_>, Ref.Error<Ref_>>> => {\n  const exitPromise = Effect.runPromiseExit(\n    Ref.runWithCodec(ref, (args[0] ?? {}) as Ref.Args<Ref_>, invoke).pipe(\n      Effect.catchTag(\"SchemaError\", Effect.die),\n      Effect.result,\n    ),\n  );\n  return exitPromise.then((exit) => {\n    if (Exit.isSuccess(exit)) return exit.value;\n    throw Cause.squash(exit.cause);\n  });\n};\n"],"mappings":"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"}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@gaganref/confect-react",
-  "version": "10.3.1-fork.3",
+  "version": "10.3.1-fork.31",
   "peerDependencies": {
-    "@confect/core": "npm:@gaganref/confect-core@10.3.1-fork.3",
+    "@confect/core": "npm:@gaganref/confect-core@10.3.1-fork.31",
     "convex": "^1.36.0",
     "effect": "^4.0.0",
     "react": "^18.0.0 || ^19.0.0"

package/src/StreamPagination.ts

@@ -13,7 +13,9 @@
  * Pinning a freshly loaded page, loading more, and splitting an overgrown page
  * are the same transition shape: the affected page keeps rendering while its
  * replacement subscriptions ("ongoing split") load, and is swapped out once all
- * of them have results.
+ * of them have results. A failed replacement fails the render at once, still
+ * showing the affected page and the pages after it, and the swap waits for a
+ * retry.
  *
  * This module is framework-free (it imports only `effect/*` and a type from
  * `convex/server`); it lives here for now because the React hook is its only
@@ -282,9 +284,14 @@ export type PageResult = PaginationResult<unknown>;
 
 /**
  * What one render pass derives from the subscribed pages' results: the items to
- * show, the trailing complete result (absent while the tail is loading or
- * force-splitting), state transitions to apply, and whether a failure or an
- * invalid cursor was hit.
+ * show, whether the first page has loaded, the trailing complete result (absent
+ * while the tail is loading or force-splitting), state transitions to apply
+ * (also while a failure shows, so the other pages keep splitting and swapping),
+ * and whether a failure or an invalid cursor was hit.
+ *
+ * `firstPageLoaded` holds once the head page has its full result. Splits can
+ * leave several pages ahead of the first loaded item, so neither the item count
+ * nor the page count tells a loading first page apart from a loaded empty one.
  */
 export type Interpretation =
   | { readonly _tag: "ResetRequired" }
@@ -292,9 +299,14 @@ export type Interpretation =
       readonly _tag: "Failed";
       readonly error: unknown;
       /**
-       * Encoded items loaded before the failing page.
+       * Encoded items across the loaded pages, in order. A page whose
+       * replacement failed is still shown, and stays subscribed with the
+       * replacement so that a retry re-requests only the replacement. A page
+       * whose own result failed ends the items, since its range is unknown.
        */
       readonly items: ReadonlyArray<unknown>;
+      readonly firstPageLoaded: boolean;
+      readonly transitions: ReadonlyArray<(state: State) => State>;
     }
   | {
       readonly _tag: "Interpreted";
@@ -302,6 +314,7 @@ export type Interpretation =
        * Encoded items across the loaded pages, in order.
        */
       readonly items: ReadonlyArray<unknown>;
+      readonly firstPageLoaded: boolean;
       /**
        * The last page's result, when every page has loaded completely.
        */
@@ -312,12 +325,6 @@ export type Interpretation =
       readonly transitions: ReadonlyArray<(state: State) => State>;
     };
 
-const interpreted = (
-  items: ReadonlyArray<unknown>,
-  lastResult: Option.Option<PageResult>,
-  transitions: ReadonlyArray<(state: State) => State>,
-): Interpretation => ({ _tag: "Interpreted", items, lastResult, transitions });
-
 /**
  * Walk the pages in display order, concatenating their items and collecting the
  * transitions to apply (completed split swaps, recommended splits, eager splits
@@ -334,39 +341,97 @@ export const interpret = (
     readonly isInvalidCursorError: (error: Error) => boolean;
   },
 ): Interpretation => {
+  const resultOf = (key: string) =>
+    Record.get(results, key).pipe(
+      Option.flatMap(Option.fromNullishOr),
+      Option.getOrUndefined,
+    );
+  const firstPageLoaded = Option.exists(Array.head(state.pageKeys), (key) => {
+    const result = resultOf(key);
+    return (
+      result !== undefined &&
+      !(result instanceof Error) &&
+      result.pageStatus !== "SplitRequired"
+    );
+  });
+  // The first error in display order is the one reported.
+  const finish = (
+    items: ReadonlyArray<unknown>,
+    lastResult: Option.Option<PageResult>,
+    transitions: ReadonlyArray<(state: State) => State>,
+    errors: ReadonlyArray<Error>,
+  ): Interpretation =>
+    Array.some(errors, options.isInvalidCursorError)
+      ? { _tag: "ResetRequired" }
+      : Option.match(Array.head(errors), {
+          onNone: () => ({
+            _tag: "Interpreted",
+            items,
+            firstPageLoaded,
+            lastResult,
+            transitions,
+          }),
+          onSome: (error) => ({
+            _tag: "Failed",
+            error,
+            items,
+            firstPageLoaded,
+            transitions,
+          }),
+        });
+
   const go = (
     remaining: ReadonlyArray<string>,
     items: ReadonlyArray<unknown>,
     transitions: ReadonlyArray<(s: State) => State>,
     lastResult: Option.Option<PageResult>,
+    errors: ReadonlyArray<Error>,
   ): Interpretation =>
     Option.match(Array.head(remaining), {
-      onNone: () => interpreted(items, lastResult, transitions),
+      onNone: () => finish(items, lastResult, transitions, errors),
       onSome: (pageKey) => {
-        const result = Record.get(results, pageKey).pipe(
-          Option.flatMap(Option.fromNullishOr),
-          Option.getOrUndefined,
-        );
+        const result = resultOf(pageKey);
         if (result === undefined) {
           // The trailing pages are still loading.
-          return interpreted(items, Option.none(), transitions);
+          return finish(items, Option.none(), transitions, errors);
         }
         if (result instanceof Error) {
-          return options.isInvalidCursorError(result)
-            ? { _tag: "ResetRequired" }
-            : { _tag: "Failed", error: result, items };
+          return finish(
+            items,
+            Option.none(),
+            transitions,
+            Array.append(errors, result),
+          );
         }
+        // A force-split page couldn't be fetched in full: show the items
+        // before it and report the tail as still loading.
+        const shown =
+          result.pageStatus === "SplitRequired"
+            ? items
+            : Array.appendAll(items, result.page);
 
-        const hasResult = (key: string) =>
-          Record.get(results, key).pipe(
-            Option.flatMap(Option.fromNullishOr),
-            Option.isSome,
-          );
         const ongoingSplit = Record.get(state.ongoingSplits, pageKey);
+        // A failed replacement leaves this page shown and its range pinned, so
+        // the pages after it stay contiguous and the walk goes on.
+        const replacementResults = Option.match(ongoingSplit, {
+          onNone: () => [],
+          onSome: Array.map(resultOf),
+        });
+        const nextErrors = Array.appendAll(
+          errors,
+          Array.filter(
+            replacementResults,
+            (replacement) => replacement instanceof Error,
+          ),
+        );
         const nextTransitions = Option.match(ongoingSplit, {
-          onSome: (replacements) =>
-            // Swap the replacements in once all of them have results.
-            Array.every(replacements, hasResult)
+          onSome: () =>
+            // Swap the replacements in once all of them have loaded.
+            Array.every(
+              replacementResults,
+              (replacement) =>
+                replacement !== undefined && !(replacement instanceof Error),
+            )
               ? Array.append(transitions, completeSplit(pageKey))
               : transitions,
           onNone: () =>
@@ -386,18 +451,17 @@ export const interpret = (
                 : transitions,
         });
 
-        // A force-split page couldn't be fetched in full: show the items
-        // before it and report the tail as still loading.
         return result.pageStatus === "SplitRequired"
-          ? interpreted(items, Option.none(), nextTransitions)
+          ? finish(shown, Option.none(), nextTransitions, nextErrors)
           : go(
               Array.drop(remaining, 1),
-              Array.appendAll(items, result.page),
+              shown,
               nextTransitions,
               Option.some(result),
+              nextErrors,
             );
       },
     });
 
-  return go(state.pageKeys, [], [], Option.none());
+  return go(state.pageKeys, [], [], Option.none(), []);
 };

package/src/index.ts

@@ -20,10 +20,10 @@ import * as Match from "effect/Match";
 import * as Option from "effect/Option";
 import { useCallback, useMemo, useState } from "react";
 
-import * as OptimisticLocalStore from "./OptimisticLocalStore";
-import * as PaginatedQueryResult from "./PaginatedQueryResult";
-import * as QueryResult from "./QueryResult";
-import * as StreamPagination from "./StreamPagination";
+import * as OptimisticLocalStore from "./OptimisticLocalStore.js";
+import * as PaginatedQueryResult from "./PaginatedQueryResult.js";
+import * as QueryResult from "./QueryResult.js";
+import * as StreamPagination from "./StreamPagination.js";
 
 export {
   OptimisticLocalStore,
@@ -489,10 +489,7 @@ export const useStreamPaginatedQuery = <
       resetKey: previous.resetKey,
       state: freshState(),
     }));
-  } else if (
-    interpretation._tag === "Interpreted" &&
-    interpretation.transitions.length > 0
-  ) {
+  } else if (interpretation.transitions.length > 0) {
     applyTransitions(interpretation.transitions);
   }
 
@@ -549,10 +546,10 @@ export const useStreamPaginatedQuery = <
       throw error;
     }
 
-    const { lastResult } = interpretation;
-    if (Option.isNone(lastResult) && current.state.pageKeys.length <= 1) {
+    if (!interpretation.firstPageLoaded) {
       return PaginatedQueryResult.loadingFirstPage({ skipped });
     }
+    const { lastResult } = interpretation;
     if (
       Option.isNone(lastResult) ||
       StreamPagination.isLastPageSplitting(current.state)