@bb-labs/convex-cache 0.0.1

package/dist/convex-cache/adapters/next/fns/preload-query.d.ts

@@ -0,0 +1,12 @@
+import { PQ_CachedResult, PQ_Query } from "../../../core/types/types/paginated-query";
+import { Q_Query, Q_Result } from "../../../core/types/types/query";
+import { PQ_ArgsPreloaded, PQ_OptionsPreloaded, Q_ArgsPreloaded, Q_OptionsPreloaded } from "../types/preloaded";
+import { T_SchemaMap } from "../../../types/schema-map";
+export type PreloadQueryReturn<Q extends Q_Query | PQ_Query> = Q extends PQ_Query ? PQ_CachedResult<Q> | undefined : Q_Result<Q> | undefined;
+export type T_PreloadQueryParams<Q extends Q_Query | PQ_Query> = {
+    query: Q;
+    args: Q_ArgsPreloaded<Q> | PQ_ArgsPreloaded<Q>;
+    options?: Q_OptionsPreloaded<Q> | PQ_OptionsPreloaded<Q>;
+    schemaMap: T_SchemaMap;
+};
+export declare function preloadQuery<Q extends Q_Query | PQ_Query>(params: T_PreloadQueryParams<Q>): Promise<PreloadQueryReturn<Q>>;

package/dist/convex-cache/adapters/next/fns/preload-query.js

@@ -0,0 +1,27 @@
+import { _preloadPaginatedQuery, _preloadQuery } from "../server-fns/preload-query";
+import { getFunctionName } from "convex/server";
+import { fetchSchemaFromMap } from "../../../core/helpers/utils/fetch-schema-from-map";
+export async function preloadQuery(params) {
+    const { query, args, options, schemaMap } = params;
+    const queryName = getFunctionName(query);
+    if (args && "paginationOpts" in args) {
+        // Paginated branch
+        const result = (await _preloadPaginatedQuery({
+            queryName,
+            args: args,
+            options,
+        }));
+        const schema = fetchSchemaFromMap({ queryName, schemaMap, type: "paginated" });
+        const validated = schema.safeParse(result);
+        return (validated.success ? result : undefined);
+    }
+    // Non-paginated branch
+    const result = (await _preloadQuery({
+        queryName,
+        args,
+        options,
+    }));
+    const schema = fetchSchemaFromMap({ queryName, schemaMap, type: "query" });
+    const validated = schema.safeParse(result);
+    return (validated.success ? result : undefined);
+}

package/dist/convex-cache/adapters/next/hooks/hooks.d.ts

@@ -0,0 +1,8 @@
+import { Q_Query, PQ_Query } from "../../../core/types";
+import { T_UseCachedPaginatedQueryServer } from "../../../core/server-cache/queries/paginated-query";
+import { T_UseCachedQueryServer } from "../../../core/server-cache/queries/query";
+type T_UseCachedQueryServerParams<Q extends Q_Query> = Omit<T_UseCachedQueryServer<Q>, "revalidateCache">;
+export declare const useCachedQueryServer: <Q extends Q_Query>({ query, args, preloadedData }: T_UseCachedQueryServerParams<Q>) => import("../../../core/types").Q_Result<Q> | undefined;
+type T_UseCachedPaginatedQueryServerParams<Q extends PQ_Query> = Omit<T_UseCachedPaginatedQueryServer<Q>, "revalidateCache">;
+export declare const useCachedPaginatedQueryServer: <Q extends PQ_Query>({ query, args, options, preloadedData }: T_UseCachedPaginatedQueryServerParams<Q>) => import("../../../core/types").PQ_Result<Q>;
+export {};

package/dist/convex-cache/adapters/next/hooks/hooks.js

@@ -0,0 +1,9 @@
+import { _useCachedPaginatedQueryServer } from "../../../core/server-cache/queries/paginated-query";
+import { _useCachedQueryServer } from "../../../core/server-cache/queries/query";
+import { revalidatePaginatedQueryCache, revalidateQueryCache } from "../lib/revalidate-query-cache";
+export const useCachedQueryServer = ({ query, args, preloadedData }) => {
+    return _useCachedQueryServer({ query, args, preloadedData, revalidateCache: revalidateQueryCache });
+};
+export const useCachedPaginatedQueryServer = ({ query, args, options, preloadedData }) => {
+    return _useCachedPaginatedQueryServer({ query, args, options, preloadedData, revalidateCache: revalidatePaginatedQueryCache });
+};

