@wp-typia/rest 0.3.6 → 0.3.8

package/README.md

@@ -15,26 +15,42 @@ 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`.
 
-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:
+## Export contract
+
+- `@wp-typia/rest`
+  Canonical convenience surface. It intentionally combines the transport helper
+  layer and the HTTP decoder helpers.
+- `@wp-typia/rest/client`
+  Focused transport surface for endpoint creation, validated fetch helpers,
+  WordPress REST route resolution, validation utilities, and named runtime
+  errors.
+- `@wp-typia/rest/http`
+  Focused decoder surface for query/header/parameter decoders plus the shared
+  validation helper utilities they return.
+- `@wp-typia/rest/react`
+  React-only cache and hook layer.
+
+Prefer the root entry when you want the shortest import path. Reach for
+`./client` or `./http` when a narrower surface makes the consumer boundary
+clearer. Query and mutation hooks still live on 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
@@ -42,22 +58,32 @@ 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/client';
 
-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/http';
 
 const decodeQuery = createQueryDecoder(
-  typia.http.createValidateQuery<MyQuery>()
+  typia.http.createValidateQuery<MyQuery>(),
 );
 ```
 
@@ -76,17 +102,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(),
       },
     },
   }),
@@ -97,7 +120,7 @@ const mutation = useEndpointMutation(writeStateEndpoint, {
   resolveCallOptions: () => ({
     requestOptions: {
       headers: {
-        "X-WP-Nonce": resolveRestNonce(),
+        'X-WP-Nonce': resolveRestNonce(),
       },
     },
   }),

package/dist/client.d.ts

@@ -3,6 +3,7 @@ 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 { ApiClientConfigurationError, RestConfigurationError, RestRootResolutionError, RestValidationAssertionError, WpTypiaContractError, WpTypiaValidationAssertionError, } from "./errors.js";
 export type { EndpointRequestValidationResult, EndpointResponseValidationResult, EndpointValidationResult, EndpointValidationTarget, } from "@wp-typia/api-client";
 export interface ValidatedFetch<T> {
     assertFetch(options: APIFetchOptions): Promise<T>;

package/dist/client.js

@@ -1,6 +1,8 @@
 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";
+export { ApiClientConfigurationError, RestConfigurationError, RestRootResolutionError, RestValidationAssertionError, WpTypiaContractError, WpTypiaValidationAssertionError, } from "./errors.js";
 function getDefaultRestRoot() {
     if (typeof window !== "undefined") {
         const wpApiSettings = window.wpApiSettings;
@@ -15,7 +17,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 +52,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 +156,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.");
             }

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/http.d.ts

@@ -1,5 +1,7 @@
 import type { IValidation } from "@typia/interface";
-import { type ValidationLike, type ValidationResult } from "./client.js";
+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 declare function createQueryDecoder<T extends object>(validate?: (input: string | URLSearchParams) => ValidationLike<T> | IValidation<T>): (input: unknown) => ValidationResult<T>;
 export declare function createHeadersDecoder<T extends object>(validate?: (input: Record<string, string | string[] | undefined>) => ValidationLike<T> | IValidation<T>): (input: unknown) => ValidationResult<T>;
 export declare function createParameterDecoder<T extends string | number | boolean | bigint | null>(): (input: string) => T;

package/dist/http.js

@@ -1,4 +1,5 @@
-import { toValidationResult, } from "./client.js";
+import { toValidationResult, } from "./internal/runtime-primitives.js";
+export { isValidationResult, normalizeValidationError, toValidationResult, } from "./internal/runtime-primitives.js";
 function toHeadersRecord(input) {
     if (input instanceof Headers) {
         const record = {};

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 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

@@ -56,7 +56,7 @@ export interface UseEndpointMutationResult<Req, Res> {
     validation: EndpointValidationResult<Req, Res> | null;
 }
 export interface EndpointDataProviderProps {
-    children?: unknown;
+    children?: Parameters<typeof createElement>[2];
     client: EndpointDataClient;
 }
 export declare function createEndpointDataClient(): EndpointDataClient;

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,
@@ -126,6 +127,20 @@ function isEntryStale(entry, staleTime) {
 function asInternalClient(client) {
     return client;
 }
+function castEndpointValidationResult(validation) {
+    return validation;
+}
+function castEndpointValidationPromise(promise) {
+    return promise;
+}
+function selectEndpointData(data, select) {
+    if (select) {
+        return select(data);
+    }
+    // The default selector is identity, but TypeScript cannot express that when
+    // Selected is an unconstrained generic chosen by the caller.
+    return data;
+}
 function isInvalidValidationResult(validation) {
     return validation.isValid === false;
 }
@@ -248,11 +263,11 @@ export function createEndpointDataClient() {
         async __runQuery(cacheKey, execute, { force = false, staleTime }) {
             const entry = getOrCreateEntry(entries, cacheKey);
             if (entry.promise) {
-                return entry.promise;
+                return castEndpointValidationPromise(entry.promise);
             }
             if (!force) {
                 if (!isEntryStale(entry, staleTime) && entry.validation) {
-                    return entry.validation;
+                    return castEndpointValidationResult(entry.validation);
                 }
             }
             entry.error = null;
@@ -288,7 +303,7 @@ export function createEndpointDataClient() {
                 notify(cacheKey);
             });
             entry.promise = promise;
-            return promise;
+            return castEndpointValidationPromise(promise);
         },
         __seedData(cacheKey, data) {
             const entry = getOrCreateEntry(entries, cacheKey);
@@ -318,14 +333,16 @@ export function createEndpointDataClient() {
 }
 const defaultEndpointDataClient = createEndpointDataClient();
 export function EndpointDataProvider({ children, client, }) {
-    return createElement(EndpointDataClientContext.Provider, { value: client }, children);
+    return children === undefined
+        ? createElement(EndpointDataClientContext.Provider, { value: client })
+        : 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.");
+        throw new RestQueryHookUsageError("useEndpointQuery only supports GET endpoints in v1.");
     }
     const defaultClient = useEndpointDataClient();
     const client = asInternalClient(options.client ?? defaultClient);
@@ -381,9 +398,7 @@ export function useEndpointQuery(endpoint, request, options = {}) {
                     requestOptions: callOptions?.requestOptions,
                 }), { force, staleTime: latest.staleTime });
                 if (validation.isValid) {
-                    const selected = latest.select !== undefined
-                        ? latest.select(validation.data)
-                        : validation.data;
+                    const selected = selectEndpointData(validation.data, latest.select);
                     await latest.onSuccess?.(selected, validation);
                 }
                 return validation;
@@ -458,9 +473,7 @@ export function useEndpointQuery(endpoint, request, options = {}) {
         if (rawData === undefined) {
             return undefined;
         }
-        return select !== undefined
-            ? select(rawData)
-            : rawData;
+        return selectEndpointData(rawData, select);
     }, [initialData, select, snapshot.data, snapshot.validation]);
     return {
         data,
@@ -469,7 +482,9 @@ export function useEndpointQuery(endpoint, request, options = {}) {
         isLoading: snapshot.isFetching &&
             data === undefined,
         refetch,
-        validation: snapshot.validation,
+        validation: snapshot.validation === null
+            ? null
+            : castEndpointValidationResult(snapshot.validation),
     };
 }
 export function useEndpointMutation(endpoint, options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wp-typia/rest",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "Typed WordPress REST helpers powered by Typia validation",
   "type": "module",
   "main": "dist/index.js",
@@ -12,14 +12,14 @@
       "default": "./dist/index.js"
     },
     "./client": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "default": "./dist/index.js"
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js",
+      "default": "./dist/client.js"
     },
     "./http": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "default": "./dist/index.js"
+      "types": "./dist/http.d.ts",
+      "import": "./dist/http.js",
+      "default": "./dist/http.js"
     },
     "./react": {
       "types": "./dist/react.d.ts",
@@ -62,7 +62,7 @@
     "bun": ">=1.3.11"
   },
   "dependencies": {
-    "@wp-typia/api-client": "^0.4.3",
+    "@wp-typia/api-client": "^0.4.4",
     "@typia/interface": "^12.0.1",
     "@wordpress/api-fetch": "^7.42.0"
   },