@mpen/routekit 0.1.0 → 0.1.1

package/src/client/react/index.ts

@@ -1,431 +0,0 @@
-import { useCallback, useDebugValue, useEffect, useRef, useState } from 'react'
-
-/**
- * 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.
- */
-export 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.
- */
-export 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.
- */
-export 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
- * }
- * ```
- */
-export 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.
- */
-export 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.
- */
-export 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>
-}
-
-interface UseQueryState<TResponse, TData> {
-    status: UseQueryStatus
-    data: TData | undefined
-    response: TResponse | undefined
-    error: unknown
-    isFetching: boolean
-}
-
-type UseQueryInput<TMethod extends QueryMethod, TData> =
-    | [method: TMethod, ...args: Parameters<TMethod>]
-    | [
-          options: UseQueryOptions<QueryResponse<TMethod>, TData>,
-          method: TMethod,
-          ...args: Parameters<TMethod>,
-      ]
-
-const isPlainObject = (value: object): value is Record<string, unknown> =>
-    Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null
-
-const hasBody = (value: unknown): value is { body: unknown } =>
-    typeof value === 'object' && value !== null && 'body' in value
-
-function defaultSelect<TResponse>(response: TResponse): QueryData<TResponse> {
-    return (hasBody(response) ? response.body : response) as QueryData<TResponse>
-}
-
-function createInitialState<TResponse, TData>(enabled: boolean): UseQueryState<TResponse, TData> {
-    return {
-        status: enabled ? 'loading' : 'idle',
-        data: undefined,
-        response: undefined,
-        error: undefined,
-        isFetching: enabled,
-    }
-}
-
-function startQuery<TResponse, TData>(
-    state: UseQueryState<TResponse, TData>,
-    keepPreviousData: boolean,
-): UseQueryState<TResponse, TData> {
-    return {
-        status: keepPreviousData && state.response !== undefined ? state.status : 'loading',
-        data: keepPreviousData ? state.data : undefined,
-        response: keepPreviousData ? state.response : undefined,
-        error: undefined,
-        isFetching: true,
-    }
-}
-
-function stopQuery<TResponse, TData>(
-    state: UseQueryState<TResponse, TData>,
-): UseQueryState<TResponse, TData> {
-    return {
-        ...state,
-        status: state.response === undefined ? 'idle' : state.status,
-        isFetching: false,
-    }
-}
-
-function toQueryResult<TResponse, TData>(
-    state: UseQueryState<TResponse, TData>,
-    refetch: () => Promise<TResponse>,
-): UseQueryResult<TResponse, TData> {
-    return {
-        ...state,
-        isIdle: state.status === 'idle',
-        isLoading: state.status === 'loading',
-        isSuccess: state.status === 'success',
-        isError: state.status === 'error',
-        refetch,
-    }
-}
-
-function hashQueryKey(value: unknown): string {
-    return stableStringify(value, new WeakMap(), { value: 0 })
-}
-
-function stableStringify(
-    value: unknown,
-    seen: WeakMap<object, number>,
-    nextSeenIndex: { value: number },
-): string {
-    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 !== undefined) {
-        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(',')}}`
-}
-
-/**
- * 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.
- */
-export 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.
- */
-export function useQuery<TMethod extends QueryMethod, TData = QueryData<QueryResponse<TMethod>>>(
-    options: UseQueryOptions<QueryResponse<TMethod>, TData>,
-    method: TMethod,
-    ...args: Parameters<TMethod>
-): UseQueryResult<QueryResponse<TMethod>, TData>
-
-export function useQuery<TMethod extends QueryMethod, TData = QueryData<QueryResponse<TMethod>>>(
-    ...input: UseQueryInput<TMethod, TData>
-): UseQueryResult<QueryResponse<TMethod>, TData> {
-    const hasOptions = typeof input[0] !== 'function'
-    const options = (hasOptions ? input[0] : undefined) as
-        | UseQueryOptions<QueryResponse<TMethod>, TData>
-        | undefined
-    const method = (hasOptions ? input[1] : input[0]) as TMethod
-    const args = input.slice(hasOptions ? 2 : 1) as Parameters<TMethod>
-    const enabled = options?.enabled ?? true
-    const queryKey = hashQueryKey(options?.key ?? args)
-    const select = options?.select ?? (defaultSelect as (response: QueryResponse<TMethod>) => TData)
-
-    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<UseQueryState<QueryResponse<TMethod>, TData>>(() =>
-        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 (): Promise<QueryResponse<TMethod>> => {
-        const requestId = requestIdRef.current + 1
-        requestIdRef.current = requestId
-
-        setState((currentState) => startQuery(currentState, keepPreviousDataRef.current))
-
-        try {
-            const response = (await method(...argsRef.current)) as QueryResponse<TMethod>
-            const data = selectRef.current(response)
-
-            if (mountedRef.current && requestId === requestIdRef.current) {
-                setState({
-                    status: 'success',
-                    data,
-                    response,
-                    error: undefined,
-                    isFetching: false,
-                })
-            }
-
-            return response
-        } catch (error) {
-            if (mountedRef.current && requestId === requestIdRef.current) {
-                setState((currentState) => ({
-                    status: 'error',
-                    data: keepPreviousDataRef.current ? currentState.data : undefined,
-                    response: keepPreviousDataRef.current ? currentState.response : undefined,
-                    error,
-                    isFetching: false,
-                }))
-            }
-
-            throw error
-        }
-    }, [method])
-
-    useEffect(() => {
-        if (!enabled) {
-            requestIdRef.current += 1
-            setState(stopQuery)
-            return
-        }
-
-        void refetch().catch(() => undefined)
-
-        return () => {
-            requestIdRef.current += 1
-        }
-    }, [enabled, queryKey, refetch])
-
-    const result = toQueryResult(state, refetch)
-    useDebugValue(result.status)
-
-    return result
-}