package/dist/convex-cache/adapters/next/index.d.ts

@@ -0,0 +1 @@
+export * from "./hooks/hooks";

package/dist/convex-cache/adapters/next/index.js

@@ -0,0 +1 @@
+export * from "./hooks/hooks";

package/dist/convex-cache/adapters/next/lib/revalidate-query-cache.d.ts

@@ -0,0 +1,13 @@
+import { Q_Query } from "../../../core/types/types/query";
+import { PQ_Query } from "../../../core/types/types/paginated-query";
+import { PQ_ArgsPreloaded, Q_ArgsPreloaded } from "../types/preloaded";
+export declare const revalidateQueryCache: <Q extends Q_Query>({ query, args }: {
+    query: Q;
+    args: Q_ArgsPreloaded<Q>;
+}) => Promise<void>;
+type T_RevalidatePaginatedQueryCacheParams<Q extends PQ_Query> = {
+    query: Q;
+    args: PQ_ArgsPreloaded<Q>;
+};
+export declare const revalidatePaginatedQueryCache: <Q extends PQ_Query>({ query, args }: T_RevalidatePaginatedQueryCacheParams<Q>) => Promise<void>;
+export {};

package/dist/convex-cache/adapters/next/lib/revalidate-query-cache.js

@@ -0,0 +1,21 @@
+import { makeQueryKey } from "../../../core/helpers/utils/query-key";
+import { getFunctionName } from "convex/server";
+import { revalidateCache } from "../server-fns/revalidate-cache";
+export const revalidateQueryCache = async ({ query, args }) => {
+    const queryName = getFunctionName(query);
+    const { tag } = makeQueryKey({
+        queryName,
+        args,
+        kind: "query",
+    });
+    await revalidateCache({ tag });
+};
+export const revalidatePaginatedQueryCache = async ({ query, args }) => {
+    const queryName = getFunctionName(query);
+    const { tag } = makeQueryKey({
+        queryName,
+        args,
+        kind: "paginated",
+    });
+    await revalidateCache({ tag });
+};

package/dist/convex-cache/adapters/next/server-fns/preload-query.d.ts

@@ -0,0 +1,16 @@
+import { Q_Query, Q_Result } from "../../../core/types/types/query";
+import { PQ_CachedResult, PQ_Query } from "../../../core/types/types/paginated-query";
+import type { PQ_ArgsPreloaded, PQ_OptionsPreloaded, Q_ArgsPreloaded, Q_OptionsPreloaded } from "../types/preloaded";
+type T_PreloadQueryParams<Q extends Q_Query> = {
+    queryName: string;
+    args: Q_ArgsPreloaded<Q>;
+    options?: Q_OptionsPreloaded<Q>;
+};
+export declare const _preloadQuery: ({ queryName, args, options }: T_PreloadQueryParams<Q_Query>) => Promise<Q_Result<Q_Query>>;
+type T_PreloadPaginatedQueryParams<Q extends PQ_Query> = {
+    queryName: string;
+    args: PQ_ArgsPreloaded<Q>;
+    options?: PQ_OptionsPreloaded<Q>;
+};
+export declare const _preloadPaginatedQuery: ({ queryName, args, options }: T_PreloadPaginatedQueryParams<PQ_Query>) => Promise<PQ_CachedResult<PQ_Query>>;
+export {};

package/dist/convex-cache/adapters/next/server-fns/preload-query.js

