@wp-typia/rest 0.2.0 → 0.3.1

package/README.md

@@ -7,10 +7,21 @@ This package focuses on:
 - validated `apiFetch` wrappers
 - typed endpoint helpers
 - canonical WordPress REST route URL resolution
+- a React/data convenience layer at `@wp-typia/rest/react`
 - optional query/header decoder helpers that can wrap Typia-generated HTTP decoders
 
 It does not include any WordPress PHP bridge logic. Generated PHP route code stays in `@wp-typia/create` templates.
 
+If you need a backend-neutral consumer instead of WordPress-specific route
+resolution, use `@wp-typia/api-client`.
+
+The root `@wp-typia/rest` entry stays transport-oriented. If you want query and
+mutation hooks on top of those WordPress helpers, use the React-only subpath:
+
+```ts
+import { useEndpointMutation, useEndpointQuery } from "@wp-typia/rest/react";
+```
+
 Typical usage:
 
 ```ts
@@ -44,3 +55,59 @@ const decodeQuery = createQueryDecoder(
   typia.http.createValidateQuery<MyQuery>()
 );
 ```
+
+## `@wp-typia/rest/react`
+
+The `./react` subpath adds a small cache client and React hook layer on top of
+`callEndpoint(...)`:
+
+- `createEndpointDataClient()`
+- `EndpointDataProvider`
+- `useEndpointDataClient()`
+- `useEndpointQuery(endpoint, request, options?)`
+- `useEndpointMutation(endpoint, options?)`
+
+`useEndpointQuery(...)` is GET-only in this first pass. Mutations and explicit
+non-query calls go through `useEndpointMutation(...)`.
+
+```tsx
+import {
+  useEndpointMutation,
+  useEndpointQuery,
+} from "@wp-typia/rest/react";
+
+const query = useEndpointQuery(stateEndpoint, request, {
+  staleTime: 30_000,
+  resolveCallOptions: () => ({
+    requestOptions: {
+      headers: {
+        "X-WP-Nonce": resolveRestNonce(),
+      },
+    },
+  }),
+});
+
+const mutation = useEndpointMutation(writeStateEndpoint, {
+  invalidate: { endpoint: stateEndpoint, request },
+  resolveCallOptions: () => ({
+    requestOptions: {
+      headers: {
+        "X-WP-Nonce": resolveRestNonce(),
+      },
+    },
+  }),
+});
+```
+
+The refresh model is explicit:
+
+- query hooks re-evaluate the latest `request` and `resolveCallOptions()` on
+  each execution
+- mutation hooks use the latest variables passed to `mutate(...)` and the latest
+  `resolveCallOptions(variables)`
+- stale nonces or public tokens do not trigger automatic retries; callers should
+  refresh auth state and then call `refetch()` or `mutate()` again
+
+For persistence scaffolds generated by `@wp-typia/create`, `src/api.ts` remains
+the WordPress call helper layer and `src/data.ts` adds block-specific wrappers
+around `@wp-typia/rest/react`.

package/dist/client.d.ts

@@ -1,21 +1,7 @@
 import type { APIFetchOptions, ApiFetch } from "@wordpress/api-fetch";
