startx 1.0.2 → 1.0.3

package/packages/ui/src/api/use-api/query-factory.ts

@@ -0,0 +1,66 @@
+import type { z } from "zod";
+import { QueryKey, type RawSchema, type SchemaQueryKeys, type ZParams, type ZQuery } from "./api-types";
+
+export type QueryKeyFactory<ZQ extends ZQuery, ZP extends ZParams> = {
+	(input?: { params?: z.input<ZP>; query?: z.input<ZQ> }): QueryKey<string>;
+};
+
+function stringifyKeyValue(value: unknown): string {
+	if (value === null) return "::null::";
+	if (value === undefined) return "";
+	return String(value as string);
+}
+export function makeQueryKeyFactory<StaticKeys extends readonly string[], ZQ extends ZQuery, ZP extends ZParams>(
+	staticKey: StaticKeys,
+	zParams?: ZP,
+	zQuery?: ZQ
+): QueryKeyFactory<ZQ, ZP> {
+	return input => {
+		const key: string[] = [...staticKey.filter(Boolean)];
+
+		if (input?.params && zParams) {
+			const shapeKeys = Object.keys(zParams?.shape);
+
+			for (const k of shapeKeys) {
+				const v = input.params[k];
+
+				if (v !== undefined) {
+					key.push(`params:${k}:${stringifyKeyValue(v)}`);
+				}
+			}
+		}
+
+		if (input?.query && zQuery) {
+			const shapeKeys = Object.keys(zQuery?.shape);
+
+			for (const k of shapeKeys) {
+				const v = input.query[k];
+
+				if (v !== undefined) {
+					if (Array.isArray(v)) {
+						for (const item of v) {
+							key.push(`query:${k}:${stringifyKeyValue(item)}`);
+						}
+					} else {
+						key.push(`query:${k}:${stringifyKeyValue(v)}`);
+					}
+				}
+			}
+		}
+
+		return key as QueryKey<string>;
+	};
+}
+
+export function createQueryKeysProxy<Schema extends RawSchema>(schema: Schema): SchemaQueryKeys<Schema> {
+	return new Proxy(schema, {
+		get(target, prop) {
+			if (typeof prop === "symbol" || prop === "then") {
+				return Reflect.get(target, prop);
+			}
+
+			const entry = target[prop as keyof Schema];
+			return entry?.queryKey ?? (() => [String(prop)]);
+		},
+	}) as SchemaQueryKeys<Schema>;
+}

package/packages/ui/src/api/use-api/react-query/types.ts

@@ -0,0 +1,64 @@
+import type { UseQueryResult, UseMutationResult } from "@tanstack/react-query";
+import type { z } from "zod";
+import type { IPaginatedData, TimeString } from "../api-types";
+
+export type ExtractData<E> = "data" extends keyof E ? E["data"] : unknown;
+export type ExtractZQuery<E> = "zQuery" extends keyof E ? E["zQuery"] : never;
+export type ExtractZParams<E> = "zParams" extends keyof E ? E["zParams"] : never;
+export type ExtractZBody<E> = "zBody" extends keyof E ? NonNullable<E["zBody"]> : never;
+
+export type WithAbort<T> = T & { abort: () => void };
+
+type CommonQueryOptions = {
+	staleTime?: number | TimeString;
+	enabled?: boolean;
+};
+
+export type FetchOptions<E> = CommonQueryOptions & {
+	query?: z.output<ExtractZQuery<E>>;
+	params?: z.output<ExtractZParams<E>>;
+};
+
+export type PaginatedFetchOptions<E> = CommonQueryOptions & {
+	query?: z.output<ExtractZQuery<E>>;
+	params?: z.output<ExtractZParams<E>>;
+	page?: number;
+	limit?: number;
+};
+
+export type MutationVariables<E> = {
+	body?: z.output<ExtractZBody<E>>;
+	query?: z.output<ExtractZQuery<E>>;
+	params?: z.output<ExtractZParams<E>>;
+};
+
+export type MutationOptions<E> = {
+	query?: z.output<ExtractZQuery<E>>;
+	params?: z.output<ExtractZParams<E>>;
+	body?: z.output<ExtractZBody<E>>;
+	isFormData?: boolean;
+	onSuccess?: (data: ExtractData<E>, variables: MutationVariables<E>) => void;
+	onError?: (error: Error, variables: MutationVariables<E>) => void;
+	onMutate?: (variables: MutationVariables<E>) => void;
+	overwriteEvents?: boolean;
+};
+
+export type UseApiOptions<Schema, K extends keyof Schema> = Schema[K] extends infer E
+	? E extends { apiType: "fetch" }
+		? FetchOptions<E>
+		: E extends { apiType: "paginated-fetch" }
+			? PaginatedFetchOptions<E>
+			: E extends { apiType: "mutation" }
+				? MutationOptions<E>
+				: never
+	: never;
+
+export type UseApiReturn<Schema, K extends keyof Schema> = Schema[K] extends { apiType: "fetch" }
+	? WithAbort<UseQueryResult<ExtractData<Schema[K]>>>
+	: Schema[K] extends { apiType: "paginated-fetch" }
+		? WithAbort<
+				UseQueryResult<IPaginatedData<ExtractData<Schema[K]>, Schema[K] extends { other: infer O } ? O : unknown>>
+			>
+		: Schema[K] extends { apiType: "mutation" }
+			? WithAbort<UseMutationResult<ExtractData<Schema[K]>, Error, MutationVariables<Schema[K]>>>
+			: never;