@@ -0,0 +1,32 @@
+import { makeFunctionReference } from "convex/server";
+import { fetchQuery } from "convex/nextjs";
+import { cacheLife, cacheTag } from "next/cache";
+import { makeQueryKey } from "../../../core/helpers/utils/query-key";
+import { defaultCacheProfile } from "../utils/cache-profile";
+export const _preloadQuery = async ({ queryName, args, options }) => {
+    "use cache";
+    const { tag } = makeQueryKey({ queryName, args, kind: "query" });
+    cacheTag(tag);
+    cacheLife(defaultCacheProfile);
+    const fnRef = makeFunctionReference(queryName);
+    const argsTuple = [args, options];
+    const result = await fetchQuery(fnRef, ...argsTuple);
+    return result;
+};
+export const _preloadPaginatedQuery = async ({ queryName, args, options }) => {
+    "use cache";
+    const { tag } = makeQueryKey({ queryName, args, kind: "paginated" });
+    cacheTag(tag);
+    cacheLife(defaultCacheProfile);
+    const fnRef = makeFunctionReference(queryName);
+    const argsTuple = [args, options];
+    const result = await fetchQuery(fnRef, ...argsTuple);
+    return convertPaginatedResultForClient({ result });
+};
+const convertPaginatedResultForClient = ({ result }) => {
+    return {
+        results: result.page,
+        status: "Exhausted",
+        isLoading: false,
+    };
+};

package/dist/convex-cache/adapters/next/server-fns/revalidate-cache.d.ts

@@ -0,0 +1,3 @@
+export declare const revalidateCache: ({ tag }: {
+    tag: string;
+}) => Promise<void>;

package/dist/convex-cache/adapters/next/server-fns/revalidate-cache.js

@@ -0,0 +1,6 @@
+"use server";
+import { revalidateTag } from "next/cache";
+import { defaultCacheProfile } from "../utils/cache-profile";
+export const revalidateCache = async ({ tag }) => {
+    revalidateTag(tag, defaultCacheProfile);
+};

package/dist/convex-cache/adapters/next/server.d.ts

@@ -0,0 +1,2 @@
+export * from "./fns/preload-query";
+export * from "./fns/build-preloader";

package/dist/convex-cache/adapters/next/server.js

@@ -0,0 +1,2 @@
+export * from "./fns/preload-query";
+export * from "./fns/build-preloader";

package/dist/convex-cache/adapters/next/types/preloaded.d.ts

@@ -0,0 +1,8 @@
+import { ArgsAndOptions } from "convex/server";
+import { PQ_Query } from "../../../core/types/types/paginated-query";
+import { Q_Query } from "../../../core/types/types/query";
+import { NextjsOptions } from "convex/nextjs";
+export type Q_ArgsPreloaded<Q extends Q_Query> = ArgsAndOptions<Q, NextjsOptions>[0];
+export type PQ_ArgsPreloaded<Q extends PQ_Query> = ArgsAndOptions<Q, NextjsOptions>[0];
+export type Q_OptionsPreloaded<Q extends Q_Query> = ArgsAndOptions<Q, NextjsOptions>[1];
+export type PQ_OptionsPreloaded<Q extends PQ_Query> = ArgsAndOptions<Q, NextjsOptions>[1];

package/dist/convex-cache/adapters/next/types/preloaded.js

@@ -0,0 +1 @@
+export {};

package/dist/convex-cache/adapters/next/utils/cache-profile.d.ts

@@ -0,0 +1 @@
+export declare const defaultCacheProfile = "default";

package/dist/convex-cache/adapters/next/utils/cache-profile.js

@@ -0,0 +1 @@
+export const defaultCacheProfile = "default";

package/dist/convex-cache/adapters/react/hooks/hooks.d.ts

@@ -0,0 +1,8 @@
+import { T_UseCachedPaginatedQueryClient } from "../../../core/client-cache/queries/paginated-query";
+import { Q_Query, PQ_Query } from "../../../core/types";
+import { T_UseCachedQueryClient } from "../../../core/client-cache/queries/query";
+type T_UseQuery<Q extends Q_Query> = Omit<T_UseCachedQueryClient<Q>, "schemaMap" | "useLocalDb">;
+type T_UsePaginatedQuery<Q extends PQ_Query> = Omit<T_UseCachedPaginatedQueryClient<Q>, "schemaMap" | "useLocalDb">;
+export declare const useCachedQueryClient: <Q extends Q_Query>({ query, args }: T_UseQuery<Q>) => import("../../../core/types").Q_Result<Q> | undefined;
+export declare const useCachedPaginatedQueryClient: <Q extends PQ_Query>({ query, args, options }: T_UsePaginatedQuery<Q>) => import("../../../core/types").PQ_Result<Q>;
+export {};