package/src/client/responses.test.ts

@@ -1,151 +0,0 @@
-import { describe, expect, test } from 'bun:test'
-import { expectType, type TypeEqual } from '@mpen/ts-types'
-import {
-    isRoutekitProblemError,
-    resolveRoutekitProblemData,
-    RoutekitProblemError,
-    type ApiResponse,
-    type RoutekitProblemSuccessData,
-} from './responses'
-
-interface TodoSuccessBody {
-    success: true
-    data: {
-        id: string
-        title: string
-    }
-}
-
-interface TodoProblemBody {
-    success: false
-    error: {
-        code: 'not_found'
-        message: string
-    }
-    issues?: Array<{
-        code: string
-        message: string
-    }>
-}
-
-describe(RoutekitProblemError.name, () => {
-    test('preserves response details', () => {
-        const response: ApiResponse<TodoProblemBody> = {
-            ok: false,
-            status: 404,
-            headers: new Headers({ 'x-request-id': 'req_123' }),
-            body: {
-                success: false,
-                error: {
-                    code: 'not_found',
-                    message: 'Todo not found.',
-                },
-            },
-        }
-
-        const error = new RoutekitProblemError(response)
-
-        expect(error).toBeInstanceOf(Error)
-        expect(error.name).toBe('RoutekitProblemError')
-        expect(error.message).toBe('Todo not found.')
-        expect(error.status).toBe(404)
-        expect(error.headers.get('x-request-id')).toBe('req_123')
-        expect(error.body.error.code).toBe('not_found')
-        expect(error.response).toBe(response)
-    })
-})
-
-describe(isRoutekitProblemError.name, () => {
-    test('narrows routekit problem errors', () => {
-        const response: ApiResponse<TodoProblemBody> = {
-            ok: false,
-            status: 404,
-            headers: new Headers(),
-            body: {
-                success: false,
-                error: {
-                    code: 'not_found',
-                    message: 'Todo not found.',
-                },
-            },
-        }
-        const error: unknown = new RoutekitProblemError(response)
-
-        expect(isRoutekitProblemError<TodoProblemBody>(error)).toBe(true)
-        if (isRoutekitProblemError<TodoProblemBody>(error)) {
-            expectType<TypeEqual<typeof error.body, TodoProblemBody>>(true)
-            expect(error.body.error.code).toBe('not_found')
-        }
-    })
-})
-
-describe(resolveRoutekitProblemData.name, () => {
-    test('unwraps successful response data', async () => {
-        expectType<
-            TypeEqual<
-                RoutekitProblemSuccessData<TodoSuccessBody>,
-                {
-                    id: string
-                    title: string
-                }
-            >
-        >(true)
-
-        const data = await resolveRoutekitProblemData<TodoSuccessBody, TodoProblemBody>({
-            ok: true,
-            status: 200,
-            headers: new Headers(),
-            body: {
-                success: true,
-                data: {
-                    id: 'todo_123',
-                    title: 'Write tests',
-                },
-            },
-        })
-
-        expectType<
-            TypeEqual<
-                typeof data,
-                {
-                    id: string
-                    title: string
-                }
-            >
-        >(true)
-        expect(data).toEqual({
-            id: 'todo_123',
-            title: 'Write tests',
-        })
-    })
-
-    test('throws routekit problem errors with typed bodies', async () => {
-        expect.assertions(7)
-
-        try {
-            await resolveRoutekitProblemData<TodoSuccessBody, TodoProblemBody>({
-                status: 404,
-                headers: { 'x-request-id': 'req_456' },
-                body: {
-                    success: false,
-                    error: {
-                        code: 'not_found',
-                        message: 'Todo not found.',
-                    },
-                    issues: [{ code: 'missing', message: 'No matching todo exists.' }],
-                },
-            })
-        } catch (error) {
-            expect(isRoutekitProblemError<TodoProblemBody>(error)).toBe(true)
-            if (!isRoutekitProblemError<TodoProblemBody>(error)) return
-
-            expectType<TypeEqual<typeof error.body, TodoProblemBody>>(true)
-            expect(error.status).toBe(404)
-            expect(error.headers.get('x-request-id')).toBe('req_456')
-            expect(error.body.error.code).toBe('not_found')
-            expect(error.body.issues?.[0]?.code).toBe('missing')
-            expect(error.response.ok).toBe(false)
-            expect(error.response.body).toBe(error.body)
-        }
-    })
-})