npm - convex-helpers - Versions diffs - 0.1.41 → 0.1.42 - Mend

convex-helpers 0.1.41 → 0.1.42

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (18) hide show

package/README.md +69 -4
package/dist/react/cache/hooks.d.ts +73 -0
package/dist/react/cache/hooks.d.ts.map +1 -0
package/dist/react/cache/hooks.js +140 -0
package/dist/react/cache/provider.d.ts +69 -0
package/dist/react/cache/provider.d.ts.map +1 -0
package/dist/react/cache/provider.js +142 -0
package/dist/react/index.d.ts +70 -2
package/dist/react/index.d.ts.map +1 -1
package/dist/react/index.js +95 -46
package/dist/tsconfig.tsbuildinfo +1 -1
package/package.json +11 -3
package/react/cache/hooks.ts +171 -0
package/react/cache/provider.tsx +212 -0
package/react/index.ts +122 -72
package/dist/server/_generated/_ignore.d.ts +0 -2
package/dist/server/_generated/_ignore.d.ts.map +0 -1
package/dist/server/_generated/_ignore.js +0 -2

package/README.md CHANGED Viewed

@@ -17,6 +17,7 @@ Table of contents:
 - [CRUD](#crud-utilities)
 - [Validator utilities](#validator-utilities)
 - [Filter db queries with JS](#filter)
+- [Query caching with ConvexQueryCacheProvider](#query-caching)
 ## Custom Functions
@@ -373,10 +374,13 @@ By default, `useQuery` will throw an error when the server throws. It also
 returns `undefined` to indicate a "loading" state. This helper returns:
 ```ts
-const { status, data, error, isSuccess, isPending, isError } = useQuery(
-  api.foo.bar,
-  { myArg: 123 },
-);
+import { makeUseQueryWithStatus } from "convex-helpers/react";
+import { useQueries } from "convex/react";
+// Do this once somewhere, name it whatever you want.
+export const useQueryWithStatus = makeUseQueryWithStatus(useQueries);
+const { status, data, error, isSuccess, isPending, isError } =
+  useQueryWithStatus(api.foo.bar, { myArg: 123 });
 ```
 The types of the return is:
@@ -630,3 +634,64 @@ export const lastCountLongerThanName = query({
   },
 });
 ```
+## Query Caching
+Utilize a query cache implementation which persists subscriptions to the
+server for some expiration period even after app `useQuery` hooks have all
+unmounted. This allows very fast reloading of unevicted values during
+navigation changes, view changes, etc.
+Related files:
+- [provider.tsx](./react/cache/provider.tsx) contains `ConvexQueryCacheProvider`,
+  a configurable cache provider you put in your react app's root.
+- [hooks.ts](./react/cache/hooks.ts) contains cache-enabled drop-in
+  replacements for both `useQuery` and `useQueries` from `convex/react`.
+To use the cache, first make sure to put a `<ConvexQueryCacheProvider>`
+inside `<ConvexProvider>` in your react component tree:
+```jsx
+import { ConvexQueryCacheProvider } from "convex-helpers/react/cache/provider";
+//...
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html lang="en">
+      <body className={inter.className}>
+        <ConvexClientProvider>
+          <ConvexQueryCacheProvider>{children}</ConvexQueryCacheProvider>
+        </ConvexClientProvider>
+      </body>
+    </html>
+  );
+}
+```
+This provider takes three optional props:
+- **expiration** (number) -- Milliseconds to preserve unmounted subscriptions
+  in the cache. After this, the subscriptions will be dropped, and the value
+  will have to be re-fetched from the server. (Default: 300000, aka 5 minutes)
+- **maxIdleEntires** (number) -- Maximum number of unused subscriptions
+  kept in the cache. (Default: 250).
+- **debug** (boolean) -- Dump console logs every 3s to debug the state of
+  the cache (Default: false).
+Finally, you can utilize `useQuery` (and `useQueries`) just the same as
+their `convex/react` equivalents.
+```jsx
+import { useQuery } from "convex-helpers/react/cache/hooks";
+// ...
+const users = useQuery(api.users.getAll);
+```

package/dist/react/cache/hooks.d.ts ADDED Viewed

@@ -0,0 +1,73 @@
+import { OptionalRestArgsOrSkip, RequestForQueries } from "convex/react";
+import { FunctionReference, FunctionReturnType } from "convex/server";
+/**
+ * Load a variable number of reactive Convex queries, utilizing
+ * the query cache.
+ *
+ * `useQueries` is similar to {@link useQuery} but it allows
+ * loading multiple queries which can be useful for loading a dynamic number
+ * of queries without violating the rules of React hooks.
+ *
+ * This hook accepts an object whose keys are identifiers for each query and the
+ * values are objects of `{ query: FunctionReference, args: Record<string, Value> }`. The
+ * `query` is a FunctionReference for the Convex query function to load, and the `args` are
+ * the arguments to that function.
+ *
+ * The hook returns an object that maps each identifier to the result of the query,
+ * `undefined` if the query is still loading, or an instance of `Error` if the query
+ * threw an exception.
+ *
+ * For example if you loaded a query like:
+ * ```typescript
+ * const results = useQueries({
+ *   messagesInGeneral: {
+ *     query: "listMessages",
+ *     args: { channel: "#general" }
+ *   }
+ * });
+ * ```
+ * then the result would look like:
+ * ```typescript
+ * {
+ *   messagesInGeneral: [{
+ *     channel: "#general",
+ *     body: "hello"
+ *     _id: ...,
+ *     _creationTime: ...
+ *   }]
+ * }
+ * ```
+ *
+ * This React hook contains internal state that will cause a rerender
+ * whenever any of the query results change.
+ *
+ * Throws an error if not used under {@link ConvexProvider}.
+ *
+ * @param queries - An object mapping identifiers to objects of
+ * `{query: string, args: Record<string, Value> }` describing which query
+ * functions to fetch.
+ * @returns An object with the same keys as the input. The values are the result
+ * of the query function, `undefined` if it's still loading, or an `Error` if
+ * it threw an exception.
+ *
+ * @public
+ */
+export declare function useQueries(queries: RequestForQueries): Record<string, any | undefined | Error>;
+/**
+ * Load a reactive query within a React component.
+ *
+ * This React hook contains internal state that will cause a rerender
+ * whenever the query result changes.
+ *
+ * Throws an error if not used under {@link ConvexProvider} and {@link ConvexQueryCacheProvider}.
+ *
+ * @param query - a {@link FunctionReference} for the public query to run
+ * like `api.dir1.dir2.filename.func`.
+ * @param args - The arguments to the query function or the string "skip" if the
+ * query should not be loaded.
+ * @returns the result of the query. If the query is loading returns `undefined`.
+ *
+ * @public
+ */
+export declare function useQuery<Query extends FunctionReference<"query">>(query: Query, ...queryArgs: OptionalRestArgsOrSkip<Query>): FunctionReturnType<Query>;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/react/cache/hooks.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../../react/cache/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,sBAAsB,EACtB,iBAAiB,EAClB,MAAM,cAAc,CAAC;AACtB,OAAO,EAEL,iBAAiB,EACjB,kBAAkB,EAEnB,MAAM,eAAe,CAAC;AAKvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,iBAAiB,GACzB,MAAM,CAAC,MAAM,EAAE,GAAG,GAAG,SAAS,GAAG,KAAK,CAAC,CA4CzC;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,CAoB3B"}

package/dist/react/cache/hooks.js ADDED Viewed

@@ -0,0 +1,140 @@
+import { getFunctionName, } from "convex/server";
+import { useContext, useEffect, useState } from "react";
+import { ConvexQueryCacheContext } from "./provider.js";
+import { convexToJson } from "convex/values";
+/**
+ * Load a variable number of reactive Convex queries, utilizing
+ * the query cache.
+ *
+ * `useQueries` is similar to {@link useQuery} but it allows
+ * loading multiple queries which can be useful for loading a dynamic number
+ * of queries without violating the rules of React hooks.
+ *
+ * This hook accepts an object whose keys are identifiers for each query and the
+ * values are objects of `{ query: FunctionReference, args: Record<string, Value> }`. The
+ * `query` is a FunctionReference for the Convex query function to load, and the `args` are
+ * the arguments to that function.
+ *
+ * The hook returns an object that maps each identifier to the result of the query,
+ * `undefined` if the query is still loading, or an instance of `Error` if the query
+ * threw an exception.
+ *
+ * For example if you loaded a query like:
+ * ```typescript
+ * const results = useQueries({
+ *   messagesInGeneral: {
+ *     query: "listMessages",
+ *     args: { channel: "#general" }
+ *   }
+ * });
+ * ```
+ * then the result would look like:
+ * ```typescript
+ * {
+ *   messagesInGeneral: [{
+ *     channel: "#general",
+ *     body: "hello"
+ *     _id: ...,
+ *     _creationTime: ...
+ *   }]
+ * }
+ * ```
+ *
+ * This React hook contains internal state that will cause a rerender
+ * whenever any of the query results change.
+ *
+ * Throws an error if not used under {@link ConvexProvider}.
+ *
+ * @param queries - An object mapping identifiers to objects of
+ * `{query: string, args: Record<string, Value> }` describing which query
+ * functions to fetch.
+ * @returns An object with the same keys as the input. The values are the result
+ * of the query function, `undefined` if it's still loading, or an `Error` if
+ * it threw an exception.
+ *
+ * @public
+ */
+export function useQueries(queries) {
+    const { registry } = useContext(ConvexQueryCacheContext);
+    if (registry === null) {
+        throw new Error("Could not find `ConvexQueryCacheContext`! This `useQuery` implementation must be used in the React component " +
+            "tree under `ConvexQueryCacheProvider`. Did you forget it? ");
+    }
+    const queryKeys = {};
+    const results = {};
+    for (const [key, { query, args }] of Object.entries(queries)) {
+        const queryKey = createQueryKey(query, args);
+        results[key] = registry.probe(queryKey);
+        queryKeys[key] = queryKey;
+    }
+    const [_, setValues] = useState(results);
+    useEffect(() => {
+        const ids = [];
+        for (const [key, { query, args }] of Object.entries(queries)) {
+            const id = crypto.randomUUID();
+            registry.start(id, queryKeys[key], query, args, (v) => setValues((old) => {
+                if (!(key in old))
+                    return old; // We're no longer tracking this query
+                if (old[key] === v)
+                    return old; // No change
+                return { ...old, [key]: v };
+            }));
+            ids.push(id);
+        }
+        return () => {
+            for (const id of ids) {
+                registry.end(id);
+            }
+        };
+    },
+    // Safe to ignore query and args since queryKey is derived from them
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [registry, JSON.stringify(queryKeys)]);
+    return results;
+}
+/**
+ * Load a reactive query within a React component.
+ *
+ * This React hook contains internal state that will cause a rerender
+ * whenever the query result changes.
+ *
+ * Throws an error if not used under {@link ConvexProvider} and {@link ConvexQueryCacheProvider}.
+ *
+ * @param query - a {@link FunctionReference} for the public query to run
+ * like `api.dir1.dir2.filename.func`.
+ * @param args - The arguments to the query function or the string "skip" if the
+ * query should not be loaded.
+ * @returns the result of the query. If the query is loading returns `undefined`.
+ *
+ * @public
+ */
+export function useQuery(query, ...queryArgs) {
+    const args = queryArgs[0] ?? {};
+    // Unlike the regular useQuery implementation, we don't need to memoize
+    // the params here, since the cached useQueries will handle that.
+    const results = useQueries(args === "skip"
+        ? {} // Use queries doesn't support skip.
+        : {
+            _default: { query, args },
+        });
+    // This may be undefined either because the upstream
+    // value is actually undefined, or because the value
+    // was not sent to `useQueries` due to "skip".
+    const result = results._default;
+    if (result instanceof Error) {
+        throw result;
+    }
+    return result;
+}
+/**
+ * Generate a query key from a query function and its arguments.
+ * @param query Query function reference like api.foo.bar
+ * @param args Arguments to the function, like { foo: "bar" }
+ * @returns A string key that uniquely identifies the query and its arguments.
+ */
+function createQueryKey(query, args) {
+    const queryString = getFunctionName(query);
+    const key = [queryString, convexToJson(args)];
+    const queryKey = JSON.stringify(key);
+    return queryKey;
+}

package/dist/react/cache/provider.d.ts ADDED Viewed

@@ -0,0 +1,69 @@
+import { ConvexReactClient } from "convex/react";
+import { FunctionArgs, FunctionReference, FunctionReturnType } from "convex/server";
+import { FC, PropsWithChildren } from "react";
+export declare const ConvexQueryCacheContext: import("react").Context<{
+    registry: CacheRegistry | null;
+}>;
+/**
+ * A provider that establishes a query cache context in the React render
+ * tree so that cached `useQuery` calls can be used.
+ *
+ * @component
+ * @param {ConvexQueryCacheOptions} props.options - Options for the query cache
+ * @returns {Element}
+ */
+export declare const ConvexQueryCacheProvider: FC<PropsWithChildren<ConvexQueryCacheOptions>>;
+export type ConvexQueryCacheOptions = {
+    /**
+     * How long, in milliseconds, to keep the subscription to the convex
+     * query alive even after all references in the app have been dropped.
+     *
+     * @default 300000
+     */
+    expiration?: number;
+    /**
+     * How many "extra" idle query subscriptions are allowed to remain
+     * connected to your convex backend.
+     *
+     * @default Infinity
+     */
+    maxIdleEntries?: number;
+    /**
+     * A debug flag that will cause information about the query cache
+     * to be logged to the console every 3 seconds.
+     *
+     * @default false
+     */
+    debug?: boolean;
+};
+/**
+ * Implementation of the query cache.
+ */
+type SubKey = string;
+type QueryKey = string;
+type CachedQuery<Query extends FunctionReference<"query">> = {
+    refs: Set<string>;
+    evictTimer: number | null;
+    unsub?: () => void;
+    value?: FunctionReturnType<Query> | Error;
+};
+type SubEntry<Query extends FunctionReference<"query">> = {
+    queryKey: QueryKey;
+    setter: (v?: FunctionReturnType<Query>) => void;
+};
+declare class CacheRegistry {
+    #private;
+    queries: Map<QueryKey, CachedQuery<FunctionReference<"query">>>;
+    subs: Map<SubKey, SubEntry<FunctionReference<"query">>>;
+    convex: ConvexReactClient;
+    timeout: number;
+    maxIdleEntries: number;
+    idle: number;
+    constructor(convex: ConvexReactClient, options: ConvexQueryCacheOptions);
+    probe<Query extends FunctionReference<"query">>(queryKey: QueryKey): FunctionReturnType<Query> | undefined;
+    start<Query extends FunctionReference<"query">>(id: string, queryKey: string, query: Query, args: FunctionArgs<Query>, setter: (v: FunctionReturnType<Query>) => void): void;
+    end(id: string): void;
+    debug(): void;
+}
+export {};
+//# sourceMappingURL=provider.d.ts.map

package/dist/react/cache/provider.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../../react/cache/provider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAa,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAiB,EAAE,EAAE,iBAAiB,EAAE,MAAM,OAAO,CAAC;AAE7D,eAAO,MAAM,uBAAuB;;EAElC,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,EAAE,EAAE,CACvC,iBAAiB,CAAC,uBAAuB,CAAC,CAgB3C,CAAC;AAKF,MAAM,MAAM,uBAAuB,GAAG;IACpC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF;;GAEG;AAEH,KAAK,MAAM,GAAG,MAAM,CAAC;AACrB,KAAK,QAAQ,GAAG,MAAM,CAAC;AACvB,KAAK,WAAW,CAAC,KAAK,SAAS,iBAAiB,CAAC,OAAO,CAAC,IAAI;IAC3D,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC;IACnB,KAAK,CAAC,EAAE,kBAAkB,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC;CAC3C,CAAC;AACF,KAAK,QAAQ,CAAC,KAAK,SAAS,iBAAiB,CAAC,OAAO,CAAC,IAAI;IACxD,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,kBAAkB,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC;CACjD,CAAC;AAGF,cAAM,aAAa;;IACjB,OAAO,EAAE,GAAG,CAAC,QAAQ,EAAE,WAAW,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAChE,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACxD,MAAM,EAAE,iBAAiB,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;gBAED,MAAM,EAAE,iBAAiB,EAAE,OAAO,EAAE,uBAAuB;IA0BvE,KAAK,CAAC,KAAK,SAAS,iBAAiB,CAAC,OAAO,CAAC,EAC5C,QAAQ,EAAE,QAAQ,GACjB,kBAAkB,CAAC,KAAK,CAAC,GAAG,SAAS;IAMxC,KAAK,CAAC,KAAK,SAAS,iBAAiB,CAAC,OAAO,CAAC,EAC5C,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,YAAY,CAAC,KAAK,CAAC,EACzB,MAAM,EAAE,CAAC,CAAC,EAAE,kBAAkB,CAAC,KAAK,CAAC,KAAK,IAAI,GAC7C,IAAI;IAoCP,GAAG,CAAC,EAAE,EAAE,MAAM;IA0Bd,KAAK;CAeN"}

package/dist/react/cache/provider.js ADDED Viewed

@@ -0,0 +1,142 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useConvex } from "convex/react";
+import { createContext } from "react";
+export const ConvexQueryCacheContext = createContext({
+    registry: null,
+});
+/**
+ * A provider that establishes a query cache context in the React render
+ * tree so that cached `useQuery` calls can be used.
+ *
+ * @component
+ * @param {ConvexQueryCacheOptions} props.options - Options for the query cache
+ * @returns {Element}
+ */
+export const ConvexQueryCacheProvider = ({ children, ...options }) => {
+    const convex = useConvex();
+    if (convex === undefined) {
+        throw new Error("Could not find Convex client! `ConvexQueryCacheProvider` must be used in the React component " +
+            "tree under `ConvexProvider`. Did you forget it? " +
+            "See https://docs.convex.dev/quick-start#set-up-convex-in-your-react-app");
+    }
+    const registry = new CacheRegistry(convex, options);
+    return (_jsx(ConvexQueryCacheContext.Provider, { value: { registry }, children: children }));
+};
+const DEFAULT_EXPIRATION_MS = 300_000; // 5 minutes
+const DEFAULT_MAX_ENTRIES = 250;
+// Core caching structure.
+class CacheRegistry {
+    queries;
+    subs;
+    convex;
+    timeout;
+    maxIdleEntries;
+    idle;
+    constructor(convex, options) {
+        this.queries = new Map();
+        this.subs = new Map();
+        this.convex = convex;
+        this.idle = 0;
+        this.timeout = options.expiration ?? DEFAULT_EXPIRATION_MS;
+        this.maxIdleEntries = options.maxIdleEntries ?? DEFAULT_MAX_ENTRIES;
+        if (options.debug ?? false) {
+            const weakThis = new WeakRef(this);
+            const debugInterval = setInterval(() => {
+                const r = weakThis.deref();
+                if (r === undefined) {
+                    clearInterval(debugInterval);
+                }
+                else {
+                    r.debug();
+                }
+            }, 3000);
+        }
+    }
+    #getQueryEntry(queryKey) {
+        const entry = this.queries.get(queryKey);
+        return entry;
+    }
+    probe(queryKey) {
+        const entry = this.#getQueryEntry(queryKey);
+        return entry === undefined ? undefined : entry.value;
+    }
+    // Enable a new subscription.
+    start(id, queryKey, query, args, setter) {
+        let entry = this.#getQueryEntry(queryKey);
+        this.subs.set(id, {
+            queryKey,
+            setter,
+        });
+        if (entry === undefined) {
+            entry = {
+                refs: new Set(),
+                evictTimer: null,
+            };
+            const w = this.convex.watchQuery(query, args);
+            const unsub = w.onUpdate(() => {
+                const e = entry;
+                try {
+                    e.value = w.localQueryResult();
+                }
+                catch (err) {
+                    e.value = err;
+                }
+                for (const ref of e.refs.values()) {
+                    this.subs.get(ref)?.setter(e.value);
+                }
+            });
+            entry.unsub = unsub;
+            this.queries.set(queryKey, entry);
+        }
+        else if (entry.evictTimer !== null) {
+            this.idle -= 1;
+            clearTimeout(entry.evictTimer);
+            entry.evictTimer = null;
+        }
+        entry.refs.add(id);
+        if (entry.value !== undefined) {
+            setter(entry.value);
+        }
+    }
+    // End a previous subscription.
+    end(id) {
+        const sub = this.subs.get(id);
+        if (sub) {
+            this.subs.delete(id);
+            const cq = this.queries.get(sub.queryKey);
+            const qk = sub.queryKey;
+            cq?.refs.delete(id);
+            // None left?
+            if (cq?.refs.size === 0) {
+                const remove = () => {
+                    cq.unsub();
+                    this.queries.delete(qk);
+                };
+                if (this.idle == this.maxIdleEntries) {
+                    remove();
+                }
+                else {
+                    this.idle += 1;
+                    const evictTimer = window.setTimeout(() => {
+                        this.idle -= 1;
+                        remove();
+                    }, this.timeout);
+                    cq.evictTimer = evictTimer;
+                }
+            }
+        }
+    }
+    debug() {
+        console.log("DEBUG CACHE");
+        console.log(`IDLE = ${this.idle}`);
+        console.log(" SUBS");
+        for (const [k, v] of this.subs.entries()) {
+            console.log(`  ${k} => ${v.queryKey}`);
+        }
+        console.log(" QUERIES");
+        for (const [k, v] of this.queries.entries()) {
+            console.log(`  ${k} => ${v.refs.size} refs, evict = ${v.evictTimer}, value = ${v.value}`);
+        }
+        console.log("~~~~~~~~~~~~~~~~~~~~~~");
+    }
+}

package/dist/react/index.d.ts CHANGED Viewed

@@ -1,9 +1,73 @@
-import { OptionalRestArgsOrSkip } from "convex/react";
+import { OptionalRestArgsOrSkip, useQueries } from "convex/react";
 import { FunctionReference, FunctionReturnType } from "convex/server";
 /**
  * Use in place of `useQuery` from "convex/react" to fetch data from a query
  * function but instead returns `{ status, data, error, isSuccess, isPending, isError}`.
  *
+ * Want a different name? Use `makeUseQueryWithStatus` to create a custom hook:
+ * ```ts
+ * import { useQueries } from "convex/react";
+ * import { makeUseQueryWithStatus } from "convex-helpers/react";
+ * export const useQuery = makeUseQueryWithStatus(useQueries);
+ * ```
+ *
+ * Status is one of "success", "pending", or "error".
+ * Docs copied from {@link useQueryOriginal} until `returns` block:
+ *
+ * Load a reactive query within a React component.
+ *
+ * This React hook contains internal state that will cause a rerender
+ * whenever the query result changes.
+ *
+ * Throws an error if not used under {@link ConvexProvider}.
+ *
+ * @param query - a {@link server.FunctionReference} for the public query to run
+ * like `api.dir1.dir2.filename.func`.
+ * @param args - The arguments to the query function or the string "skip" if the
+ * query should not be loaded.
+ * @returns {status, data, error, isSuccess, isPending, isError} where:
+ * - `status` is one of "success", "pending", or "error"
+ * - `data` is the result of the query function, if it loaded successfully,
+ * - `error` is an `Error` if the query threw an exception.
+ * - `isSuccess` is `true` if the query loaded successfully.
+ * - `isPending` is `true` if the query is still loading or "skip" was passed.
+ * - `isError` is `true` if the query threw an exception.
+ */
+export declare const useQuery: <Query extends FunctionReference<"query">>(query: Query, ...queryArgs: OptionalRestArgsOrSkip<Query>) => {
+    status: "success";
+    data: FunctionReturnType<Query>;
+    error: undefined;
+    isSuccess: true;
+    isPending: false;
+    isError: false;
+} | {
+    status: "pending";
+    data: undefined;
+    error: undefined;
+    isSuccess: false;
+    isPending: true;
+    isError: false;
+} | {
+    status: "error";
+    data: undefined;
+    error: Error;
+    isSuccess: false;
+    isPending: false;
+    isError: true;
+};
+/**
+ * Makes a hook to use in place of `useQuery` from "convex/react" to fetch data from a query
+ * function but instead returns `{ status, data, error, isSuccess, isPending, isError}`.
+ *
+ * You can pass in any hook that matches the signature of {@link useQueries} from "convex/react".
+ * For instance:
+ *
+ * ```ts
+ * import { useQueries } from "convex-helpers/react/cache/hooks";
+ * import { makeUseQueryWithStatus } from "convex-helpers/react";
+ * const useQuery = makeUseQueryWithStatus(useQueries);
+ * ```
+ *
  * Status is one of "success", "pending", or "error".
  * Docs copied from {@link useQueryOriginal} until `returns` block:
  *
@@ -25,8 +89,12 @@ import { FunctionReference, FunctionReturnType } from "convex/server";
  * - `isSuccess` is `true` if the query loaded successfully.
  * - `isPending` is `true` if the query is still loading or "skip" was passed.
  * - `isError` is `true` if the query threw an exception.
+ *
+ * @param useQueries Something matching the signature of {@link useQueries} from "convex/react".
+ * @returns
+ * @returns A useQuery function that returns an object with status, data, error, isSuccess, isPending, isError.
  */
-export declare function useQuery<Query extends FunctionReference<"query">>(query: Query, ...queryArgs: OptionalRestArgsOrSkip<Query>): {
+export declare function makeUseQueryWithStatus(useQueriesHook: typeof useQueries): <Query extends FunctionReference<"query">>(query: Query, ...queryArgs: OptionalRestArgsOrSkip<Query>) => {
     status: "success";
     data: FunctionReturnType<Query>;
     error: undefined;

package/dist/react/index.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../react/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,~~EAGvB~~,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAEnB,MAAM,eAAe,CAAC;AAIvB~~;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG~~;AACH,~~wBAAgB~~,QAAQ,CAAC,KAAK,SAAS,~~iBAAiB~~,CAAC,OAAO,CAAC,~~EAC/D~~,KAAK,EAAE,KAAK,~~EACZ~~,~~GAAG~~,SAAS,EAAE,sBAAsB,CAAC,KAAK,CAAC,~~GAEzC~~;IACE,MAAM,EAAE,SAAS,CAAC;IAClB,IAAI,EAAE,~~kBAAkB~~,~~CAAC,~~KAAK,CAAC,CAAC;IAChC,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,KAAK,CAAC;IACjB,OAAO,EAAE,KAAK,CAAC;CAChB,GACD;IACE,MAAM,EAAE,SAAS,CAAC;IAClB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,KAAK,CAAC;IACjB,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,EAAE,KAAK,CAAC;CAChB,GACD;IACE,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,KAAK,CAAC;IACb,SAAS,EAAE,KAAK,CAAC;IACjB,SAAS,EAAE,KAAK,CAAC;IACjB,OAAO,EAAE,IAAI,CAAC;CACf,~~CAsDJ~~"}
1	+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../react/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,UAAU,EAEX,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAEnB,MAAM,eAAe,CAAC;AAIvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,QAAQ,oDA2CV,KAAK,gBACE,uBAAuB,KAAK,CAAC,KAEzC;IACE,MAAM,EAAE,SAAS,CAAC;IAClB,IAAI,EAAE,mBAAmB,KAAK,CAAC,CAAC;IAChC,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,KAAK,CAAC;IACjB,OAAO,EAAE,KAAK,CAAC;CAChB,GACD;IACE,MAAM,EAAE,SAAS,CAAC;IAClB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,KAAK,CAAC;IACjB,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,EAAE,KAAK,CAAC;CAChB,GACD;IACE,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,KAAK,CAAC;IACb,SAAS,EAAE,KAAK,CAAC;IACjB,SAAS,EAAE,KAAK,CAAC;IACjB,OAAO,EAAE,IAAI,CAAC;CACf,AArEmD,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,sBAAsB,CAAC,cAAc,EAAE,OAAO,UAAU,qDAE7D,KAAK,gBACE,uBAAuB,KAAK,CAAC,KAEzC;IACE,MAAM,EAAE,SAAS,CAAC;IAClB,IAAI,EAAE,mBAAmB,KAAK,CAAC,CAAC;IAChC,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,KAAK,CAAC;IACjB,OAAO,EAAE,KAAK,CAAC;CAChB,GACD;IACE,MAAM,EAAE,SAAS,CAAC;IAClB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,KAAK,CAAC;IACjB,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,EAAE,KAAK,CAAC;CAChB,GACD;IACE,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,KAAK,CAAC;IACb,SAAS,EAAE,KAAK,CAAC;IACjB,SAAS,EAAE,KAAK,CAAC;IACjB,OAAO,EAAE,IAAI,CAAC;CACf,CAuDN"}