package/dist/convex-cache/adapters/react/hooks/hooks.js

@@ -0,0 +1,12 @@
+import { _useCachedPaginatedQueryClient } from "../../../core/client-cache/queries/paginated-query";
+import { _useCachedQueryClient } from "../../../core/client-cache/queries/query";
+import { useConvexProvider } from "../provider/provider";
+import { useLocalDb as useLocalDbDefault } from "@bb-labs/local-db";
+export const useCachedQueryClient = ({ query, args }) => {
+    const { schemaMap, useLocalDb } = useConvexProvider();
+    return _useCachedQueryClient({ query, args, schemaMap, useLocalDb: useLocalDb ?? useLocalDbDefault });
+};
+export const useCachedPaginatedQueryClient = ({ query, args, options }) => {
+    const { schemaMap, useLocalDb } = useConvexProvider();
+    return _useCachedPaginatedQueryClient({ query, args, options, schemaMap, useLocalDb: (useLocalDb ?? useLocalDbDefault) });
+};

package/dist/convex-cache/adapters/react/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./hooks/hooks";
+export * from "./provider/provider";

package/dist/convex-cache/adapters/react/index.js

@@ -0,0 +1,2 @@
+export * from "./hooks/hooks";
+export * from "./provider/provider";

package/dist/convex-cache/adapters/react/provider/provider.d.ts

@@ -0,0 +1,13 @@
+import type { T_SchemaMap } from "../../../types/schema-map";
+import { useLocalDb as useLocalDbDefault } from "@bb-labs/local-db";
+type T_ConvexCacheProvider = {
+    children: React.ReactNode;
+    schemaMap: T_SchemaMap;
+    useLocalDb?: typeof useLocalDbDefault<unknown>;
+};
+export declare const ConvexCacheProvider: ({ children, schemaMap, useLocalDb }: T_ConvexCacheProvider) => import("react/jsx-runtime").JSX.Element;
+export declare const useConvexProvider: () => {
+    schemaMap: T_SchemaMap;
+    useLocalDb: typeof useLocalDbDefault<unknown> | undefined;
+};
+export {};

package/dist/convex-cache/adapters/react/provider/provider.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+const convexCacheContext = createContext({
+    schemaMap: undefined,
+    useLocalDb: undefined,
+});
+export const ConvexCacheProvider = ({ children, schemaMap, useLocalDb }) => {
+    return _jsx(convexCacheContext.Provider, { value: { schemaMap, useLocalDb }, children: children });
+};
+export const useConvexProvider = () => {
+    const context = useContext(convexCacheContext);
+    if (!context || !context.schemaMap) {
+        throw new Error("Application must be wrapped in a <ConvexCacheProvider />");
+    }
+    return { schemaMap: context.schemaMap, useLocalDb: context.useLocalDb };
+};

package/dist/convex-cache/core/client-cache/helpers/hooks/use-client-cache.d.ts

@@ -0,0 +1,10 @@
+import { useLocalDb as useLocalDbDefault } from "@bb-labs/local-db";
+import { z } from "zod";
+type T_UseClientCache<T> = {
+    storageKey: string;
+    raw: T | undefined;
+    schema: z.ZodSchema<T>;
+    useLocalDb: typeof useLocalDbDefault<T>;
+};
+export declare const useClientCache: <T>({ storageKey, raw, schema, useLocalDb }: T_UseClientCache<T>) => T | null | undefined;
+export {};

package/dist/convex-cache/core/client-cache/helpers/hooks/use-client-cache.js

@@ -0,0 +1,16 @@
+import { useEffect } from "react";
+import deepEqual from "fast-deep-equal";
+export const useClientCache = ({ storageKey, raw, schema, useLocalDb }) => {
+    const { value: stored, setValue: setStored } = useLocalDb({
+        key: storageKey,
+        schema,
+        initialValue: undefined,
+        dbName: "convex-cache",
+        storeName: "local-store",
+    });
+    useEffect(() => {
+        if (raw !== undefined && !deepEqual(raw, stored))
+            setStored(raw);
+    }, [raw, stored, setStored]);
+    return stored;
+};

package/dist/convex-cache/core/client-cache/helpers/hooks/use-query-key.d.ts

