@wp-typia/rest 0.2.0

package/README.md

@@ -0,0 +1,46 @@
+# `@wp-typia/rest`
+
+Typed WordPress REST helpers for `wp-typia`.
+
+This package focuses on:
+
+- validated `apiFetch` wrappers
+- typed endpoint helpers
+- canonical WordPress REST route URL resolution
+- 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.
+
+Typical usage:
+
+```ts
+import { callEndpoint, createEndpoint } from "@wp-typia/rest";
+
+const endpoint = createEndpoint<MyRequest, MyResponse>({
+  method: "POST",
+  path: "/my-namespace/v1/demo",
+  validateRequest: validators.request,
+  validateResponse: validators.response,
+});
+
+const result = await callEndpoint(endpoint, { title: "Hello" });
+```
+
+If you need a canonical REST URL for a route path, use:
+
+```ts
+import { resolveRestRouteUrl } from "@wp-typia/rest";
+
+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";
+
+const decodeQuery = createQueryDecoder(
+  typia.http.createValidateQuery<MyQuery>()
+);
+```

package/dist/client.d.ts

@@ -0,0 +1,45 @@
+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;
+};
+export interface ValidatedFetch<T> {
+    assertFetch(options: APIFetchOptions): Promise<T>;
+    fetch(options: APIFetchOptions): Promise<ValidationResult<T>>;
+    fetchWithResponse(options: APIFetchOptions<false>): Promise<{
+        response: Response;
+        validation: ValidationResult<T>;
+    }>;
+    isFetch(options: APIFetchOptions): Promise<T | null>;
+}
+export interface ApiEndpoint<Req, Res> {
+    buildRequestOptions?: (request: Req) => Partial<APIFetchOptions>;
+    method: "DELETE" | "GET" | "PATCH" | "POST" | "PUT";
+    path: string;
+    validateRequest: (input: unknown) => ValidationResult<Req>;
+    validateResponse: (input: unknown) => ValidationResult<Res>;
+}
+export interface EndpointCallOptions {
+    fetchFn?: ApiFetch;
+    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

@@ -0,0 +1,285 @@
+function getDefaultRestRoot() {
+    if (typeof window !== "undefined") {
+        const wpApiSettings = window.wpApiSettings;
+        if (typeof wpApiSettings?.root === "string" && wpApiSettings.root.length > 0) {
+            return wpApiSettings.root;
+        }
+        if (typeof document !== "undefined") {
+            const apiLink = document.querySelector('link[rel="https://api.w.org/"]');
+            const href = apiLink?.getAttribute("href");
+            if (typeof href === "string" && href.length > 0) {
+                return new URL(href, window.location.origin).toString();
+            }
+        }
+    }
+    throw new Error("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);
+    const [rawPath, rawQuery = ""] = pathWithQuery.split("?", 2);
+    const normalizedRoute = `/${rawPath.replace(/^\/+/, "").replace(/\/+$/, "")}/`;
+    const queryParams = new URLSearchParams(rawQuery);
+    const resolvedRoot = typeof window !== "undefined" ? new URL(root, window.location.origin) : new URL(root);
+    if (resolvedRoot.searchParams.has("rest_route")) {
+        resolvedRoot.searchParams.set("rest_route", normalizedRoute);
+        for (const [key, value] of queryParams) {
+            resolvedRoot.searchParams.append(key, value);
+        }
+        if (hash) {
+            resolvedRoot.hash = hash;
+        }
+        return resolvedRoot.toString();
+    }
+    const basePath = resolvedRoot.pathname.endsWith("/") ? resolvedRoot.pathname : `${resolvedRoot.pathname}/`;
+    resolvedRoot.pathname = `${basePath}${normalizedRoute.slice(1)}`;
+    for (const [key, value] of queryParams) {
+        resolvedRoot.searchParams.append(key, value);
+    }
+    if (hash) {
+        resolvedRoot.hash = hash;
+    }
+    return resolvedRoot.toString();
+}
+function resolveFetchUrl(options) {
+    if (typeof options.url === "string" && options.url.length > 0) {
+        return options.url;
+    }
+    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.");
+}
+async function defaultFetch(options) {
+    const response = await fetch(resolveFetchUrl(options), {
+        body: options.body,
+        credentials: "same-origin",
+        headers: options.headers,
+        method: options.method ?? "GET",
+    });
+    if (options.parse === false) {
+        return response;
+    }
+    if (response.status === 204) {
+        return undefined;
+    }
+    const text = await response.text();
+    if (!text) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+async function parseResponsePayload(response) {
+    if (response.status === 204) {
+        return undefined;
+    }
+    const text = await response.text();
+    if (!text) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        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 "";
+    }
+    if (request instanceof URLSearchParams) {
+        return request.toString();
+    }
+    if (!isPlainObject(request)) {
+        throw new Error("GET/DELETE endpoint requests must be plain objects or URLSearchParams.");
+    }
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(request)) {
+        if (value === undefined || value === null) {
+            continue;
+        }
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                params.append(key, String(item));
+            }
+            continue;
+        }
+        params.set(key, String(value));
+    }
+    return params.toString();
+}
+function joinPathWithQuery(path, query) {
+    if (!query) {
+        return path;
+    }
+    return path.includes("?") ? `${path}&${query}` : `${path}?${query}`;
+}
+function joinUrlWithQuery(url, query) {
+    if (!query) {
+        return url;
+    }
+    const nextUrl = new URL(url, typeof window !== "undefined" ? window.location.origin : "http://localhost");
+    for (const [key, value] of new URLSearchParams(query)) {
+        nextUrl.searchParams.append(key, value);
+    }
+    return nextUrl.toString();
+}
+function mergeHeaderInputs(baseHeaders, requestHeaders) {
+    if (!baseHeaders && !requestHeaders) {
+        return undefined;
+    }
+    const mergedHeaders = new Headers(baseHeaders);
+    const nextHeaders = new Headers(requestHeaders);
+    for (const [key, value] of nextHeaders.entries()) {
+        mergedHeaders.set(key, value);
+    }
+    return Object.fromEntries(mergedHeaders.entries());
+}
+function buildEndpointFetchOptions(endpoint, request) {
+    const baseOptions = endpoint.buildRequestOptions?.(request) ?? {};
+    if (endpoint.method === "GET" || endpoint.method === "DELETE") {
+        const query = encodeGetLikeRequest(request);
+        const resolvedUrl = baseOptions.url ? joinUrlWithQuery(baseOptions.url, query) : undefined;
+        return {
+            ...baseOptions,
+            method: endpoint.method,
+            ...(resolvedUrl ? { url: resolvedUrl, path: undefined } : {
+                path: joinPathWithQuery(baseOptions.path ?? endpoint.path, query),
+            }),
+        };
+    }
+    if (isFormDataLike(request)) {
+        return {
+            ...baseOptions,
+            body: request,
+            method: endpoint.method,
+            ...(baseOptions.url
+                ? {
+                    url: baseOptions.url,
+                    path: undefined,
+                }
+                : {
+                    path: baseOptions.path ?? endpoint.path,
+                }),
+        };
+    }
+    return {
+        ...baseOptions,
+        body: typeof request === "string" ? request : JSON.stringify(request),
+        headers: mergeHeaderInputs({ "Content-Type": "application/json" }, baseOptions.headers),
+        method: endpoint.method,
+        ...(baseOptions.url
+            ? {
+                url: baseOptions.url,
+                path: undefined,
+            }
+            : {
+                path: baseOptions.path ?? endpoint.path,
+            }),
+    };
+}
+function mergeFetchOptions(baseOptions, requestOptions) {
+    if (!requestOptions) {
+        return baseOptions;
+    }
+    const { headers: requestHeaders, ...transportOptions } = requestOptions;
+    return {
+        ...baseOptions,
+        ...transportOptions,
+        headers: mergeHeaderInputs(baseOptions.headers, requestHeaders),
+    };
+}
+export function createValidatedFetch(validator, fetchFn = defaultFetch) {
+    return {
+        async fetchWithResponse(options) {
+            const response = await fetchFn({
+                ...options,
+                parse: false,
+            });
+            const payload = await parseResponsePayload(response.clone());
+            return {
+                response,
+                validation: toValidationResult(validator(payload)),
+            };
+        },
+        async fetch(options) {
+            if (options.parse === false) {
+                const { validation } = await this.fetchWithResponse(options);
+                return validation;
+            }
+            const payload = await fetchFn(options);
+            return toValidationResult(validator(payload));
+        },
+        async assertFetch(options) {
+            const result = await this.fetch(options);
+            if (!result.isValid) {
+                throw new Error(result.errors[0]
+                    ? `${result.errors[0].path}: ${result.errors[0].expected}`
+                    : "REST response validation failed.");
+            }
+            return result.data;
+        },
+        async isFetch(options) {
+            const result = await this.fetch(options);
+            return result.isValid ? result.data : null;
+        },
+    };
+}
+export function createEndpoint(config) {
+    return config;
+}
+export async function callEndpoint(endpoint, request, { fetchFn = defaultFetch, requestOptions } = {}) {
+    const requestValidation = endpoint.validateRequest(request);
+    if (!requestValidation.isValid) {
+        return requestValidation;
+    }
+    const payload = await fetchFn(mergeFetchOptions(buildEndpointFetchOptions(endpoint, request), requestOptions));
+    return endpoint.validateResponse(payload);
+}

