convex-helpers/dist/react/sessions.d.ts

A collection of useful code to complement the official convex package.

/**
 * React helpers for adding session data to Convex functions.
 *
 * !Important!: To use these functions, you must wrap your code with
 * ```tsx
 *  <ConvexProvider client={convex}>
 *    <SessionProvider>
 *      <App />
 *    </SessionProvider>
 *  </ConvexProvider>
 * ```
 *
 * With the `SessionProvider` inside the `ConvexProvider` but outside your app.
 *
 * See the associated [Stack post](https://stack.convex.dev/track-sessions-without-cookies)
 * for more information.
 */
import React from "react";
import type { FunctionArgs, FunctionReference, FunctionReturnType } from "convex/server";
import type { SessionId } from "../server/sessions";
import { EmptyObject, BetterOmit } from "..";
export type UseStorage<T> = (key: string, initialValue: T) => readonly [T, (value: T) => void];
export type RefreshSessionFn = (beforeUpdate?: (newSessionId: SessionId) => any | Promise<any>) => Promise<SessionId>;
type SessionFunction<T extends "query" | "mutation" | "action", Args extends any = any> = FunctionReference<T, "public", {
    sessionId: SessionId;
} & Args, any>;
type SessionQueryArgsArray<Fn extends SessionFunction<"query">> = keyof FunctionArgs<Fn> extends "sessionId" ? [args?: EmptyObject | "skip"] : [args: BetterOmit<FunctionArgs<Fn>, "sessionId"> | "skip"];
type SessionArgsArray<Fn extends SessionFunction<"mutation" | "action">> = keyof FunctionArgs<Fn> extends "sessionId" ? [args?: EmptyObject] : [args: BetterOmit<FunctionArgs<Fn>, "sessionId">];
/**
 * Context for a Convex session, creating a server session and providing the id.
 *
 * @param useStorage - Where you want your session ID to be persisted. Roughly:
 *  - sessionStorage is saved per-tab
 *  - localStorage is shared between tabs, but not browser profiles.
 * @param storageKey - Key under which to store the session ID in the store
 * @param idGenerator - Function to return a new, unique session ID string. Defaults to crypto.randomUUID
 * @returns A provider to wrap your React nodes which provides the session ID.
 * To be used with useSessionQuery and useSessionMutation.
 */
export declare const SessionProvider: React.FC<{
    useStorage?: UseStorage<SessionId>;
    storageKey?: string;
    idGenerator?: () => string;
    children?: React.ReactNode;
}>;
export declare function useSessionQuery<Query extends SessionFunction<"query">>(query: Query, ...args: SessionQueryArgsArray<Query>): FunctionReturnType<Query> | undefined;
export declare function useSessionMutation<Mutation extends SessionFunction<"mutation">>(name: Mutation): (...args: SessionArgsArray<Mutation>) => Promise<FunctionReturnType<Mutation>>;
export declare function useSessionAction<Action extends SessionFunction<"action">>(name: Action): (...args: SessionArgsArray<Action>) => Promise<FunctionReturnType<Action>>;
export declare function useSessionId(): readonly [SessionId, RefreshSessionFn];
export declare function useSessionStorage(key: string, initialValue: SessionId): readonly [SessionId, (value: SessionId) => void];
export {};