@@ -0,0 +1,7 @@
+type T_UseQueryKey = {
+    queryName: string;
+    args: unknown;
+    kind: "query" | "paginated";
+};
+export declare const useQueryKey: ({ queryName, args, kind }: T_UseQueryKey) => string;
+export {};

package/dist/convex-cache/core/client-cache/helpers/hooks/use-query-key.js

@@ -0,0 +1,5 @@
+import { useMemo } from "react";
+import { makeQueryKey } from "../../../helpers/utils/query-key";
+export const useQueryKey = ({ queryName, args, kind }) => {
+    return useMemo(() => makeQueryKey({ queryName, args, kind }).key, [queryName, args, kind]);
+};

package/dist/convex-cache/core/client-cache/queries/paginated-query.d.ts

@@ -0,0 +1,13 @@
+import { PQ_Query, PQ_Args, PQ_Result, PQ_CachedResult } from "../../types/types/paginated-query";
+import type { T_SchemaMap } from "../../../types/schema-map";
+import { useLocalDb as useLocalDbDefault } from "@bb-labs/local-db";
+export type T_UseCachedPaginatedQueryClient<Q extends PQ_Query> = {
+    query: Q;
+    args: PQ_Args<Q>;
+    options: {
+        initialNumItems: number;
+    };
+    schemaMap: T_SchemaMap;
+    useLocalDb: typeof useLocalDbDefault<PQ_CachedResult<Q>>;
+};
+export declare const _useCachedPaginatedQueryClient: <Q extends PQ_Query>({ query, args, options, schemaMap, useLocalDb }: T_UseCachedPaginatedQueryClient<Q>) => PQ_Result<Q>;

package/dist/convex-cache/core/client-cache/queries/paginated-query.js

@@ -0,0 +1,37 @@
+import { usePaginatedQuery } from "convex/react";
+import { useQueryKey } from "../helpers/hooks/use-query-key";
+import { useClientCache } from "../helpers/hooks/use-client-cache";
+import { getFunctionName } from "convex/server";
+import { useMemo } from "react";
+import { fetchSchemaFromMap } from "../../helpers/utils/fetch-schema-from-map";
+export const _useCachedPaginatedQueryClient = ({ query, args, options, schemaMap, useLocalDb }) => {
+    const queryName = useMemo(() => getFunctionName(query), [query]);
+    const schema = useMemo(() => fetchSchemaFromMap({
+        queryName,
+        schemaMap,
+        type: "paginated",
+    }), [queryName, schemaMap]);
+    const raw = usePaginatedQuery(query, args, options);
+    const storageKey = useQueryKey({ queryName, args, kind: "paginated" });
+    const cacheInput = raw.status === "LoadingFirstPage"
+        ? undefined
+        : {
+            results: raw.results,
+            status: raw.status,
+            isLoading: raw.isLoading,
+        };
+    const cached = useClientCache({
+        storageKey,
+        raw: cacheInput,
+        schema,
+        useLocalDb,
+    });
+    if (!cached)
+        return raw;
+    return {
+        ...raw,
+        results: cached.results,
+        status: cached.status,
+        isLoading: cached.isLoading,
+    };
+};

package/dist/convex-cache/core/client-cache/queries/query.d.ts

@@ -0,0 +1,10 @@
+import { Q_Query, Q_Args, Q_Result } from "../../types/types/query";
+import type { T_SchemaMap } from "../../../types/schema-map";
+import { useLocalDb as useLocalDbDefault } from "@bb-labs/local-db";
+export type T_UseCachedQueryClient<Q extends Q_Query> = {
+    query: Q;
+    args: Q_Args<Q>;
+    schemaMap: T_SchemaMap;
+    useLocalDb: typeof useLocalDbDefault<Q_Result<Q>>;
+};
+export declare const _useCachedQueryClient: <Q extends Q_Query>({ query, args, schemaMap, useLocalDb }: T_UseCachedQueryClient<Q>) => Q_Result<Q> | undefined;

package/dist/convex-cache/core/client-cache/queries/query.js

