@wp-typia/rest 0.3.5 → 0.3.7

package/README.md

@@ -15,44 +15,73 @@ It does not include any WordPress PHP bridge logic. Generated PHP route code sta
 If you need a backend-neutral consumer instead of WordPress-specific route
 resolution, use `@wp-typia/api-client`.
 
+## Export contract
+
+- `@wp-typia/rest`
+  Canonical convenience surface for transport helpers plus HTTP decoder helpers.
+- `@wp-typia/rest/client`
+  Backward-compatible alias of the root surface. It is not a distinct semantic
+  contract and may be removed in a future major once downstream imports settle.
+- `@wp-typia/rest/http`
+  Backward-compatible alias of the root surface. It remains publishable for
+  existing imports, but it is not a distinct decoder-only contract in the
+  current major line.
+- `@wp-typia/rest/react`
+  React-only cache and hook layer.
+
 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";
+import { useEndpointMutation, useEndpointQuery } from '@wp-typia/rest/react';
 ```
 
 Typical usage:
 
 ```ts
-import { callEndpoint, createEndpoint } from "@wp-typia/rest";
+import { callEndpoint, createEndpoint } from '@wp-typia/rest';
 
 const endpoint = createEndpoint<MyRequest, MyResponse>({
-  method: "POST",
-  path: "/my-namespace/v1/demo",
+  method: 'POST',
+  path: '/my-namespace/v1/demo',
   validateRequest: validators.request,
   validateResponse: validators.response,
 });
 
-const result = await callEndpoint(endpoint, { title: "Hello" });
+const result = await callEndpoint(endpoint, { title: 'Hello' });
 ```
 
+`callEndpoint(...)` returns `EndpointValidationResult<Req, Res>`. If request
+validation fails before transport execution, the result keeps
+`validationTarget: "request"`. Response validation runs after transport and uses
+`validationTarget: "response"`.
+
+Invalid request/response payloads stay in that result union. Thrown exceptions
+are reserved for public runtime misconfiguration or assertion APIs:
+
+- `RestConfigurationError`
+- `RestRootResolutionError`
+- `RestQueryHookUsageError`
+- `RestValidationAssertionError`
+- shared base classes re-exported from `@wp-typia/api-client`:
+  `WpTypiaContractError` and `WpTypiaValidationAssertionError`
+
 If you need a canonical REST URL for a route path, use:
 
 ```ts
-import { resolveRestRouteUrl } from "@wp-typia/rest";
+import { resolveRestRouteUrl } from '@wp-typia/rest';
 
-const url = resolveRestRouteUrl("/my-namespace/v1/demo");
+const url = resolveRestRouteUrl('/my-namespace/v1/demo');
 ```
 
 If you want Typia-powered HTTP decoding, compile the decoder in the consumer project and pass it in:
 
 ```ts
-import typia from "typia";
-import { createQueryDecoder } from "@wp-typia/rest";
+import typia from 'typia';
+import { createQueryDecoder } from '@wp-typia/rest';
 
 const decodeQuery = createQueryDecoder(
-  typia.http.createValidateQuery<MyQuery>()
+  typia.http.createValidateQuery<MyQuery>(),
 );
 ```
 
@@ -71,17 +100,14 @@ The `./react` subpath adds a small cache client and React hook layer on top of
 non-query calls go through `useEndpointMutation(...)`.
 
 ```tsx
