@mpen/routekit 0.1.0 → 0.1.1

package/dist/bin.d.mts

@@ -0,0 +1,4 @@
+//#region src/bin/gen-api-client.d.ts
+declare function main(): Promise<void>;
+//#endregion
+export { main };

package/dist/client/react.d.mts

@@ -0,0 +1,178 @@
+//#region src/client/react/index.d.ts
+/**
+ * A generated API client endpoint method that can be called by [`useQuery`]{@link useQuery}.
+ *
+ * @example
+ * ```ts
+ * const method: QueryMethod<[id: number], ApiResponse<{ id: number }>> = apiClient.users.get
+ * ```
+ *
+ * @typeParam TArgs - The endpoint argument tuple.
+ * @typeParam TResponse - The resolved endpoint response type.
+ */
+type QueryMethod<TArgs extends unknown[] = any[], TResponse = unknown> = (...args: TArgs) => Promise<TResponse>;
+/**
+ * Resolves the response type returned by a [`QueryMethod`]{@link QueryMethod}.
+ *
+ * @example
+ * ```ts
+ * type Response = QueryResponse<typeof apiClient.users.get>
+ * ```
+ *
+ * @typeParam TMethod - The endpoint method type.
+ */
+type QueryResponse<TMethod extends QueryMethod> = Awaited<ReturnType<TMethod>>;
+/**
+ * Infers the default data value exposed by [`useQuery`]{@link useQuery}.
+ *
+ * @example
+ * ```ts
+ * type Data = QueryData<ApiResponse<{ ok: true }>>
+ * ```
+ *
+ * @typeParam TResponse - The endpoint response type.
+ */
+type QueryData<TResponse> = TResponse extends {
+  body: infer TBody;
+} ? TBody : TResponse;
+/**
+ * Current lifecycle status for a [`useQuery`]{@link useQuery} request.
+ *
+ * @example
+ * ```ts
+ * if (query.status === 'success') {
+ *     query.data
+ * }
+ * ```
+ */
+type UseQueryStatus = 'idle' | 'loading' | 'success' | 'error';
+/**
+ * Options for [`useQuery`]{@link useQuery}.
+ *
+ * @example
+ * ```tsx
+ * const query = useQuery(
+ *     { enabled: userId !== undefined, keepPreviousData: true },
+ *     apiClient.users.get,
+ *     userId,
+ * )
+ * ```
+ *
+ * @typeParam TResponse - The endpoint response type.
+ * @typeParam TData - The selected data type exposed on the result.
+ */
+interface UseQueryOptions<TResponse, TData = QueryData<TResponse>> {
+  /**
+   * Whether the hook should automatically run the endpoint.
+   */
+  enabled?: boolean;
+  /**
+   * Keeps the previous response and data visible while the next request is loading.
+   * @defaultValue true
+   */
+  keepPreviousData?: boolean;
+  /**
+   * Optional query key used instead of the endpoint arguments when deciding whether to refetch.
+   */
+  key?: unknown;
+  /**
+   * Selects the result data from the endpoint response.
+   */
+  select?: (response: TResponse) => TData;
+}
+/**
+ * Result returned by [`useQuery`]{@link useQuery}.
+ *
+ * @example
+ * ```tsx
+ * const query = useQuery(apiClient.health.get)
+ *
+ * if (query.isLoading) return 'Loading'
+ * if (query.isError) return String(query.error)
+ *
+ * return query.data.ok
+ * ```
+ *
+ * @typeParam TResponse - The endpoint response type.
+ * @typeParam TData - The selected data type exposed on the result.
+ */
+interface UseQueryResult<TResponse, TData = QueryData<TResponse>> {
+  /**
+   * The current request lifecycle status.
+   */
+  status: UseQueryStatus;
+  /**
+   * The latest selected data. By default this is `response.body`.
+   */
+  data: TData | undefined;
+  /**
+   * The latest full endpoint response.
+   */
+  response: TResponse | undefined;
+  /**
+   * The latest request error.
+   */
+  error: unknown;
+  /**
+   * Whether the query has not run yet.
+   */
+  isIdle: boolean;
+  /**
+   * Whether the query is loading without any successful response.
+   */
+  isLoading: boolean;
+  /**
+   * Whether a request is currently in flight.
+   */
+  isFetching: boolean;
+  /**
+   * Whether the query has a successful response.
+   */
+  isSuccess: boolean;
+  /**
+   * Whether the latest request failed.
+   */
+  isError: boolean;
+  /**
+   * Runs the endpoint again with the latest method arguments.
+   *
+   * @returns A promise for the endpoint response.
+   */
+  refetch(): Promise<TResponse>;
+}
+/**
+ * Runs a generated API endpoint method and refetches when its arguments change.
+ *
+ * @example
+ * ```tsx
+ * const query = useQuery(apiClient.usersById.get, 123, { includePosts: true })
+ * ```
+ *
+ * @param method - Generated API client endpoint method to run.
+ * @param args - Arguments passed to the endpoint method.
+ * @returns Query state, the latest response body, the full response, and a manual refetch function.
+ * @typeParam TMethod - The endpoint method type.
+ */
+declare function useQuery<TMethod extends QueryMethod>(method: TMethod, ...args: Parameters<TMethod>): UseQueryResult<QueryResponse<TMethod>, QueryData<QueryResponse<TMethod>>>;
+/**
+ * Runs a generated API endpoint method with query options and refetches when its arguments change.
+ *
+ * @example
+ * ```tsx
+ * const query = useQuery(
+ *     { keepPreviousData: true, select: (response) => response.body.items },
+ *     apiClient.search.get,
+ *     { q: 'routekit' },
+ * )
+ * ```
+ *
+ * @param options - Query behavior options.
+ * @param method - Generated API client endpoint method to run.
+ * @param args - Arguments passed to the endpoint method.
+ * @returns Query state, the selected data, the full response, and a manual refetch function.
+ * @typeParam TMethod - The endpoint method type.
+ * @typeParam TData - The selected data type.
+ */
+declare function useQuery<TMethod extends QueryMethod, TData = QueryData<QueryResponse<TMethod>>>(options: UseQueryOptions<QueryResponse<TMethod>, TData>, method: TMethod, ...args: Parameters<TMethod>): UseQueryResult<QueryResponse<TMethod>, TData>;
+//#endregion
+export { QueryData, QueryMethod, QueryResponse, UseQueryOptions, UseQueryResult, UseQueryStatus, useQuery };

