convex-helpers 0.1.91 → 0.1.92

package/bin.cjs

@@ -3747,8 +3747,8 @@ function generateApiSpec(functionSpec, includeInternal) {
     includeInternal ? internalFunctionTree : {}
   );
   return `
-import { FunctionReference, anyApi } from "convex/server"
-import { GenericId as Id } from "convex/values"
+import { type FunctionReference, anyApi } from "convex/server"
+import { type GenericId as Id } from "convex/values"
 
 export const api: PublicApiType = anyApi as unknown as PublicApiType;
 export const internal: InternalApiType = anyApi as unknown as InternalApiType;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "convex-helpers",
-  "version": "0.1.91",
+  "version": "0.1.92",
   "description": "A collection of useful code to complement the official convex package.",
   "type": "module",
   "bin": {

package/react/cache/hooks.d.ts

@@ -73,6 +73,10 @@ export declare function useQuery<Query extends FunctionReference<"query">>(query
 /**
  * Load data reactively from a paginated query to a create a growing list.
  *
+ * Note: This is a modified version of the original `usePaginatedQuery` hook.
+ * The main difference (aside from subscriptions staying active longer) is that
+ * the `latestPageSize` option is "fixed" by default.
+ *
  * This can be used to power "infinite scroll" UIs.
  *
  * This hook must be used with public query references that match
@@ -101,22 +105,13 @@ export declare function useQuery<Query extends FunctionReference<"query">>(query
  * @param args - The arguments object for the query function, excluding
  * the `paginationOpts` property. That property is injected by this hook.
  * @param options - An object specifying the `initialNumItems` to be loaded in
- * the first page, and the `endCursorBehavior` to use.
- * @param options.endCursorBehavior` controls how the `endCursor` is set on the
- * last loaded page. The current behavior is to have the first request for a page
- * "pin" the end of the page to the `endCursor` returned in the first request.
- * This shows up as your first request growing as new items are added within
- * the range of the initial page. This is tracked via a QueryJournal, which is
- * not shared between clients and can have unexpected behavior, so we will be
- * deprecating this behavior in favor of the new option `setOnLoadMore`.
- * For `setOnLoadMore`, the `endCursor` is not inferred from the first request,
- * instead the first call to `loadMore` will explicitly set the `endCursor` to
- * the `continueCursor` of the last page. In the future this will not use the
- * QueryJournal and will become the default behavior, resulting in the first
- * page staying at the same size as `initialNumItems` until you call `loadMore`.
- * Note: setting the `endCursor` on the request will re-request that page with
- * the new argument, causing an effectively duplicate request per `loadMore`.
- *
+ * the first page, and the `latestPageSize` to use.
+ * @param options.latestPageSize controls how the latest page (the first page
+ * until another page is loaded) size grows. With "fixed", the page size will
+ * stay at the size specified by `initialNumItems` / `loadMore`. With "grow",
+ * the page size will grow as new items are added within the range of the initial
+ * page. Once multiple pages are loaded, all but the last page will grow, in
+ * order to provide seamless pagination. See the docs for more details.
  * @returns A {@link UsePaginatedQueryResult} that includes the currently loaded
  * items, the status of the pagination, and a `loadMore` function.
  *