@@ -0,0 +1,23 @@
+import { useQuery } from "convex/react";
+import { getFunctionName } from "convex/server";
+import { useQueryKey } from "../helpers/hooks/use-query-key";
+import { useClientCache } from "../helpers/hooks/use-client-cache";
+import { useMemo } from "react";
+import { fetchSchemaFromMap } from "../../helpers/utils/fetch-schema-from-map";
+export const _useCachedQueryClient = ({ query, args, schemaMap, useLocalDb }) => {
+    const queryName = useMemo(() => getFunctionName(query), [query]);
+    const schema = useMemo(() => fetchSchemaFromMap({
+        queryName,
+        schemaMap,
+        type: "query",
+    }), [queryName, schemaMap]);
+    const raw = useQuery(query, args);
+    const storageKey = useQueryKey({ queryName, args, kind: "query" });
+    const cached = useClientCache({
+        storageKey,
+        raw,
+        schema,
+        useLocalDb,
+    });
+    return (cached ?? raw);
+};

package/dist/convex-cache/core/helpers/utils/convert-paginated-schema.d.ts

@@ -0,0 +1,13 @@
+import { z, type ZodType } from "zod";
+import type { PaginationResult } from "convex/server";
+import type { UsePaginatedQueryResult } from "convex/react";
+type T_ServerSchema<T> = PaginationResult<T>;
+type CacheableUsePaginated<T> = Pick<UsePaginatedQueryResult<T>, "results" | "status" | "isLoading">;
+/**
+ * Convert a Zod schema for `PaginationResult<T>` (server) into a Zod schema
+ * for the cacheable subset of `UsePaginatedQueryResult<T>` (client).
+ *
+ * `Item` is inferred as: z.output<ServerSchema>["page"][number]
+ */
+export declare const convertPaginatedSchemaForClient: <ServerSchema extends ZodType<T_ServerSchema<unknown>>, Item = z.output<ServerSchema>["page"][number]>(schema: ServerSchema) => ZodType<CacheableUsePaginated<Item>>;
+export {};

package/dist/convex-cache/core/helpers/utils/convert-paginated-schema.js

@@ -0,0 +1,45 @@
+import { z, ZodArray, ZodObject } from "zod";
+/**
+ * Convert a Zod schema for `PaginationResult<T>` (server) into a Zod schema
+ * for the cacheable subset of `UsePaginatedQueryResult<T>` (client).
+ *
+ * `Item` is inferred as: z.output<ServerSchema>["page"][number]
+ */
+export const convertPaginatedSchemaForClient = (schema) => {
+    let itemSchema;
+    // Try to extract the item schema from the server schema's `page` field.
+    if (schema instanceof ZodObject) {
+        const objShape = schema.shape;
+        if (objShape && objShape.page instanceof ZodArray) {
+            itemSchema = objShape.page.element;
+        }
+        else {
+            throw new Error("[convertPaginatedSchemaForClient] Schema object has no `page` array;");
+        }
+    }
+    else {
+        throw new Error("[convertPaginatedSchemaForClient] Schema is not a ZodObject;");
+    }
+    // Base part shared by all cacheable paginated variants (no loadMore)
+    const base = z.object({
+        results: z.array(itemSchema),
+    });
+    const loadingFirstPage = base.extend({
+        status: z.literal("LoadingFirstPage"),
+        isLoading: z.literal(true),
+    });
+    const canLoadMore = base.extend({
+        status: z.literal("CanLoadMore"),
+        isLoading: z.literal(false),
+    });
+    const loadingMore = base.extend({
+        status: z.literal("LoadingMore"),
+        isLoading: z.literal(true),
+    });
+    const exhausted = base.extend({
+        status: z.literal("Exhausted"),
+        isLoading: z.literal(false),
+    });
+    const clientSchema = z.union([loadingFirstPage, canLoadMore, loadingMore, exhausted]);
+    return clientSchema;
+};

package/dist/convex-cache/core/helpers/utils/fetch-schema-from-map.d.ts