-import {
-  useEndpointMutation,
-  useEndpointQuery,
-} from "@wp-typia/rest/react";
+import { useEndpointMutation, useEndpointQuery } from '@wp-typia/rest/react';
 
 const query = useEndpointQuery(stateEndpoint, request, {
   staleTime: 30_000,
   resolveCallOptions: () => ({
     requestOptions: {
       headers: {
-        "X-WP-Nonce": resolveRestNonce(),
+        'X-WP-Nonce': resolveRestNonce(),
       },
     },
   }),
@@ -92,7 +118,7 @@ const mutation = useEndpointMutation(writeStateEndpoint, {
   resolveCallOptions: () => ({
     requestOptions: {
       headers: {
-        "X-WP-Nonce": resolveRestNonce(),
+        'X-WP-Nonce': resolveRestNonce(),
       },
     },
   }),

package/dist/client.d.ts

@@ -1,7 +1,9 @@
 import type { APIFetchOptions, ApiFetch } from "@wordpress/api-fetch";
+import type { EndpointValidationResult } from "@wp-typia/api-client";
 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 type { EndpointRequestValidationResult, EndpointResponseValidationResult, EndpointValidationResult, EndpointValidationTarget, } from "@wp-typia/api-client";
 export interface ValidatedFetch<T> {
     assertFetch(options: APIFetchOptions): Promise<T>;
     fetch(options: APIFetchOptions): Promise<ValidationResult<T>>;
@@ -25,4 +27,4 @@ export interface EndpointCallOptions {
 export declare function resolveRestRouteUrl(routePath: string, root?: string): string;
 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>>;
+export declare function callEndpoint<Req, Res>(endpoint: ApiEndpoint<Req, Res>, request: Req, { fetchFn, requestOptions }?: EndpointCallOptions): Promise<EndpointValidationResult<Req, Res>>;

package/dist/client.js

@@ -1,5 +1,6 @@
 import { encodeGetLikeRequest, joinPathWithQuery, joinUrlWithQuery, mergeHeaderInputs, parseResponsePayload, } from "@wp-typia/api-client/client-utils";
 import { isFormDataLike, toValidationResult, } from "./internal/runtime-primitives.js";
+import { RestConfigurationError, RestRootResolutionError, RestValidationAssertionError, } from "./errors.js";
 export { isValidationResult, normalizeValidationError, toValidationResult } from "./internal/runtime-primitives.js";
 function getDefaultRestRoot() {
     if (typeof window !== "undefined") {
@@ -15,7 +16,7 @@ function getDefaultRestRoot() {
             }
         }
     }
-    throw new Error("Unable to resolve the WordPress REST root automatically. Provide wpApiSettings.root, an api.w.org discovery link, or an explicit url.");
+    throw new RestRootResolutionError("Unable to resolve the WordPress REST root automatically. Provide wpApiSettings.root, an api.w.org discovery link, or an explicit url.");
 }
 export function resolveRestRouteUrl(routePath, root = getDefaultRestRoot()) {
     const [pathWithQuery, hash = ""] = routePath.split("#", 2);
@@ -50,7 +51,7 @@ function resolveFetchUrl(options) {
     if (typeof options.path === "string" && options.path.length > 0) {
         return resolveRestRouteUrl(options.path);
     }
-    throw new Error("API fetch options must include either a path or a url.");
+    throw new RestConfigurationError("API fetch options must include either a path or a url.");
 }
 async function defaultFetch(options) {
     const response = await fetch(resolveFetchUrl(options), {
@@ -154,7 +155,7 @@ export function createValidatedFetch(validator, fetchFn = defaultFetch) {
         async assertFetch(options) {
             const result = await this.fetch(options);
             if (!result.isValid) {
-                throw new Error(result.errors[0]
+                throw new RestValidationAssertionError(result, result.errors[0]
                     ? `${result.errors[0].path}: ${result.errors[0].expected}`
                     : "REST response validation failed.");
             }
@@ -169,11 +170,26 @@ export function createValidatedFetch(validator, fetchFn = defaultFetch) {
 export function createEndpoint(config) {
     return config;
 }
+function isInvalidValidationResult(validation) {
+    return validation.isValid === false;
+}
+function toEndpointRequestValidationResult(validation) {
+    return {
+        ...validation,
+        validationTarget: "request",
+    };
+}
+function toEndpointResponseValidationResult(validation) {
+    return {
+        ...validation,
+        validationTarget: "response",
+    };
+}
 export async function callEndpoint(endpoint, request, { fetchFn = defaultFetch, requestOptions } = {}) {
     const requestValidation = endpoint.validateRequest(request);
-    if (!requestValidation.isValid) {
-        return requestValidation;
+    if (isInvalidValidationResult(requestValidation)) {
+        return toEndpointRequestValidationResult(requestValidation);
     }
     const payload = await fetchFn(mergeFetchOptions(buildEndpointFetchOptions(endpoint, request), requestOptions));
-    return endpoint.validateResponse(payload);
+    return toEndpointResponseValidationResult(endpoint.validateResponse(payload));
 }

package/dist/errors.d.ts

@@ -0,0 +1,14 @@
+import { WpTypiaContractError, WpTypiaValidationAssertionError, type ValidationResult } from "@wp-typia/api-client";
+export { ApiClientConfigurationError, WpTypiaContractError, WpTypiaValidationAssertionError, } from "@wp-typia/api-client";
+export declare class RestConfigurationError extends WpTypiaContractError {
+    constructor(message: string);
+}
+export declare class RestRootResolutionError extends RestConfigurationError {
+    constructor(message: string);
+}
+export declare class RestQueryHookUsageError extends RestConfigurationError {
+    constructor(message: string);
+}
+export declare class RestValidationAssertionError<T = unknown> extends WpTypiaValidationAssertionError<T> {
+    constructor(validation: ValidationResult<T>, message: string);
+}

package/dist/errors.js

@@ -0,0 +1,25 @@
+import { WpTypiaContractError, WpTypiaValidationAssertionError, } from "@wp-typia/api-client";
+export { ApiClientConfigurationError, WpTypiaContractError, WpTypiaValidationAssertionError, } from "@wp-typia/api-client";
+export class RestConfigurationError extends WpTypiaContractError {
+    constructor(message) {
+        super(message, "REST_CONFIGURATION_ERROR");
+    }
+}
+export class RestRootResolutionError extends RestConfigurationError {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+export class RestQueryHookUsageError extends RestConfigurationError {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+export class RestValidationAssertionError extends WpTypiaValidationAssertionError {
+    constructor(validation, message) {
+        super(validation, message);
+        this.name = new.target.name;
+    }
+}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
-export { createEndpoint, createValidatedFetch, callEndpoint, isValidationResult, normalizeValidationError, resolveRestRouteUrl, toValidationResult, type ApiEndpoint, type EndpointCallOptions, type ValidatedFetch, type ValidationResult, type ValidationError, type ValidationLike, } from "./client.js";
+export { createEndpoint, createValidatedFetch, callEndpoint, isValidationResult, normalizeValidationError, resolveRestRouteUrl, toValidationResult, type ApiEndpoint, type EndpointCallOptions, type EndpointRequestValidationResult, type EndpointResponseValidationResult, type EndpointValidationResult, type EndpointValidationTarget, type ValidatedFetch, type ValidationResult, type ValidationError, type ValidationLike, } from "./client.js";
+export { ApiClientConfigurationError, RestConfigurationError, RestQueryHookUsageError, RestRootResolutionError, RestValidationAssertionError, WpTypiaContractError, WpTypiaValidationAssertionError, } from "./errors.js";
 export { createHeadersDecoder, createParameterDecoder, createQueryDecoder, } from "./http.js";

package/dist/index.js

@@ -1,2 +1,3 @@
 export { createEndpoint, createValidatedFetch, callEndpoint, isValidationResult, normalizeValidationError, resolveRestRouteUrl, toValidationResult, } from "./client.js";
+export { ApiClientConfigurationError, RestConfigurationError, RestQueryHookUsageError, RestRootResolutionError, RestValidationAssertionError, WpTypiaContractError, WpTypiaValidationAssertionError, } from "./errors.js";
 export { createHeadersDecoder, createParameterDecoder, createQueryDecoder, } from "./http.js";

package/dist/react.d.ts

@@ -1,6 +1,6 @@
 import { createElement } from "@wordpress/element";
 import type { ApiFetch } from "@wordpress/api-fetch";
-import { type ApiEndpoint, type EndpointCallOptions, type ValidationResult } from "./client.js";
+import { type ApiEndpoint, type EndpointCallOptions, type EndpointResponseValidationResult, type EndpointValidationResult } 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;
@@ -19,31 +19,31 @@ export interface UseEndpointQueryOptions<_Req, Res, Selected = Res> {
     fetchFn?: ApiFetch;
     initialData?: Res;
     onError?: (error: unknown) => void | Promise<void>;
-    onSuccess?: (data: Selected, validation: ValidationResult<Res>) => void | Promise<void>;
+    onSuccess?: (data: Selected, validation: EndpointResponseValidationResult<Res>) => void | Promise<void>;
     resolveCallOptions?: () => EndpointCallOptions | undefined;
     select?: (data: Res) => Selected;
     staleTime?: number;
 }
-export interface UseEndpointQueryResult<Res, Selected = Res> {
+export interface UseEndpointQueryResult<Res, Selected = Res, Req = unknown> {
     data: Selected | undefined;
     error: unknown;
     isFetching: boolean;
     isLoading: boolean;
-    refetch: () => Promise<ValidationResult<Res>>;
-    validation: ValidationResult<Res> | null;
+    refetch: () => Promise<EndpointValidationResult<Req, Res>>;
+    validation: EndpointValidationResult<Req, Res> | null;
 }
 export interface UseEndpointMutationOptions<Req, Res, Context = unknown> {
     client?: EndpointDataClient;
     fetchFn?: ApiFetch;
-    invalidate?: EndpointInvalidateTargets | ((data: Res | undefined, variables: Req, validation: ValidationResult<Res>) => EndpointInvalidateTargets);
+    invalidate?: EndpointInvalidateTargets | ((data: Res | undefined, variables: Req, validation: EndpointValidationResult<Req, 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;
+        validation: EndpointValidationResult<Req, 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>;
+    onSuccess?: (data: Res | undefined, variables: Req, validation: EndpointResponseValidationResult<Res>, client: EndpointDataClient, context: Context | undefined) => void | Promise<void>;
     resolveCallOptions?: (variables: Req) => EndpointCallOptions | undefined;
 }
 export interface UseEndpointMutationResult<Req, Res> {
@@ -51,9 +51,9 @@ export interface UseEndpointMutationResult<Req, Res> {
     error: unknown;
     isPending: boolean;
     mutate: (variables: Req) => void;
-    mutateAsync: (variables: Req) => Promise<ValidationResult<Res>>;
+    mutateAsync: (variables: Req) => Promise<EndpointValidationResult<Req, Res>>;
     reset: () => void;
-    validation: ValidationResult<Res> | null;
+    validation: EndpointValidationResult<Req, Res> | null;
 }
 export interface EndpointDataProviderProps {
     children?: unknown;
@@ -62,6 +62,6 @@ export interface EndpointDataProviderProps {
 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 useEndpointQuery<Req, Res, Selected = Res>(endpoint: ApiEndpoint<Req, Res>, request: Req, options?: UseEndpointQueryOptions<Req, Res, Selected>): UseEndpointQueryResult<Res, Selected, Req>;
 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

@@ -1,5 +1,6 @@
 import { createContext, createElement, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore, } from "@wordpress/element";
 import { callEndpoint, } from "./client.js";
+import { RestQueryHookUsageError } from "./errors.js";
 import { isPlainObject } from "./internal/runtime-primitives.js";
 const EMPTY_SNAPSHOT = {
     data: undefined,
@@ -10,6 +11,18 @@ const EMPTY_SNAPSHOT = {
     validation: null,
 };
 const EndpointDataClientContext = createContext(null);
+const endpointIdentityIds = new WeakMap();
+let nextEndpointIdentityId = 0;
+function getStableEndpointIdentity(value) {
+    const existing = endpointIdentityIds.get(value);
+    if (existing !== undefined) {
+        return existing;
+    }
+    const created = nextEndpointIdentityId;
+    nextEndpointIdentityId += 1;
+    endpointIdentityIds.set(value, created);
+    return created;
+}
 function normalizeCacheValue(value) {
     if (value === undefined) {
         return undefined;
@@ -45,7 +58,18 @@ function normalizeCacheValue(value) {
     return String(value);
 }
 function createEndpointPrefix(endpoint) {
-    return `${endpoint.method} ${endpoint.path}`;
+    const requestValidatorId = getStableEndpointIdentity(endpoint.validateRequest);
+    const responseValidatorId = getStableEndpointIdentity(endpoint.validateResponse);
+    const requestBuilderId = endpoint.buildRequestOptions !== undefined
+        ? getStableEndpointIdentity(endpoint.buildRequestOptions)
+        : -1;
+    return [
+        endpoint.method,
+        endpoint.path,
+        `request:${requestValidatorId}`,
+        `response:${responseValidatorId}`,
+        `builder:${requestBuilderId}`,
+    ].join(" ");
 }
 function createCacheKey(endpoint, request) {
     const requestValidation = endpoint.validateRequest(request);
@@ -103,6 +127,21 @@ function isEntryStale(entry, staleTime) {
 function asInternalClient(client) {
     return client;
 }
+function isInvalidValidationResult(validation) {
+    return validation.isValid === false;
+}
+function toEndpointRequestValidationResult(validation) {
+    return {
+        ...validation,
+        validationTarget: "request",
+    };
+}
+function toEndpointResponseValidationResult(validation) {
+    return {
+        ...validation,
+        validationTarget: "response",
+    };
+}
 export function createEndpointDataClient() {
     const entries = new Map();
     function notify(cacheKey) {
@@ -171,11 +210,11 @@ export function createEndpointDataClient() {
             entry.data = resolvedNext;
             entry.error = null;
             entry.updatedAt = Date.now();
-            entry.validation = {
+            entry.validation = toEndpointResponseValidationResult({
                 data: resolvedNext,
                 errors: [],
                 isValid: true,
-            };
+            });
             syncSnapshot(entry);
             notify(cacheKey);
         },
@@ -194,6 +233,9 @@ export function createEndpointDataClient() {
             if (validation.isValid) {
                 entry.data = validation.data;
             }
+            else if (validation.validationTarget === "request") {
+                entry.data = undefined;
+            }
             syncSnapshot(entry);
             notify(cacheKey);
         },
@@ -257,11 +299,11 @@ export function createEndpointDataClient() {
             entry.data = data;
             entry.error = null;
             entry.updatedAt = Date.now();
-            entry.validation = {
+            entry.validation = toEndpointResponseValidationResult({
                 data,
                 errors: [],
                 isValid: true,
-            };
+            });
             syncSnapshot(entry);
             notify(cacheKey);
         },
@@ -284,7 +326,7 @@ export function useEndpointDataClient() {
 }
 export function useEndpointQuery(endpoint, request, options = {}) {
     if (endpoint.method !== "GET") {
-        throw new Error("useEndpointQuery only supports GET endpoints in v1.");
+        throw new RestQueryHookUsageError("useEndpointQuery only supports GET endpoints in v1.");
     }
     const defaultClient = useEndpointDataClient();
     const client = asInternalClient(options.client ?? defaultClient);
@@ -328,8 +370,8 @@ export function useEndpointQuery(endpoint, request, options = {}) {
     if (!executeQueryRef.current) {
         executeQueryRef.current = async (force) => {
             const latest = latestRef.current;
-            if (!latest.requestValidation.isValid) {
-                const invalidValidation = latest.requestValidation;
+            if (isInvalidValidationResult(latest.requestValidation)) {
+                const invalidValidation = toEndpointRequestValidationResult(latest.requestValidation);
                 latest.client.__publishValidation(latest.cacheKey, invalidValidation);
                 return invalidValidation;
             }
@@ -371,11 +413,11 @@ export function useEndpointQuery(endpoint, request, options = {}) {
         if (!enabled) {
             return;
         }
-        if (!prepared.requestValidation.isValid) {
+        if (isInvalidValidationResult(prepared.requestValidation)) {
             if (snapshot.validation?.isValid === false) {
                 return;
             }
-            client.__publishValidation(prepared.cacheKey, prepared.requestValidation);
+            client.__publishValidation(prepared.cacheKey, toEndpointRequestValidationResult(prepared.requestValidation));
             return;
         }
         if (snapshot.isFetching) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wp-typia/rest",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "Typed WordPress REST helpers powered by Typia validation",
   "type": "module",
   "main": "dist/index.js",
@@ -62,7 +62,7 @@
     "bun": ">=1.3.11"
   },
   "dependencies": {
-    "@wp-typia/api-client": "^0.4.2",
+    "@wp-typia/api-client": "^0.4.4",
     "@typia/interface": "^12.0.1",
     "@wordpress/api-fetch": "^7.42.0"
   },