package/packages/ui/src/api/use-api/react-query/use-api-client.ts

@@ -0,0 +1,56 @@
+import { useQueryClient, type Updater } from "@tanstack/react-query";
+import { useMemo } from "react";
+import type { z } from "zod";
+import type { RawSchema, IPaginatedData, QueryKey } from "../api-types";
+import { createQueryKeysProxy } from "../query-factory";
+import type { ExtractZQuery, ExtractZParams, ExtractData } from "./types";
+
+export type SafeZodInput<T> = T extends z.ZodTypeAny ? z.input<T> : never;
+
+export type InputArgs<E> = {
+	query?: SafeZodInput<ExtractZQuery<E>>;
+	params?: SafeZodInput<ExtractZParams<E>>;
+};
+
+export type ResolvedData<E> = E extends { apiType: "paginated-fetch" }
+	? IPaginatedData<ExtractData<E>, E extends { other: infer O } ? O : unknown>
+	: ExtractData<E>;
+
+export function useApiClient<Schema extends RawSchema>(schema: Schema) {
+	const queryClient = useQueryClient();
+	const proxy = useMemo(() => createQueryKeysProxy(schema), [schema]);
+
+	const getQueryKey = <K extends keyof Schema & string>(key: K, input?: InputArgs<Schema[K]>): QueryKey<string> => {
+		const factory = proxy[key] as unknown as (input?: InputArgs<Schema[K]>) => QueryKey<string>;
+		return factory(input);
+	};
+
+	return {
+		invalidate: <K extends keyof Schema & string>(key: K, input?: InputArgs<Schema[K]>) =>
+			queryClient.invalidateQueries({ queryKey: getQueryKey(key, input) }),
+
+		refetch: <K extends keyof Schema & string>(key: K, input?: InputArgs<Schema[K]>) =>
+			queryClient.refetchQueries({ queryKey: getQueryKey(key, input) }),
+
+		getData: <K extends keyof Schema & string>(key: K, input?: InputArgs<Schema[K]>) =>
+			queryClient.getQueryData<ResolvedData<Schema[K]>>(getQueryKey(key, input)),
+
+		setData: <K extends keyof Schema & string>(
+			key: K,
+			dataOrUpdater: Updater<ResolvedData<Schema[K]> | undefined, ResolvedData<Schema[K]> | undefined>,
+			input?: InputArgs<Schema[K]>
+		) => queryClient.setQueryData<ResolvedData<Schema[K]>>(getQueryKey(key, input), dataOrUpdater),
+
+		remove: <K extends keyof Schema & string>(key: K, input?: InputArgs<Schema[K]>) =>
+			queryClient.removeQueries({ queryKey: getQueryKey(key, input) }),
+
+		reset: <K extends keyof Schema & string>(key: K, input?: InputArgs<Schema[K]>) =>
+			queryClient.resetQueries({ queryKey: getQueryKey(key, input) }),
+
+		cancel: <K extends keyof Schema & string>(key?: K, input?: InputArgs<Schema[K]>) =>
+			key ? queryClient.cancelQueries({ queryKey: getQueryKey(key, input) }) : queryClient.cancelQueries(),
+
+		getQueryKey,
+		queryKeys: proxy,
+	};
+}