package/dist/http.d.ts

@@ -0,0 +1,5 @@
+import type { IValidation } from "@typia/interface";
+import { type ValidationLike, type ValidationResult } from "./client.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

@@ -0,0 +1,99 @@
+import { toValidationResult, } from "./client.js";
+function toHeadersRecord(input) {
+    if (input instanceof Headers) {
+        const record = {};
+        input.forEach((value, key) => {
+            record[key] = value;
+        });
+        return record;
+    }
+    if (input !== null && typeof input === "object" && !Array.isArray(input)) {
+        return input;
+    }
+    return {};
+}
+function toQueryInput(input) {
+    if (typeof input === "string" || input instanceof URLSearchParams) {
+        return input;
+    }
+    if (input !== null && typeof input === "object" && !Array.isArray(input)) {
+        const params = new URLSearchParams();
+        for (const [key, value] of Object.entries(input)) {
+            if (value === undefined || value === null) {
+                continue;
+            }
+            if (Array.isArray(value)) {
+                for (const item of value) {
+                    params.append(key, String(item));
+                }
+                continue;
+            }
+            params.set(key, String(value));
+        }
+        return params;
+    }
+    return "";
+}
+function toQueryRecord(input) {
+    const params = typeof input === "string" ? new URLSearchParams(input) : input;
+    return Object.fromEntries(params.entries());
+}
+export function createQueryDecoder(validate) {
+    return (input) => {
+        const queryInput = toQueryInput(input);
+        if (validate) {
+            return toValidationResult(validate(queryInput));
+        }
+        return {
+            data: toQueryRecord(queryInput),
+            errors: [],
+            isValid: true,
+        };
+    };
+}
+export function createHeadersDecoder(validate) {
+    return (input) => {
+        const headersRecord = toHeadersRecord(input);
+        if (validate) {
+            return toValidationResult(validate(headersRecord));
+        }
+        return {
+            data: headersRecord,
+            errors: [],
+            isValid: true,
+        };
+    };
+}
+function decodePrimitiveParameter(input) {
+    if (input === "null") {
+        return null;
+    }
+    if (input === "true") {
+        return true;
+    }
+    if (input === "false") {
+        return false;
+    }
+    if (/^-?\d+$/.test(input)) {
+        const numericValue = Number(input);
+        if (Number.isSafeInteger(numericValue)) {
+            return numericValue;
+        }
+        try {
+            return BigInt(input);
+        }
+        catch {
+            return input;
+        }
+    }
+    if (/^-?(?:\d+\.\d+|\d+\.|\.\d+)$/.test(input)) {
+        const numericValue = Number(input);
+        if (!Number.isNaN(numericValue)) {
+            return numericValue;
+        }
+    }
+    return input;
+}
+export function createParameterDecoder() {
+    return ((input) => decodePrimitiveParameter(input));
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { createEndpoint, createValidatedFetch, callEndpoint, isValidationResult, normalizeValidationError, resolveRestRouteUrl, toValidationResult, type ApiEndpoint, type EndpointCallOptions, type ValidatedFetch, type ValidationResult, type ValidationError, type ValidationLike, } from "./client.js";
+export { createHeadersDecoder, createParameterDecoder, createQueryDecoder, } from "./http.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createEndpoint, createValidatedFetch, callEndpoint, isValidationResult, normalizeValidationError, resolveRestRouteUrl, toValidationResult, } from "./client.js";
+export { createHeadersDecoder, createParameterDecoder, createQueryDecoder, } from "./http.js";

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@wp-typia/rest",
+  "version": "0.2.0",
+  "description": "Typed WordPress REST helpers powered by Typia validation",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./http": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "package.json"
+  ],
+  "scripts": {
+    "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"
+  },
+  "author": "imjlk",
+  "license": "GPL-2.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/imjlk/wp-typia.git",
+    "directory": "packages/wp-typia-rest"
+  },
+  "bugs": {
+    "url": "https://github.com/imjlk/wp-typia/issues"
+  },
+  "homepage": "https://github.com/imjlk/wp-typia/tree/main/packages/wp-typia-rest#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "npm": ">=10.0.0",
+    "bun": ">=1.3.10"
+  },
+  "dependencies": {
+    "@typia/interface": "^12.0.1",
+    "@wordpress/api-fetch": "^7.42.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.2"
+  }
+}