package/dist/client/react.mjs

@@ -0,0 +1,142 @@
+import { useCallback, useDebugValue, useEffect, useRef, useState } from "react";
+//#region src/client/react/index.ts
+const isPlainObject = (value) => Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null;
+const hasBody = (value) => typeof value === "object" && value !== null && "body" in value;
+function defaultSelect(response) {
+	return hasBody(response) ? response.body : response;
+}
+function createInitialState(enabled) {
+	return {
+		status: enabled ? "loading" : "idle",
+		data: void 0,
+		response: void 0,
+		error: void 0,
+		isFetching: enabled
+	};
+}
+function startQuery(state, keepPreviousData) {
+	return {
+		status: keepPreviousData && state.response !== void 0 ? state.status : "loading",
+		data: keepPreviousData ? state.data : void 0,
+		response: keepPreviousData ? state.response : void 0,
+		error: void 0,
+		isFetching: true
+	};
+}
+function stopQuery(state) {
+	return {
+		...state,
+		status: state.response === void 0 ? "idle" : state.status,
+		isFetching: false
+	};
+}
+function toQueryResult(state, refetch) {
+	return {
+		...state,
+		isIdle: state.status === "idle",
+		isLoading: state.status === "loading",
+		isSuccess: state.status === "success",
+		isError: state.status === "error",
+		refetch
+	};
+}
+function hashQueryKey(value) {
+	return stableStringify(value, /* @__PURE__ */ new WeakMap(), { value: 0 });
+}
+function stableStringify(value, seen, nextSeenIndex) {
+	if (value === null) return "null";
+	switch (typeof value) {
+		case "bigint": return `bigint:${value}`;
+		case "boolean":
+		case "number":
+		case "string": return JSON.stringify(value);
+		case "symbol": return `symbol:${String(value.description)}`;
+		case "undefined": return "undefined";
+		case "function": return `function:${String(value)}`;
+	}
+	const seenIndex = seen.get(value);
+	if (seenIndex !== void 0) return `[Circular:${seenIndex}]`;
+	seen.set(value, nextSeenIndex.value);
+	nextSeenIndex.value += 1;
+	if (Array.isArray(value)) return `[${value.map((item) => stableStringify(item, seen, nextSeenIndex)).join(",")}]`;
+	if (value instanceof Date) return `Date:${value.toISOString()}`;
+	if (typeof URLSearchParams !== "undefined" && value instanceof URLSearchParams) return `URLSearchParams:${stableStringify(Array.from(value.entries()), seen, nextSeenIndex)}`;
+	if (typeof Headers !== "undefined" && value instanceof Headers) return `Headers:${stableStringify(Array.from(value.entries()).sort(), seen, nextSeenIndex)}`;
+	if (value instanceof Map) return `Map:${stableStringify(Array.from(value.entries()).sort(), seen, nextSeenIndex)}`;
+	if (value instanceof Set) return `Set:${stableStringify(Array.from(value.values()).sort(), seen, nextSeenIndex)}`;
+	if (!isPlainObject(value)) return Object.prototype.toString.call(value);
+	return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(value[key], seen, nextSeenIndex)}`).join(",")}}`;
+}
+function useQuery(...input) {
+	const hasOptions = typeof input[0] !== "function";
+	const options = hasOptions ? input[0] : void 0;
+	const method = hasOptions ? input[1] : input[0];
+	const args = input.slice(hasOptions ? 2 : 1);
+	const enabled = options?.enabled ?? true;
+	const queryKey = hashQueryKey(options?.key ?? args);
+	const select = options?.select ?? defaultSelect;
+	const argsRef = useRef(args);
+	const keepPreviousDataRef = useRef(options?.keepPreviousData ?? true);
+	const mountedRef = useRef(false);
+	const requestIdRef = useRef(0);
+	const selectRef = useRef(select);
+	const [state, setState] = useState(() => createInitialState(enabled));
+	useEffect(() => {
+		argsRef.current = args;
+		keepPreviousDataRef.current = options?.keepPreviousData ?? true;
+		selectRef.current = select;
+	});
+	useEffect(() => {
+		mountedRef.current = true;
+		return () => {
+			mountedRef.current = false;
+			requestIdRef.current += 1;
+		};
+	}, []);
+	const refetch = useCallback(async () => {
+		const requestId = requestIdRef.current + 1;
+		requestIdRef.current = requestId;
+		setState((currentState) => startQuery(currentState, keepPreviousDataRef.current));
+		try {
+			const response = await method(...argsRef.current);
+			const data = selectRef.current(response);
+			if (mountedRef.current && requestId === requestIdRef.current) setState({
+				status: "success",
+				data,
+				response,
+				error: void 0,
+				isFetching: false
+			});
+			return response;
+		} catch (error) {
+			if (mountedRef.current && requestId === requestIdRef.current) setState((currentState) => ({
+				status: "error",
+				data: keepPreviousDataRef.current ? currentState.data : void 0,
+				response: keepPreviousDataRef.current ? currentState.response : void 0,
+				error,
+				isFetching: false
+			}));
+			throw error;
+		}
+	}, [method]);
+	useEffect(() => {
+		if (!enabled) {
+			requestIdRef.current += 1;
+			setState(stopQuery);
+			return;
+		}
+		refetch().catch(() => void 0);
+		return () => {
+			requestIdRef.current += 1;
+		};
+	}, [
+		enabled,
+		queryKey,
+		refetch
+	]);
+	const result = toQueryResult(state, refetch);
+	useDebugValue(result.status);
+	return result;
+}
+//#endregion
+export { useQuery };