πΈ Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.
import { Filter } from "@rybbit/shared";
import {
InfiniteData,
useInfiniteQuery,
UseInfiniteQueryResult,
useQuery,
UseQueryOptions,
UseQueryResult,
} from "@tanstack/react-query";
import { Time } from "../../components/DateSelector/types";
import { useStore, useTimezone } from "../../lib/store";
import {
AnalyticsContext,
AnalyticsDescriptor,
AnalyticsRequest,
buildAnalyticsRequest,
fetchAnalytics,
} from "./analyticsRequest";
type PeriodTime = "current" | "previous";
export interface AnalyticsContextOptions {
// Override the store's current site (e.g. multi-site overview cards).
site?: number | string;
periodTime?: PeriodTime;
// Query a specific time range instead of the store's; ignored when
// periodTime is "previous" (the store's comparison period wins).
overrideTime?: Time;
// Previous period in past-minutes mode means [2x .. 1x] minutes ago.
doublePastMinutesForPrevious?: boolean;
// Endpoints that are not scoped to the selected period (trait keys, saved
// funnels) send no window and do not refetch when the date selector moves.
useTime?: boolean;
useFilters?: boolean;
// Appended to the store filters.
additionalFilters?: Filter[];
// Replace the store filters entirely (when non-empty).
customFilters?: Filter[];
}
/**
* Resolves the analytics request context (site, time period, filters) from the
* store once and derives the request from it β path plus the exact params that
* go on the wire. The queryKey is built from that same request, so it is in
* sync with what is sent by construction: a hook can no longer forget to list
* an input and silently serve stale data.
*
* The store is read through selectors so a `selectedStat` or `bucket` change
* does not re-render every analytics hook on the page.
*/
export function useAnalyticsContext(options: AnalyticsContextOptions = {}): {
site: number | string;
context: AnalyticsContext;
/** False when the request has no window to ask for β comparison turned off. */
hasPeriod: boolean;
} {
const storeSite = useStore(state => state.site);
const time = useStore(state => state.time);
const previousTime = useStore(state => state.previousTime);
const filters = useStore(state => state.filters);
const timeZone = useTimezone();
const site = options.site ?? storeSite;
const baseTime = options.overrideTime ?? time;
// A comparison of "none" leaves previousTime null: there is no window to ask
// about, so the query is disabled rather than falling through to all-time.
let timeToUse = options.periodTime === "previous" ? previousTime : baseTime;
if (options.doublePastMinutesForPrevious && options.periodTime === "previous" && timeToUse?.mode === "past-minutes") {
timeToUse = {
...timeToUse,
pastMinutesStart: timeToUse.pastMinutesStart * 2,
pastMinutesEnd: timeToUse.pastMinutesStart,
};
}
const useFilters = options.useFilters ?? true;
const combinedFilters = !useFilters
? undefined
: options.customFilters?.length
? options.customFilters
: options.additionalFilters?.length
? [...filters, ...options.additionalFilters]
: filters;
return {
site,
hasPeriod: timeToUse !== null,
context: {
time: (options.useTime ?? true) && timeToUse ? timeToUse : null,
timeZone,
filters: combinedFilters,
},
};
}
function useAnalyticsRequest(options: AnalyticsContextOptions & AnalyticsDescriptor) {
const { site, context, hasPeriod } = useAnalyticsContext(options);
const request = buildAnalyticsRequest(options, context);
const scope = request.organizationId === undefined ? site : `organization:${request.organizationId}`;
const hasScope = request.organizationId === undefined ? !!site : !!request.organizationId;
return { site, scope, hasScope, hasPeriod, request };
}
export interface AnalyticsQueryOptions<TData> extends AnalyticsContextOptions, AnalyticsDescriptor {
// First element(s) of the queryKey. Keep the historical name β mutations
// invalidate by this prefix (e.g. ["users"], ["user-info", userId]).
key: string | readonly unknown[];
staleTime?: number;
refetchInterval?: number;
enabled?: boolean;
// Same-site placeholder policy: keep showing the previous result while a
// changed key (time/filter tweak) refetches. Site changes still hard-reset.
placeholder?: boolean;
props?: Partial<UseQueryOptions<TData, Error>>;
}
const buildQueryKey = (
key: string | readonly unknown[],
scope: number | string | undefined,
request: AnalyticsRequest
) => [...(Array.isArray(key) ? key : [key]), scope, request.path, request.params, request.body];
export function useAnalyticsQuery<TData>(options: AnalyticsQueryOptions<TData>): UseQueryResult<TData> {
const { site, scope, hasScope, request, hasPeriod } = useAnalyticsRequest(options);
return useQuery<TData, Error>({
queryKey: buildQueryKey(options.key, scope, request),
queryFn: () => fetchAnalytics<TData>(site!, request),
staleTime: options.staleTime ?? 60_000,
refetchInterval: options.refetchInterval,
placeholderData:
(options.placeholder ?? true)
? (previousData, previousQuery) =>
scope !== undefined && previousQuery?.queryKey?.includes(scope) ? previousData : undefined
: undefined,
enabled: (options.enabled ?? true) && hasScope && hasPeriod,
...options.props,
});
}
export interface AnalyticsInfiniteQueryOptions<TPage, TCursor> extends AnalyticsContextOptions, AnalyticsDescriptor {
key: string | readonly unknown[];
initialPageParam: TCursor;
// Params that position the request at `cursor` (a page number, an offset, a
// timestamp) β merged into the descriptor params for that page.
pageParams: (cursor: TCursor) => Record<string, unknown>;
getNextPageParam: (lastPage: TPage, allPages: TPage[]) => TCursor | undefined;
staleTime?: number;
refetchInterval?: number;
enabled?: boolean;
refetchOnWindowFocus?: boolean;
// Hand the query's abort signal to the request. Cancelling the query (or unmounting its last
// observer) then aborts the request and stops a refetch before it walks the remaining pages.
abortable?: boolean;
}
export function useAnalyticsInfiniteQuery<TPage, TCursor = number>(
options: AnalyticsInfiniteQueryOptions<TPage, TCursor>
): UseInfiniteQueryResult<InfiniteData<TPage>> {
const { site, scope, hasScope, request, hasPeriod } = useAnalyticsRequest(options);
return useInfiniteQuery<TPage, Error, InfiniteData<TPage>, readonly unknown[], TCursor>({
queryKey: [...buildQueryKey(options.key, scope, request), "infinite"],
// `signal` is read only when abortable: reading it is what opts a query into cancellation.
queryFn: context =>
fetchAnalytics<TPage>(
site!,
{ ...request, params: { ...request.params, ...options.pageParams(context.pageParam as TCursor) } },
options.abortable ? context.signal : undefined
),
initialPageParam: options.initialPageParam,
getNextPageParam: options.getNextPageParam,
staleTime: options.staleTime ?? 60_000,
refetchInterval: options.refetchInterval,
refetchOnWindowFocus: options.refetchOnWindowFocus,
enabled: (options.enabled ?? true) && hasScope && hasPeriod,
});
}
/** Page-numbered pagination over an endpoint that reports a `totalCount`. */
export const nextPageByTotalCount = <TPage extends { data: unknown[]; totalCount: number }>(
lastPage: TPage,
allPages: TPage[]
): number | undefined => {
const fetched = allPages.reduce((total, page) => total + page.data.length, 0);
return fetched >= lastPage.totalCount ? undefined : allPages.length + 1;
};