@@ -124,6 +119,6 @@ export declare function useQuery<Query extends FunctionReference<"query">>(query
  */
 export declare function usePaginatedQuery<Query extends PaginatedQueryReference>(query: Query, args: PaginatedQueryArgs<Query> | "skip", options: {
     initialNumItems: number;
-    endCursorBehavior?: "setOnLoadMore" | "legacyQueryJournal";
+    latestPageSize?: "grow" | "fixed";
 }): UsePaginatedQueryReturnType<Query>;
 //# sourceMappingURL=hooks.d.ts.map

package/react/cache/hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sBAAsB,EACtB,kBAAkB,EAClB,uBAAuB,EACvB,iBAAiB,EACjB,2BAA2B,EAC5B,MAAM,cAAc,CAAC;AAMtB,OAAO,KAAK,EAEV,iBAAiB,EACjB,kBAAkB,EAInB,MAAM,eAAe,CAAC;AAkBvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,iBAAiB,GACzB,MAAM,CAAC,MAAM,EAAE,GAAG,GAAG,SAAS,GAAG,KAAK,CAAC,CAiCzC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CAAC,KAAK,SAAS,iBAAiB,CAAC,OAAO,CAAC,EAC/D,KAAK,EAAE,KAAK,EACZ,GAAG,SAAS,EAAE,sBAAsB,CAAC,KAAK,CAAC,GAC1C,kBAAkB,CAAC,KAAK,CAAC,GAAG,SAAS,CAoBvC;AAoHD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,SAAS,uBAAuB,EACrE,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,kBAAkB,CAAC,KAAK,CAAC,GAAG,MAAM,EACxC,OAAO,EAAE;IACP,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,CAAC,EAAE,eAAe,GAAG,oBAAoB,CAAC;CAC5D,GACA,2BAA2B,CAAC,KAAK,CAAC,CAqPpC"}
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sBAAsB,EACtB,kBAAkB,EAClB,uBAAuB,EACvB,iBAAiB,EACjB,2BAA2B,EAC5B,MAAM,cAAc,CAAC;AAMtB,OAAO,KAAK,EAEV,iBAAiB,EACjB,kBAAkB,EAInB,MAAM,eAAe,CAAC;AAkBvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,iBAAiB,GACzB,MAAM,CAAC,MAAM,EAAE,GAAG,GAAG,SAAS,GAAG,KAAK,CAAC,CAiCzC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CAAC,KAAK,SAAS,iBAAiB,CAAC,OAAO,CAAC,EAC/D,KAAK,EAAE,KAAK,EACZ,GAAG,SAAS,EAAE,sBAAsB,CAAC,KAAK,CAAC,GAC1C,kBAAkB,CAAC,KAAK,CAAC,GAAG,SAAS,CAoBvC;AAoHD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,SAAS,uBAAuB,EACrE,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,kBAAkB,CAAC,KAAK,CAAC,GAAG,MAAM,EACxC,OAAO,EAAE;IACP,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC,GACA,2BAA2B,CAAC,KAAK,CAAC,CAqPpC"}

package/react/cache/hooks.js

@@ -202,6 +202,10 @@ const completeSplitQuery = (key) => (prevState) => {
 /**
  * Load data reactively from a paginated query to a create a growing list.
  *
+ * Note: This is a modified version of the original `usePaginatedQuery` hook.
+ * The main difference (aside from subscriptions staying active longer) is that
+ * the `latestPageSize` option is "fixed" by default.
+ *
  * This can be used to power "infinite scroll" UIs.
  *
  * This hook must be used with public query references that match
@@ -230,22 +234,13 @@ const completeSplitQuery = (key) => (prevState) => {
  * @param args - The arguments object for the query function, excluding
  * the `paginationOpts` property. That property is injected by this hook.
  * @param options - An object specifying the `initialNumItems` to be loaded in
- * the first page, and the `endCursorBehavior` to use.
- * @param options.endCursorBehavior` controls how the `endCursor` is set on the
- * last loaded page. The current behavior is to have the first request for a page
- * "pin" the end of the page to the `endCursor` returned in the first request.
- * This shows up as your first request growing as new items are added within
- * the range of the initial page. This is tracked via a QueryJournal, which is
- * not shared between clients and can have unexpected behavior, so we will be
- * deprecating this behavior in favor of the new option `setOnLoadMore`.
- * For `setOnLoadMore`, the `endCursor` is not inferred from the first request,
- * instead the first call to `loadMore` will explicitly set the `endCursor` to
- * the `continueCursor` of the last page. In the future this will not use the
- * QueryJournal and will become the default behavior, resulting in the first
- * page staying at the same size as `initialNumItems` until you call `loadMore`.
- * Note: setting the `endCursor` on the request will re-request that page with
- * the new argument, causing an effectively duplicate request per `loadMore`.
- *
+ * the first page, and the `latestPageSize` to use.
+ * @param options.latestPageSize controls how the latest page (the first page
+ * until another page is loaded) size grows. With "fixed", the page size will
+ * stay at the size specified by `initialNumItems` / `loadMore`. With "grow",
+ * the page size will grow as new items are added within the range of the initial
+ * page. Once multiple pages are loaded, all but the last page will grow, in
+ * order to provide seamless pagination. See the docs for more details.
  * @returns A {@link UsePaginatedQueryResult} that includes the currently loaded
  * items, the status of the pagination, and a `loadMore` function.
  *
@@ -416,7 +411,7 @@ export function usePaginatedQuery(query, args, options) {
                         const queries = { ...prevState.queries };
                         let ongoingSplits = prevState.ongoingSplits;
                         let pageKeys = prevState.pageKeys;
-                        if (options.endCursorBehavior === "setOnLoadMore") {
+                        if (options.latestPageSize !== "grow") {
                             const lastPageKey = prevState.pageKeys.at(-1);
                             const boundLastPageKey = nextPageKey;
                             queries[boundLastPageKey] = {
@@ -462,7 +457,7 @@ export function usePaginatedQuery(query, args, options) {
                 }
             },
         };
-    }, [maybeLastResult, currState.nextPageKey, options.endCursorBehavior]);
+    }, [maybeLastResult, currState.nextPageKey, options.latestPageSize]);
     return {
         results,
         ...statusObject,

package/react/cache/hooks.ts

@@ -282,6 +282,10 @@ const completeSplitQuery =
 /**
  * Load data reactively from a paginated query to a create a growing list.
  *
+ * Note: This is a modified version of the original `usePaginatedQuery` hook.
+ * The main difference (aside from subscriptions staying active longer) is that
+ * the `latestPageSize` option is "fixed" by default.
+ *
  * This can be used to power "infinite scroll" UIs.
  *
  * This hook must be used with public query references that match
@@ -310,22 +314,13 @@ const completeSplitQuery =
  * @param args - The arguments object for the query function, excluding
  * the `paginationOpts` property. That property is injected by this hook.
  * @param options - An object specifying the `initialNumItems` to be loaded in
- * the first page, and the `endCursorBehavior` to use.
- * @param options.endCursorBehavior` controls how the `endCursor` is set on the
- * last loaded page. The current behavior is to have the first request for a page
- * "pin" the end of the page to the `endCursor` returned in the first request.
- * This shows up as your first request growing as new items are added within
- * the range of the initial page. This is tracked via a QueryJournal, which is
- * not shared between clients and can have unexpected behavior, so we will be
- * deprecating this behavior in favor of the new option `setOnLoadMore`.
- * For `setOnLoadMore`, the `endCursor` is not inferred from the first request,
- * instead the first call to `loadMore` will explicitly set the `endCursor` to
- * the `continueCursor` of the last page. In the future this will not use the
- * QueryJournal and will become the default behavior, resulting in the first
- * page staying at the same size as `initialNumItems` until you call `loadMore`.
- * Note: setting the `endCursor` on the request will re-request that page with
- * the new argument, causing an effectively duplicate request per `loadMore`.
- *
+ * the first page, and the `latestPageSize` to use.
+ * @param options.latestPageSize controls how the latest page (the first page
+ * until another page is loaded) size grows. With "fixed", the page size will
+ * stay at the size specified by `initialNumItems` / `loadMore`. With "grow",
+ * the page size will grow as new items are added within the range of the initial
+ * page. Once multiple pages are loaded, all but the last page will grow, in
+ * order to provide seamless pagination. See the docs for more details.
  * @returns A {@link UsePaginatedQueryResult} that includes the currently loaded
  * items, the status of the pagination, and a `loadMore` function.
  *
@@ -336,7 +331,7 @@ export function usePaginatedQuery<Query extends PaginatedQueryReference>(
   args: PaginatedQueryArgs<Query> | "skip",
   options: {
     initialNumItems: number;
-    endCursorBehavior?: "setOnLoadMore" | "legacyQueryJournal";
+    latestPageSize?: "grow" | "fixed";
   },
 ): UsePaginatedQueryReturnType<Query> {
   if (
@@ -532,7 +527,7 @@ export function usePaginatedQuery<Query extends PaginatedQueryReference>(
             const queries = { ...prevState.queries };
             let ongoingSplits = prevState.ongoingSplits;
             let pageKeys = prevState.pageKeys;
-            if (options.endCursorBehavior === "setOnLoadMore") {
+            if (options.latestPageSize !== "grow") {
               const lastPageKey = prevState.pageKeys.at(-1)!;
               const boundLastPageKey = nextPageKey;
               queries[boundLastPageKey] = {
@@ -577,7 +572,7 @@ export function usePaginatedQuery<Query extends PaginatedQueryReference>(
         }
       },
     } as const;
-  }, [maybeLastResult, currState.nextPageKey, options.endCursorBehavior]);
+  }, [maybeLastResult, currState.nextPageKey, options.latestPageSize]);
 
   return {
     results,