-import type { IValidation } from "@typia/interface";
-export interface ValidationError {
-    description?: string;
-    expected: string;
-    path: string;
-    value: unknown;
-}
-export interface ValidationResult<T> {
-    data?: T;
-    errors: ValidationError[];
-    isValid: boolean;
-}
-export type ValidationLike<T> = IValidation<T> | {
-    data?: unknown;
-    errors?: unknown;
-    success?: unknown;
-};
+import { type ValidationLike, type ValidationResult } from "./internal/runtime-primitives.js";
+export type { ValidationError, ValidationLike, ValidationResult } from "./internal/runtime-primitives.js";
+export { isValidationResult, normalizeValidationError, toValidationResult } from "./internal/runtime-primitives.js";
 export interface ValidatedFetch<T> {
     assertFetch(options: APIFetchOptions): Promise<T>;
     fetch(options: APIFetchOptions): Promise<ValidationResult<T>>;
@@ -37,9 +23,6 @@ export interface EndpointCallOptions {
     requestOptions?: Partial<APIFetchOptions>;
 }
 export declare function resolveRestRouteUrl(routePath: string, root?: string): string;
-export declare function normalizeValidationError(error: unknown): ValidationError;
-export declare function isValidationResult<T>(value: unknown): value is ValidationResult<T>;
-export declare function toValidationResult<T>(result: ValidationLike<T>): ValidationResult<T>;
 export declare function createValidatedFetch<T>(validator: (input: unknown) => ValidationLike<T>, fetchFn?: ApiFetch): ValidatedFetch<T>;
 export declare function createEndpoint<Req, Res>(config: ApiEndpoint<Req, Res>): ApiEndpoint<Req, Res>;
 export declare function callEndpoint<Req, Res>(endpoint: ApiEndpoint<Req, Res>, request: Req, { fetchFn, requestOptions }?: EndpointCallOptions): Promise<ValidationResult<Res>>;

package/dist/client.js

@@ -1,3 +1,5 @@
+import { isFormDataLike, isPlainObject, toValidationResult, } from "./internal/runtime-primitives.js";
+export { isValidationResult, normalizeValidationError, toValidationResult } from "./internal/runtime-primitives.js";
 function getDefaultRestRoot() {
     if (typeof window !== "undefined") {
         const wpApiSettings = window.wpApiSettings;
@@ -88,48 +90,6 @@ async function parseResponsePayload(response) {
         return text;
     }
 }
-function isPlainObject(value) {
-    return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-function isFormDataLike(value) {
-    return typeof FormData !== "undefined" && value instanceof FormData;
-}
-function normalizePath(path) {
-    return typeof path === "string" && path.length > 0 ? path : "(root)";
-}
-function normalizeExpected(expected) {
-    return typeof expected === "string" && expected.length > 0 ? expected : "unknown";
-}
-export function normalizeValidationError(error) {
-    const raw = isPlainObject(error) ? error : {};
-    return {
-        description: typeof raw.description === "string" ? raw.description : undefined,
-        expected: normalizeExpected(raw.expected),
-        path: normalizePath(raw.path),
-        value: Object.prototype.hasOwnProperty.call(raw, "value") ? raw.value : undefined,
-    };
-}
-export function isValidationResult(value) {
-    return isPlainObject(value) && typeof value.isValid === "boolean" && Array.isArray(value.errors);
-}
-export function toValidationResult(result) {
-    const rawResult = result;
-    if (isValidationResult(result)) {
-        return result;
-    }
-    if (rawResult.success === true) {
-        return {
-            data: rawResult.data,
-            errors: [],
-            isValid: true,
-        };
-    }
-    return {
-        data: undefined,
-        errors: Array.isArray(rawResult.errors) ? rawResult.errors.map(normalizeValidationError) : [],
-        isValid: false,
-    };
-}
 function encodeGetLikeRequest(request) {
     if (request === undefined || request === null) {
         return "";

package/dist/internal/runtime-primitives.d.ts

@@ -0,0 +1 @@
+export { isFormDataLike, isPlainObject, isValidationResult, normalizeExpected, normalizePath, normalizeValidationError, toValidationResult, type RawValidationError, type ValidationError, type ValidationLike, type ValidationResult, } from "@wp-typia/api-client/internal/runtime-primitives";

package/dist/internal/runtime-primitives.js

@@ -0,0 +1 @@
+export { isFormDataLike, isPlainObject, isValidationResult, normalizeExpected, normalizePath, normalizeValidationError, toValidationResult, } from "@wp-typia/api-client/internal/runtime-primitives";

package/dist/react.d.ts

@@ -0,0 +1,67 @@
+import { createElement } from "@wordpress/element";
+import type { ApiFetch } from "@wordpress/api-fetch";
+import { type ApiEndpoint, type EndpointCallOptions, type ValidationResult } from "./client.js";
+type EndpointDataUpdater<T> = T | ((current: T | undefined) => T | undefined);
+export interface EndpointDataClient {
+    invalidate<Req, Res>(endpoint: ApiEndpoint<Req, Res>, request?: Req): void;
+    refetch<Req, Res>(endpoint: ApiEndpoint<Req, Res>, request?: Req): Promise<void>;
+    getData<Req, Res>(endpoint: ApiEndpoint<Req, Res>, request: Req): Res | undefined;
+    setData<Req, Res>(endpoint: ApiEndpoint<Req, Res>, request: Req, next: EndpointDataUpdater<Res>): void;
+}
+export interface EndpointInvalidateTarget<E extends ApiEndpoint<any, any> = ApiEndpoint<any, any>> {
+    endpoint: E;
+    request?: E extends ApiEndpoint<infer Req, any> ? Req : never;
+}
+type EndpointInvalidateTargets = EndpointInvalidateTarget | readonly EndpointInvalidateTarget[] | undefined;
+export interface UseEndpointQueryOptions<_Req, Res, Selected = Res> {
+    client?: EndpointDataClient;
+    enabled?: boolean;
+    fetchFn?: ApiFetch;
+    initialData?: Res;
+    onError?: (error: unknown) => void | Promise<void>;
+    onSuccess?: (data: Selected, validation: ValidationResult<Res>) => void | Promise<void>;
+    resolveCallOptions?: () => EndpointCallOptions | undefined;
+    select?: (data: Res) => Selected;
+    staleTime?: number;
+}
+export interface UseEndpointQueryResult<Res, Selected = Res> {
+    data: Selected | undefined;
+    error: unknown;
+    isFetching: boolean;
+    isLoading: boolean;
+    refetch: () => Promise<ValidationResult<Res>>;
+    validation: ValidationResult<Res> | null;
+}
+export interface UseEndpointMutationOptions<Req, Res, Context = unknown> {
+    client?: EndpointDataClient;
+    fetchFn?: ApiFetch;
+    invalidate?: EndpointInvalidateTargets | ((data: Res | undefined, variables: Req, validation: ValidationResult<Res>) => EndpointInvalidateTargets);
+    onError?: (error: unknown, variables: Req, client: EndpointDataClient, context: Context | undefined) => void | Promise<void>;
+    onMutate?: (variables: Req, client: EndpointDataClient) => Context | Promise<Context>;
+    onSettled?: (result: {
+        data: Res | undefined;
+        error: unknown;
+        validation: ValidationResult<Res> | null;
+    }, variables: Req, client: EndpointDataClient, context: Context | undefined) => void | Promise<void>;
+    onSuccess?: (data: Res | undefined, variables: Req, validation: ValidationResult<Res>, client: EndpointDataClient, context: Context | undefined) => void | Promise<void>;
+    resolveCallOptions?: (variables: Req) => EndpointCallOptions | undefined;
+}
+export interface UseEndpointMutationResult<Req, Res> {
+    data: Res | undefined;
+    error: unknown;
+    isPending: boolean;
+    mutate: (variables: Req) => void;
+    mutateAsync: (variables: Req) => Promise<ValidationResult<Res>>;
+    reset: () => void;
+    validation: ValidationResult<Res> | null;
+}
+export interface EndpointDataProviderProps {
+    children?: unknown;
+    client: EndpointDataClient;
+}
+export declare function createEndpointDataClient(): EndpointDataClient;
+export declare function EndpointDataProvider({ children, client, }: EndpointDataProviderProps): ReturnType<typeof createElement>;
+export declare function useEndpointDataClient(): EndpointDataClient;
+export declare function useEndpointQuery<Req, Res, Selected = Res>(endpoint: ApiEndpoint<Req, Res>, request: Req, options?: UseEndpointQueryOptions<Req, Res, Selected>): UseEndpointQueryResult<Res, Selected>;
+export declare function useEndpointMutation<Req, Res, Context = unknown>(endpoint: ApiEndpoint<Req, Res>, options?: UseEndpointMutationOptions<Req, Res, Context>): UseEndpointMutationResult<Req, Res>;
+export {};

package/dist/react.js

@@ -0,0 +1,550 @@
+import { createContext, createElement, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore, } from "@wordpress/element";
+import { callEndpoint, } from "./client.js";
+import { isPlainObject } from "./internal/runtime-primitives.js";
+const EMPTY_SNAPSHOT = {
+    data: undefined,
+    error: null,
+    invalidatedAt: 0,
+    isFetching: false,
+    updatedAt: 0,
+    validation: null,
+};
+const EndpointDataClientContext = createContext(null);
+function normalizeCacheValue(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === null ||
+        typeof value === "boolean" ||
+        typeof value === "number" ||
+        typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "bigint") {
+        return { __bigint: String(value) };
+    }
+    if (value instanceof URLSearchParams) {
+        return {
+            __urlSearchParams: [...value.entries()].sort(([leftKey, leftValue], [rightKey, rightValue]) => leftKey === rightKey
+                ? leftValue.localeCompare(rightValue)
+                : leftKey.localeCompare(rightKey)),
+        };
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => normalizeCacheValue(item));
+    }
+    if (isPlainObject(value)) {
+        return Object.fromEntries(Object.entries(value)
+            .filter(([, item]) => item !== undefined)
+            .sort(([leftKey], [rightKey]) => leftKey.localeCompare(rightKey))
+            .map(([key, item]) => [key, normalizeCacheValue(item)]));
+    }
+    if (value instanceof Date) {
+        return { __date: value.toISOString() };
+    }
+    return String(value);
+}
+function createEndpointPrefix(endpoint) {
+    return `${endpoint.method} ${endpoint.path}`;
+}
+function createCacheKey(endpoint, request) {
+    const requestValidation = endpoint.validateRequest(request);
+    const normalizedRequest = requestValidation.isValid
+        ? requestValidation.data ?? request
+        : request;
+    return {
+        cacheKey: `${createEndpointPrefix(endpoint)}::${JSON.stringify(normalizeCacheValue(normalizedRequest))}`,
+        requestValidation,
+    };
+}
+function normalizeInvalidateTargets(targets) {
+    if (!targets) {
+        return [];
+    }
+    return (Array.isArray(targets) ? targets : [targets]);
+}
+function getOrCreateEntry(entries, cacheKey) {
+    const existing = entries.get(cacheKey);
+    if (existing) {
+        return existing;
+    }
+    const created = {
+        ...EMPTY_SNAPSHOT,
+        listeners: new Set(),
+        promise: null,
+        refetchers: new Set(),
+        snapshot: EMPTY_SNAPSHOT,
+    };
+    entries.set(cacheKey, created);
+    return created;
+}
+function syncSnapshot(entry) {
+    entry.snapshot = {
+        data: entry.data,
+        error: entry.error,
+        invalidatedAt: entry.invalidatedAt,
+        isFetching: entry.isFetching,
+        updatedAt: entry.updatedAt,
+        validation: entry.validation,
+    };
+}
+function isEntryStale(entry, staleTime) {
+    if (entry.updatedAt === 0) {
+        return true;
+    }
+    if (entry.invalidatedAt > entry.updatedAt) {
+        return true;
+    }
+    if (staleTime === 0) {
+        return true;
+    }
+    return Date.now() - entry.updatedAt > staleTime;
+}
+function asInternalClient(client) {
+    return client;
+}
+export function createEndpointDataClient() {
+    const entries = new Map();
+    function notify(cacheKey) {
+        const entry = entries.get(cacheKey);
+        if (!entry) {
+            return;
+        }
+        for (const listener of entry.listeners) {
+            listener();
+        }
+    }
+    const client = {
+        invalidate(endpoint, request) {
+            if (request !== undefined) {
+                const { cacheKey } = createCacheKey(endpoint, request);
+                const entry = entries.get(cacheKey);
+                if (!entry) {
+                    return;
+                }
+                entry.invalidatedAt = Date.now();
+                syncSnapshot(entry);
+                notify(cacheKey);
+                return;
+            }
+            const prefix = createEndpointPrefix(endpoint);
+            for (const [cacheKey, entry] of entries.entries()) {
+                if (!cacheKey.startsWith(`${prefix}::`)) {
+                    continue;
+                }
+                entry.invalidatedAt = Date.now();
+                syncSnapshot(entry);
+                notify(cacheKey);
+            }
+        },
+        async refetch(endpoint, request) {
+            const callbacks = new Set();
+            if (request !== undefined) {
+                const { cacheKey } = createCacheKey(endpoint, request);
+                for (const refetcher of entries.get(cacheKey)?.refetchers ?? []) {
+                    callbacks.add(refetcher);
+                }
+            }
+            else {
+                const prefix = createEndpointPrefix(endpoint);
+                for (const [cacheKey, entry] of entries.entries()) {
+                    if (!cacheKey.startsWith(`${prefix}::`)) {
+                        continue;
+                    }
+                    for (const refetcher of entry.refetchers) {
+                        callbacks.add(refetcher);
+                    }
+                }
+            }
+            await Promise.all([...callbacks].map((refetcher) => refetcher()));
+        },
+        getData(endpoint, request) {
+            const { cacheKey } = createCacheKey(endpoint, request);
+            return entries.get(cacheKey)?.data;
+        },
+        setData(endpoint, request, next) {
+            const { cacheKey } = createCacheKey(endpoint, request);
+            const entry = getOrCreateEntry(entries, cacheKey);
+            const resolvedNext = typeof next === "function"
+                ? next(entry.data)
+                : next;
+            entry.data = resolvedNext;
+            entry.error = null;
+            entry.updatedAt = Date.now();
+            entry.validation = {
+                data: resolvedNext,
+                errors: [],
+                isValid: true,
+            };
+            syncSnapshot(entry);
+            notify(cacheKey);
+        },
+        __getSnapshot(cacheKey) {
+            const entry = entries.get(cacheKey);
+            if (!entry) {
+                return EMPTY_SNAPSHOT;
+            }
+            return entry.snapshot;
+        },
+        __publishValidation(cacheKey, validation) {
+            const entry = getOrCreateEntry(entries, cacheKey);
+            entry.error = null;
+            entry.updatedAt = Date.now();
+            entry.validation = validation;
+            if (validation.isValid) {
+                entry.data = validation.data;
+            }
+            syncSnapshot(entry);
+            notify(cacheKey);
+        },
+        __registerRefetcher(cacheKey, refetcher) {
+            const entry = getOrCreateEntry(entries, cacheKey);
+            entry.refetchers.add(refetcher);
+            return () => {
+                entry.refetchers.delete(refetcher);
+            };
+        },
+        async __runQuery(cacheKey, execute, { force = false, staleTime }) {
+            const entry = getOrCreateEntry(entries, cacheKey);
+            if (entry.promise) {
+                return entry.promise;
+            }
+            if (!force) {
+                if (!isEntryStale(entry, staleTime) && entry.validation) {
+                    return entry.validation;
+                }
+            }
+            entry.error = null;
+            entry.isFetching = true;
+            syncSnapshot(entry);
+            notify(cacheKey);
+            const startedAt = Date.now();
+            const promise = execute()
+                .then((validation) => {
+                entry.error = null;
+                if (entry.invalidatedAt <= startedAt) {
+                    entry.updatedAt = Date.now();
+                    entry.validation = validation;
+                    if (validation.isValid) {
+                        entry.data = validation.data;
+                    }
+                }
+                syncSnapshot(entry);
+                return validation;
+            })
+                .catch((error) => {
+                entry.error = error;
+                if (entry.invalidatedAt <= startedAt) {
+                    entry.updatedAt = Date.now();
+                }
+                syncSnapshot(entry);
+                throw error;
+            })
+                .finally(() => {
+                entry.isFetching = false;
+                entry.promise = null;
+                syncSnapshot(entry);
+                notify(cacheKey);
+            });
+            entry.promise = promise;
+            return promise;
+        },
+        __seedData(cacheKey, data) {
+            const entry = getOrCreateEntry(entries, cacheKey);
+            if (entry.validation) {
+                return;
+            }
+            entry.data = data;
+            entry.error = null;
+            entry.updatedAt = Date.now();
+            entry.validation = {
+                data,
+                errors: [],
+                isValid: true,
+            };
+            syncSnapshot(entry);
+            notify(cacheKey);
+        },
+        __subscribe(cacheKey, listener) {
+            const entry = getOrCreateEntry(entries, cacheKey);
+            entry.listeners.add(listener);
+            return () => {
+                entry.listeners.delete(listener);
+            };
+        },
+    };
+    return client;
+}
+const defaultEndpointDataClient = createEndpointDataClient();
+export function EndpointDataProvider({ children, client, }) {
+    return createElement(EndpointDataClientContext.Provider, { value: client }, children);
+}
+export function useEndpointDataClient() {
+    return useContext(EndpointDataClientContext) ?? defaultEndpointDataClient;
+}
+export function useEndpointQuery(endpoint, request, options = {}) {
+    if (endpoint.method !== "GET") {
+        throw new Error("useEndpointQuery only supports GET endpoints in v1.");
+    }
+    const defaultClient = useEndpointDataClient();
+    const client = asInternalClient(options.client ?? defaultClient);
+    const { enabled = true, fetchFn, initialData, onError, onSuccess, resolveCallOptions, select, staleTime = 0, } = options;
+    const prepared = useMemo(() => createCacheKey(endpoint, request), [endpoint, request]);
+    const snapshot = useSyncExternalStore((listener) => client.__subscribe(prepared.cacheKey, listener), () => client.__getSnapshot(prepared.cacheKey), () => client.__getSnapshot(prepared.cacheKey));
+    const latestRef = useRef({
+        cacheKey: prepared.cacheKey,
+        client,
+        endpoint,
+        fetchFn,
+        onError,
+        onSuccess,
+        request,
+        requestValidation: prepared.requestValidation,
+        resolveCallOptions,
+        select,
+        staleTime,
+    });
+    latestRef.current = {
+        cacheKey: prepared.cacheKey,
+        client,
+        endpoint,
+        fetchFn,
+        onError,
+        onSuccess,
+        request,
+        requestValidation: prepared.requestValidation,
+        resolveCallOptions,
+        select,
+        staleTime,
+    };
+    const refetchRef = useRef();
+    const executeQueryRef = useRef();
+    const hasAutoFetchedZeroStaleRef = useRef(false);
+    useEffect(() => {
+        hasAutoFetchedZeroStaleRef.current = false;
+    }, [enabled, prepared.cacheKey, staleTime]);
+    // Keep these callbacks stable while still reading the latest runtime inputs
+    // from latestRef.current on each execution.
+    if (!executeQueryRef.current) {
+        executeQueryRef.current = async (force) => {
+            const latest = latestRef.current;
+            if (!latest.requestValidation.isValid) {
+                const invalidValidation = latest.requestValidation;
+                latest.client.__publishValidation(latest.cacheKey, invalidValidation);
+                return invalidValidation;
+            }
+            try {
+                const callOptions = latest.resolveCallOptions?.();
+                const validation = await latest.client.__runQuery(latest.cacheKey, () => callEndpoint(latest.endpoint, latest.request, {
+                    fetchFn: callOptions?.fetchFn ?? latest.fetchFn,
+                    requestOptions: callOptions?.requestOptions,
+                }), { force, staleTime: latest.staleTime });
+                if (validation.isValid) {
+                    const selected = latest.select !== undefined
+                        ? latest.select(validation.data)
+                        : validation.data;
+                    await latest.onSuccess?.(selected, validation);
+                }
+                return validation;
+            }
+            catch (error) {
+                await latest.onError?.(error);
+                throw error;
+            }
+        };
+    }
+    const executeQuery = executeQueryRef.current;
+    if (!refetchRef.current) {
+        refetchRef.current = () => executeQuery(true);
+    }
+    const refetch = refetchRef.current;
+    useEffect(() => {
+        return client.__registerRefetcher(prepared.cacheKey, () => refetch());
+    }, [client, prepared.cacheKey, refetch]);
+    useEffect(() => {
+        if (initialData === undefined || snapshot.validation) {
+            return;
+        }
+        client.__seedData(prepared.cacheKey, initialData);
+    }, [client, initialData, prepared.cacheKey, snapshot.validation]);
+    useEffect(() => {
+        if (!enabled) {
+            return;
+        }
+        if (!prepared.requestValidation.isValid) {
+            if (snapshot.validation?.isValid === false) {
+                return;
+            }
+            client.__publishValidation(prepared.cacheKey, prepared.requestValidation);
+            return;
+        }
+        if (snapshot.isFetching) {
+            return;
+        }
+        const shouldFetch = snapshot.updatedAt === 0
+            ? initialData === undefined
+            : snapshot.invalidatedAt > snapshot.updatedAt
+                ? true
+                : snapshot.error !== null
+                    ? false
+                    : staleTime === 0
+                        ? !hasAutoFetchedZeroStaleRef.current
+                        : Date.now() - snapshot.updatedAt > staleTime;
+        if (!shouldFetch) {
+            return;
+        }
+        if (staleTime === 0) {
+            hasAutoFetchedZeroStaleRef.current = true;
+        }
+        void executeQuery(false).catch(() => { });
+    }, [
+        client,
+        enabled,
+        executeQuery,
+        initialData,
+        prepared.cacheKey,
+        prepared.requestValidation.isValid,
+        snapshot.isFetching,
+        refetch,
+        snapshot.invalidatedAt,
+        snapshot.updatedAt,
+        staleTime,
+    ]);
+    const data = useMemo(() => {
+        const rawData = snapshot.data === undefined && snapshot.validation === null
+            ? initialData
+            : snapshot.data;
+        if (rawData === undefined) {
+            return undefined;
+        }
+        return select !== undefined
+            ? select(rawData)
+            : rawData;
+    }, [initialData, select, snapshot.data, snapshot.validation]);
+    return {
+        data,
+        error: snapshot.error,
+        isFetching: snapshot.isFetching,
+        isLoading: snapshot.isFetching &&
+            data === undefined,
+        refetch,
+        validation: snapshot.validation,
+    };
+}
+export function useEndpointMutation(endpoint, options = {}) {
+    const defaultClient = useEndpointDataClient();
+    const client = options.client ?? defaultClient;
+    const { fetchFn, invalidate, onError, onMutate, onSettled, onSuccess, resolveCallOptions, } = options;
+    const [data, setData] = useState(undefined);
+    const [error, setError] = useState(null);
+    const [isPending, setIsPending] = useState(false);
+    const [validation, setValidation] = useState(null);
+    const pendingCountRef = useRef(0);
+    const latestRef = useRef({
+        client,
+        endpoint,
+        fetchFn,
+        invalidate,
+        onError,
+        onMutate,
+        onSettled,
+        onSuccess,
+        resolveCallOptions,
+    });
+    latestRef.current = {
+        client,
+        endpoint,
+        fetchFn,
+        invalidate,
+        onError,
+        onMutate,
+        onSettled,
+        onSuccess,
+        resolveCallOptions,
+    };
+    const mutateAsyncRef = useRef();
+    if (!mutateAsyncRef.current) {
+        mutateAsyncRef.current = async (variables) => {
+            const latest = latestRef.current;
+            pendingCountRef.current += 1;
+            setIsPending(true);
+            setError(null);
+            setValidation(null);
+            let context;
+            try {
+                context = latest.onMutate
+                    ? await latest.onMutate(variables, latest.client)
+                    : undefined;
+                const callOptions = latest.resolveCallOptions?.(variables);
+                const result = await callEndpoint(latest.endpoint, variables, {
+                    fetchFn: callOptions?.fetchFn ?? latest.fetchFn,
+                    requestOptions: callOptions?.requestOptions,
+                });
+                setValidation(result);
+                if (result.isValid) {
+                    setData(result.data);
+                    await latest.onSuccess?.(result.data, variables, result, latest.client, context);
+                    const targets = normalizeInvalidateTargets(typeof latest.invalidate === "function"
+                        ? latest.invalidate(result.data, variables, result)
+                        : latest.invalidate);
+                    for (const target of targets) {
+                        latest.client.invalidate(target.endpoint, target.request);
+                    }
+                }
+                else {
+                    setData(undefined);
+                    setError(result);
+                    await latest.onError?.(result, variables, latest.client, context);
+                    const targets = normalizeInvalidateTargets(typeof latest.invalidate === "function"
+                        ? latest.invalidate(undefined, variables, result)
+                        : latest.invalidate);
+                    for (const target of targets) {
+                        latest.client.invalidate(target.endpoint, target.request);
+                    }
+                }
+                await latest.onSettled?.({
+                    data: result.isValid ? result.data : undefined,
+                    error: result.isValid ? null : result,
+                    validation: result,
+                }, variables, latest.client, context);
+                return result;
+            }
+            catch (nextError) {
+                setData(undefined);
+                setError(nextError);
+                setValidation(null);
+                await latest.onError?.(nextError, variables, latest.client, context);
+                await latest.onSettled?.({
+                    data: undefined,
+                    error: nextError,
+                    validation: null,
+                }, variables, latest.client, context);
+                throw nextError;
+            }
+            finally {
+                pendingCountRef.current = Math.max(0, pendingCountRef.current - 1);
+                setIsPending(pendingCountRef.current > 0);
+            }
+        };
+    }
+    const mutateAsync = mutateAsyncRef.current;
+    const mutate = (variables) => {
+        void mutateAsync(variables).catch(() => { });
+    };
+    const reset = () => {
+        pendingCountRef.current = 0;
+        setData(undefined);
+        setError(null);
+        setIsPending(false);
+        setValidation(null);
+    };
+    return {
+        data,
+        error,
+        isPending,
+        mutate,
+        mutateAsync,
+        reset,
+        validation,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wp-typia/rest",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Typed WordPress REST helpers powered by Typia validation",
   "type": "module",
   "main": "dist/index.js",
@@ -21,6 +21,11 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js",
+      "default": "./dist/react.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -29,10 +34,11 @@
     "package.json"
   ],
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json && bun ./scripts/fix-dist-imports.mjs",
+    "build": "bun run --filter @wp-typia/api-client build && rm -rf dist && tsc -p tsconfig.build.json && bun ./scripts/fix-dist-imports.mjs",
     "clean": "rm -rf dist",
-    "test": "bun run build && bun test tests",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "test": "bun run build && cd ../.. && bun test packages/wp-typia-rest/tests",
+    "test:coverage": "bun run build && cd ../.. && bun test packages/wp-typia-rest/tests --coverage --coverage-reporter=text --coverage-reporter=lcov --coverage-dir=packages/wp-typia-rest/coverage",
+    "typecheck": "bun run --filter @wp-typia/api-client build && tsc -p tsconfig.build.json --noEmit"
   },
   "author": "imjlk",
   "license": "GPL-2.0-or-later",
@@ -54,10 +60,21 @@
     "bun": ">=1.3.10"
   },
   "dependencies": {
+    "@wp-typia/api-client": "workspace:*",
     "@typia/interface": "^12.0.1",
     "@wordpress/api-fetch": "^7.42.0"
   },
+  "peerDependencies": {
+    "@wordpress/element": "^6.29.0"
+  },
+  "peerDependenciesMeta": {
+    "@wordpress/element": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@wordpress/element": "^6.29.0",
+    "happy-dom": "^20.8.9",
     "typescript": "^5.9.2"
   }
 }