@@ -0,0 +1,21 @@
+import type { ZodType } from "zod";
+import type { PaginationResult } from "convex/server";
+import type { UsePaginatedQueryResult } from "convex/react";
+import type { T_SchemaMap } from "../../../types/schema-map";
+import type { ValidatorJSON } from "convex/values";
+type OutputOf<Map, Key extends keyof Map> = Map[Key] extends {
+    returns: ValidatorJSON;
+} ? ValidatorJSON : unknown;
+type PaginatedItem<Map, Key extends keyof Map> = OutputOf<Map, Key> extends PaginationResult<infer Item> ? Item : never;
+type CacheableUsePaginated<T> = Pick<UsePaginatedQueryResult<T>, "results" | "status" | "isLoading">;
+export declare function fetchSchemaFromMap<Map extends T_SchemaMap, Key extends keyof Map>(params: {
+    queryName: Key;
+    schemaMap: Map;
+    type: "query";
+}): ZodType<OutputOf<Map, Key>>;
+export declare function fetchSchemaFromMap<Map extends T_SchemaMap, Key extends keyof Map>(params: {
+    queryName: Key;
+    schemaMap: Map;
+    type: "paginated";
+}): ZodType<CacheableUsePaginated<PaginatedItem<Map, Key>>>;
+export {};

package/dist/convex-cache/core/helpers/utils/fetch-schema-from-map.js

@@ -0,0 +1,16 @@
+import { convertPaginatedSchemaForClient } from "./convert-paginated-schema";
+import { validatorFromJSON } from "../../../../validation";
+import { convexToZod } from "convex-helpers/server/zod4";
+export function fetchSchemaFromMap({ queryName, schemaMap, type }) {
+    const entry = schemaMap[queryName];
+    if (!entry || !entry.returns) {
+        throw new Error(`Schema not found for function ${String(queryName)}`);
+    }
+    const validator = validatorFromJSON(entry.returns);
+    const zodSchema = convexToZod(validator);
+    if (type === "query") {
+        return zodSchema;
+    }
+    const paginatedSchema = convertPaginatedSchemaForClient(zodSchema);
+    return paginatedSchema;
+}

package/dist/convex-cache/core/helpers/utils/query-key.d.ts

@@ -0,0 +1,10 @@
+type T_MakeQueryKey = {
+    queryName: string;
+    args: unknown;
+    kind: "query" | "paginated";
+};
+export declare const makeQueryKey: ({ queryName, args, kind }: T_MakeQueryKey) => {
+    key: string;
+    tag: string;
+};
+export {};

package/dist/convex-cache/core/helpers/utils/query-key.js

@@ -0,0 +1,16 @@
+import superjson from "superjson";
+import { deepSort } from "@bb-labs/deep-sort";
+import crypto from "crypto";
+export const makeQueryKey = ({ queryName, args, kind }) => {
+    const ns = kind === "paginated" ? "pq" : "q";
+    const sortedArgs = deepSort(args);
+    const argKey = superjson.stringify(sortedArgs);
+    const queryKey = `${ns}:${queryName}:${argKey}`;
+    return {
+        key: queryKey,
+        tag: hashKey(queryKey),
+    };
+};
+const hashKey = (key) => {
+    return crypto.createHash("sha256").update(key).digest("hex").slice(0, 16);
+};

package/dist/convex-cache/core/server-cache/queries/paginated-query.d.ts

@@ -0,0 +1,15 @@
+import { PQ_Query, PQ_Args, PQ_Result, PQ_CachedResult } from "../../types/types/paginated-query";
+import { PQ_ArgsPreloaded } from "../../../adapters/next/types/preloaded";
+export type T_UseCachedPaginatedQueryServer<Q extends PQ_Query> = {
+    query: Q;
+    args: PQ_Args<Q>;
+    options: {
+        initialNumItems: number;
+    };
+    preloadedData: PQ_CachedResult<Q> | undefined;
+    revalidateCache: ({ query, args }: {
+        query: Q;
+        args: PQ_ArgsPreloaded<Q>;
+    }) => void;
+};
+export declare const _useCachedPaginatedQueryServer: <Q extends PQ_Query>({ query, args, options, preloadedData, revalidateCache }: T_UseCachedPaginatedQueryServer<Q>) => PQ_Result<Q>;

package/dist/convex-cache/core/server-cache/queries/paginated-query.js