package/packages/ui/src/api/use-api/react-query/use-api.ts

@@ -0,0 +1,297 @@
+import {
+	useQuery,
+	useMutation,
+	useQueryClient,
+	type UseQueryOptions,
+	type UseQueryResult,
+	type UseMutationResult,
+} from "@tanstack/react-query";
+import { type AxiosError, type AxiosInstance, type AxiosRequestConfig } from "axios";
+import { useMemo, useRef } from "react";
+import { z } from "zod";
+import { FormUtils } from "@repo/ui/lib/utils";
+import { ApiHelper } from "../api-helpers";
+import type {
+	IFetchOptions,
+	IPaginatedFetchOptions,
+	IFetchMutationOptions,
+	IPaginatedData,
+	QueryEvent,
+	CbAction,
+	RawSchema,
+	QueryKey,
+	ZQuery,
+	ZParams,
+} from "../api-types";
+import { createQueryKeysProxy } from "../query-factory";
+
+import type {
+	UseApiOptions,
+	UseApiReturn,
+	MutationVariables,
+	ExtractData,
+	FetchOptions,
+	PaginatedFetchOptions,
+	MutationOptions,
+} from "./types";
+
+async function processEvents<
+	Schema extends RawSchema,
+	IK extends string,
+	IQ extends z.output<ZQuery>,
+	IP extends z.output<ZParams>,
+	IB,
+	ID,
+>(
+	events: QueryEvent<IK, IQ, IP, IB, ID, Schema> | undefined,
+	data: ID,
+	variables: { query?: IQ; params?: IP; body?: IB } | undefined,
+	schemaProxy: ReturnType<typeof createQueryKeysProxy<Schema>>,
+	queryClient: ReturnType<typeof useQueryClient>,
+	override?: boolean
+) {
+	if (!events) return;
+	const payload = { data, ...variables };
+	const runAction = async (
+		action: CbAction<Schema, IP, IQ, IB, ID, IK, Array<QueryKey<IK>>> | undefined,
+		exec: (key: QueryKey<IK>) => Promise<void>
+	) => {
+		if (!action) return;
+		const keys: Array<QueryKey<IK>> = typeof action === "function" ? action(payload, schemaProxy) : action;
+		for (const key of keys) {
+			await exec(key);
+		}
+	};
+
+	await runAction(events.invalidateQuery, key => queryClient.invalidateQueries({ queryKey: key }));
+	await runAction(events.refetchQuery, key => queryClient.refetchQueries({ queryKey: key }));
+	await runAction(events.clearQuery, key => queryClient.resetQueries({ queryKey: key }));
+
+	if (!override) {
+		if (typeof events.fn === "function") await events.fn?.(payload, schemaProxy);
+	}
+}
+
+function useFetchApi<ID, ZQ extends ZQuery, ZP extends ZParams>(
+	key: keyof RawSchema,
+	endpoint: IFetchOptions<ID, ZQ, ZP>,
+	axiosClient: AxiosInstance,
+	options: {
+		query?: z.output<ZQ>;
+		params?: z.output<ZP>;
+		staleTime?: number;
+		enabled?: boolean;
+	}
+): UseQueryResult<ID> & { abort: () => void } {
+	const queryClient = useQueryClient();
+	const queryKey = useMemo(
+		() =>
+			ApiHelper.getQueryKey(key, endpoint.key, {
+				params: options.params,
+				query: options.query,
+			}),
+		[options.query, options.params]
+	);
+	const staleTime = ApiHelper.parseTime(ApiHelper.merge(options.staleTime, endpoint.staleTime));
+
+	const query = useQuery<ID>({
+		queryKey,
+		queryFn: async ({ signal }) => {
+			const config: AxiosRequestConfig = {
+				method: endpoint.method || "GET",
+				url: ApiHelper.buildUrl({
+					route: endpoint.route,
+					params: options.params,
+					searchParams: options.query,
+				}),
+				params: options.query,
+				signal,
+			};
+			const resp = await axiosClient.request<ID>(config);
+
+			return resp.data;
+		},
+		staleTime,
+		enabled: options.enabled ?? endpoint.enable?.isEnable ?? true,
+		retry: endpoint.retry?.count,
+		retryDelay: endpoint.retry?.interval,
+		refetchInterval: endpoint.refetch?.interval?.ms,
+		refetchIntervalInBackground: endpoint.refetch?.interval?.inBackground,
+		refetchOnMount: endpoint.refetch?.onMount ? "always" : false,
+		refetchOnWindowFocus: endpoint.refetch?.onFocus ? "always" : false,
+	} as UseQueryOptions<ID>);
+
+	return {
+		...query,
+		abort: () => queryClient.cancelQueries({ queryKey }),
+	};
+}
+
+function usePaginatedFetchApi<ID, IO, ZQ extends ZQuery, ZP extends ZParams>(
+	key: keyof RawSchema,
+	endpoint: IPaginatedFetchOptions<ID, IO, ZQ, ZP>,
+	axiosClient: AxiosInstance,
+	options: {
+		query?: z.output<ZQ>;
+		params?: z.output<ZP>;
+		page?: number;
+		limit?: number;
+		staleTime?: number;
+		enabled?: boolean;
+	}
+): UseQueryResult<{ data: IPaginatedData<ID, IO> }> & { abort: () => void } {
+	const queryClient = useQueryClient();
+	const mergedQuery = useMemo(
+		() =>
+			ApiHelper.merge(options.query, {
+				page: options.page,
+				limit: options.limit,
+			}),
+		[options.query, options.page, options.limit]
+	);
+
+	const queryKey = useMemo(
+		() =>
+			ApiHelper.getQueryKey(key, endpoint.key, {
+				params: options.params,
+				query: mergedQuery,
+			}),
+		[key, endpoint.key, options.params, mergedQuery]
+	);
+
+	const staleTime = ApiHelper.parseTime(ApiHelper.merge(options.staleTime, endpoint.staleTime));
+
+	const query = useQuery<{ data: IPaginatedData<ID, IO> }>({
+		queryKey,
+		queryFn: async ({ signal }) => {
+			const config: AxiosRequestConfig = {
+				method: endpoint.method || "GET",
+				url: ApiHelper.buildUrl({
+					route: endpoint.route,
+					params: options.params,
+					searchParams: mergedQuery,
+				}),
+				signal,
+			};
+
+			const resp = await axiosClient.request<{
+				data: IPaginatedData<ID, IO>;
+			}>(config);
+
+			return resp.data;
+		},
+		staleTime,
+		enabled: options.enabled ?? endpoint.enable?.isEnable ?? true,
+		retry: endpoint.retry?.count,
+		retryDelay: endpoint.retry?.interval,
+		refetchInterval: endpoint.refetch?.interval?.ms,
+		refetchIntervalInBackground: endpoint.refetch?.interval?.inBackground,
+		refetchOnMount: endpoint.refetch?.onMount ? "always" : false,
+		refetchOnWindowFocus: endpoint.refetch?.onFocus ? "always" : false,
+	} as UseQueryOptions<{ data: IPaginatedData<ID, IO> }>);
+
+	return {
+		...query,
+		abort: () => queryClient.cancelQueries({ queryKey }),
+	};
+}
+function useMutationApi<Schema extends RawSchema, K extends keyof Schema & string>(
+	endpoint: IFetchMutationOptions<K>,
+	axiosClient: AxiosInstance,
+	proxy: ReturnType<typeof createQueryKeysProxy<Schema>>,
+	options?: MutationOptions<Schema[K]>
+): UseMutationResult<ExtractData<Schema[K]>, Error, MutationVariables<Schema[K]>> & { abort: () => void } {
+	const queryClient = useQueryClient();
+	const abortControllerRef = useRef<AbortController | null>(null);
+	const isFormData = ApiHelper.merge(options?.isFormData, endpoint.isFormData);
+
+	const mutation = useMutation<ExtractData<Schema[K]>, Error, MutationVariables<Schema[K]>>({
+		mutationFn: async (variables: MutationVariables<Schema[K]>) => {
+			abortControllerRef.current = new AbortController();
+
+			if (endpoint.zBody && endpoint.validateBody !== false && options?.overwriteEvents !== true) {
+				const valid = ApiHelper.validateSchema(endpoint.zBody, variables.body);
+				if (!valid.success) {
+					throw new Error(valid.errors.join(", "));
+				}
+			}
+
+			const body = ApiHelper.merge(variables.body, options?.body)!;
+			const config: AxiosRequestConfig = {
+				method: endpoint.method || "POST",
+				url: ApiHelper.buildUrl(
+					ApiHelper.merge(
+						{ route: endpoint.route, params: variables.params, searchParams: variables.query },
+						{ route: endpoint.route, params: options?.params, searchParams: options?.query }
+					)
+				),
+				params: ApiHelper.merge(variables.query, options?.query),
+				data: isFormData ? FormUtils.getFormData(body!) : body,
+				...(isFormData && { headers: { "Content-Type": "multipart/form-data" } }),
+				signal: abortControllerRef.current.signal,
+			};
+
+			const response = await axiosClient.request<ExtractData<Schema[K]>>(config);
+
+			await processEvents(endpoint.onFetch, response.data, variables, proxy, queryClient, options?.overwriteEvents);
+
+			return response.data;
+		},
+		onSuccess: async (data, variables) => {
+			options?.onSuccess?.(data, variables);
+			await processEvents(endpoint.onSuccess, data, variables, proxy, queryClient, options?.overwriteEvents);
+		},
+		onError: async (error: Error, variables) => {
+			options?.onError?.(error, variables);
+			await processEvents(
+				endpoint.onError,
+				error as AxiosError<any>,
+				variables,
+				proxy,
+				queryClient,
+				options?.overwriteEvents
+			);
+		},
+		onMutate: options?.onMutate,
+	});
+
+	return {
+		...mutation,
+		abort: () => abortControllerRef.current?.abort(),
+	};
+}
+export function useApi<Schema extends RawSchema>(schema: Schema, axiosClient: AxiosInstance) {
+	return <K extends keyof Schema & string>(key: K, options?: UseApiOptions<Schema, K>): UseApiReturn<Schema, K> => {
+		const endpoint = schema[key];
+		const proxy = useMemo(() => createQueryKeysProxy(schema), [schema]);
+
+		if (endpoint.apiType === "fetch") {
+			const ep = endpoint as IFetchOptions<unknown, ZQuery, ZParams>;
+			const opts = options as FetchOptions<Schema[K]> | undefined;
+			return useFetchApi(key, ep, axiosClient, {
+				query: opts?.query,
+				params: opts?.params,
+				staleTime: ApiHelper.parseTime(ApiHelper.merge(opts?.staleTime, ep.staleTime)),
+				enabled: opts?.enabled,
+			}) as UseApiReturn<Schema, K>;
+		}
+
+		if (endpoint.apiType === "paginated-fetch") {
+			const ep = endpoint as IPaginatedFetchOptions<unknown, unknown, ZQuery, ZParams>;
+			const opts = options as PaginatedFetchOptions<Schema[K]> | undefined;
+			return usePaginatedFetchApi(key, ep, axiosClient, {
+				query: opts?.query,
+				params: opts?.params,
+				staleTime: ApiHelper.parseTime(ApiHelper.merge(opts?.staleTime, ep.staleTime)),
+				enabled: opts?.enabled,
+			}) as UseApiReturn<Schema, K>;
+		}
+
+		if (endpoint.apiType === "mutation") {
+			const ep = endpoint as IFetchMutationOptions<K>;
+			const opts = options as MutationOptions<Schema[K]> | undefined;
+			return useMutationApi(ep, axiosClient, proxy, opts) as UseApiReturn<Schema, K>;
+		}
+		throw new Error(`Unknown API type: ${endpoint.apiType}`);
+	};
+}