@@ -0,0 +1,16 @@
+import { usePaginatedQuery } from "convex/react";
+import { useEffect } from "react";
+import { isDeepEqual } from "@bb-labs/deep-equal";
+export const _useCachedPaginatedQueryServer = ({ query, args, options, preloadedData, revalidateCache }) => {
+    const raw = usePaginatedQuery(query, args, options);
+    useEffect(() => {
+        if (args === "skip")
+            return;
+        if (raw.isLoading)
+            return;
+        if (isDeepEqual(preloadedData, raw))
+            return;
+        revalidateCache({ query, args: { ...args, paginationOpts: { numItems: options.initialNumItems, cursor: null } } });
+    }, [raw]);
+    return raw.status == "LoadingFirstPage" ? { ...(preloadedData ?? { results: [], status: "LoadingFirstPage", isLoading: false }), loadMore: () => { } } : raw;
+};

package/dist/convex-cache/core/server-cache/queries/query.d.ts

@@ -0,0 +1,12 @@
+import { Q_Query, Q_Args, Q_Result } from "../../types/types/query";
+import { Q_ArgsPreloaded } from "../../../adapters/next/types/preloaded";
+export type T_UseCachedQueryServer<Q extends Q_Query> = {
+    query: Q;
+    args: Q_Args<Q>;
+    preloadedData: Q_Result<Q> | undefined;
+    revalidateCache: ({ query, args }: {
+        query: Q;
+        args: Q_ArgsPreloaded<Q>;
+    }) => void;
+};
+export declare const _useCachedQueryServer: <Q extends Q_Query>({ query, args, preloadedData, revalidateCache }: T_UseCachedQueryServer<Q>) => Q_Result<Q> | undefined;

package/dist/convex-cache/core/server-cache/queries/query.js

@@ -0,0 +1,16 @@
+import { useQuery } from "convex/react";
+import { useEffect } from "react";
+import { isDeepEqual } from "@bb-labs/deep-equal";
+export const _useCachedQueryServer = ({ query, args, preloadedData, revalidateCache }) => {
+    const raw = useQuery(query, args);
+    useEffect(() => {
+        if (args === "skip")
+            return;
+        if (!raw)
+            return;
+        if (isDeepEqual(preloadedData, raw))
+            return;
+        revalidateCache({ query, args });
+    }, [raw]);
+    return raw ?? preloadedData;
+};

package/dist/convex-cache/core/types/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./types/query";
+export * from "./types/paginated-query";

package/dist/convex-cache/core/types/index.js

@@ -0,0 +1,2 @@
+export * from "./types/query";
+export * from "./types/paginated-query";

package/dist/convex-cache/core/types/types/paginated-query.d.ts

@@ -0,0 +1,8 @@
+import { ConvexHttpClient } from "convex/browser";
+import { PaginatedQueryReference, PaginatedQueryArgs, UsePaginatedQueryResult, PaginatedQueryItem } from "convex/react";
+export type PQ_Query = PaginatedQueryReference;
+export type PQ_Args<Q extends PQ_Query> = PaginatedQueryArgs<Q> | "skip";
+export type PQ_Result<Q extends PQ_Query> = UsePaginatedQueryResult<PaginatedQueryItem<Q>>;
+export type PQ_Item<Q extends PQ_Query> = PaginatedQueryItem<Q>;
+export type PQ_CachedResult<Q extends PQ_Query> = Pick<UsePaginatedQueryResult<PQ_Item<Q>>, "results" | "status" | "isLoading">;
+export declare const client: ConvexHttpClient;

package/dist/convex-cache/core/types/types/paginated-query.js

@@ -0,0 +1,2 @@
+import { ConvexHttpClient } from "convex/browser";
+export const client = new ConvexHttpClient(process.env["NEXT_PUBLIC_CONVEX_URL"] ?? "");

package/dist/convex-cache/core/types/types/query.d.ts

@@ -0,0 +1,5 @@
+import { OptionalRestArgsOrSkip } from "convex/react";
+import { FunctionReference, FunctionReturnType } from "convex/server";
+export type Q_Query = FunctionReference<"query">;
+export type Q_Args<Q extends Q_Query> = OptionalRestArgsOrSkip<Q>[0];
+export type Q_Result<Q extends Q_Query> = FunctionReturnType<Q>;

package/dist/convex-cache/core/types/types/query.js

@@ -0,0 +1 @@
+export {};