@nestia/fetcher 14.0.1 → 14.0.2

package/src/IPropagation.ts

@@ -7,20 +7,21 @@
  *
  * ```typescript
  * type Output = IPropagation<{
- *    200: ISeller.IAuthorized;
- *    400: TypeGuardError.IProps;
- * >};
+ *   200: ISeller.IAuthorized;
+ *   400: TypeGuardError.IProps;
+ * }>;
  *
  * const output: Output = await sdk.sellers.authenticate.join(input);
  * if (output.success) {
- *     // automatically casted to "ISeller.IAuthorized" type
- *     const authorized: ISeller.IAuthorized = output.data;
+ *   // automatically casted to "ISeller.IAuthorized" type
+ *   const authorized: ISeller.IAuthorized = output.data;
  * } else if (output.status === 400) {
- *     // automatically casted to "TypeGuardError.IProps" type
- *     const error: TypeGuardError.IProps = output.data;
+ *   // The unknown-status fallback overlaps numeric statuses. Validate the
+ *   // body before treating it as TypeGuardError.IProps.
+ *   const error: unknown = output.data;
  * } else {
- *     // unknown type when out of pre-defined status codes
- *     const result: unknown = output.data;
+ *   // unknown type when out of pre-defined status codes
+ *   const result: unknown = output.data;
  * }
  * ```
  *
@@ -33,6 +34,10 @@
  * @author Jeongho Nam - https://github.com/samchon
  * @template StatusMap Map of status code and its body data type.
  * @template Success Default success status code.
+ * @evidence contracts/common.md#principled-implementation Each configured status becomes a branch whose success flag is true for configured success statuses, 200 and 201 by default. A false-success fallback with numeric status and unknown data represents unconfigured responses; TypeScript cannot subtract numeric literals from number, so this fallback also overlaps configured failure statuses and status-only narrowing cannot prove their payload shape.
+ * @evidence contracts/common.md#clear-and-simple-design One mapped type indexed into a union, plus the fallback branch.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+ * @evidence contracts/common.md#meaningful-documentation The comment gives an example of narrowing and says which generated SDK option uses the type.
  */
 export type IPropagation<
   StatusMap extends {
@@ -55,6 +60,11 @@ export namespace IPropagation {
    * The special characters like `2XX`, `3XX`, `4XX`, `5XX` are meaning the
    * range of status codes. If `5XX` is specified, it means the status code is
    * in the range of `500` to `599`.
+   *
+   * @evidence contracts/common.md#principled-implementation A status is a number or one of the four range spellings, which is enough to configure both exact and ranged branches.
+   * @evidence contracts/common.md#clear-and-simple-design A single union.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment defines the range spellings.
    */
   export type Status = number | "2XX" | "3XX" | "4XX" | "5XX";
 
@@ -64,6 +74,11 @@ export namespace IPropagation {
    * `IPropagation.IBranch` is a branch type composing `IPropagation` type,
    * which is gathering all possible status codes and their body data types as a
    * union type.
+   *
+   * @evidence contracts/common.md#principled-implementation A branch pairs a literal success flag with the status, the data, and the headers, and turns a range spelling into the union of its integers, so a narrowed status is a number the caller can compare.
+   * @evidence contracts/common.md#clear-and-simple-design One record with a conditional on the status member.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment explains that it is the element of the propagation union.
    */
   export interface IBranch<Success extends boolean, StatusValue, BodyData> {
     success: Success;
@@ -76,7 +91,14 @@ export namespace IPropagation {
     headers: Record<string, string | string[]>;
   }
 
-  /** Range of status codes by the first digit, `"4XX"` for `400` to `499`. */
+  /**
+   * Range of status codes by the first digit, `"4XX"` for `400` to `499`.
+   *
+   * @evidence contracts/common.md#principled-implementation The first-digit spelling maps to the integers from its hundred up to the next hundred, computed by excluding a smaller enumeration from a larger one.
+   * @evidence contracts/common.md#clear-and-simple-design One conditional over the four spellings, using two private helper types.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment gives the range rule with an example.
+   */
   export type StatusRange<T extends "2XX" | "3XX" | "4XX" | "5XX"> =
     T extends "2XX"
       ? IntRange<200, 300>

package/src/NestiaSimulator.ts

@@ -1,7 +1,31 @@
 import { HttpError } from "./HttpError";
 import { join_host_and_path } from "./internal/join_host_and_path";
 
+/**
+ * Request validation for the mockup simulator of a generated SDK.
+ *
+ * A simulated function does not call a server. It validates its input with
+ * typia and, when the input is wrong, throws the `HttpError` with status 400
+ * that the real server would answer with.
+ *
+ * @evidence contracts/common.md#principled-implementation Each validator runs the caller's assertion and converts a readable typia `TypeGuardError` shape into an `HttpError` 400 whose JSON body carries the method, path, expected type and value plus a message naming the failing part. A shared snapshot reads each needed property once; malformed or unreadable shapes rethrow the caller's original value. Payload values must support JSON serialization, whose errors still propagate.
+ * @evidence contracts/common.md#clear-and-simple-design One public entry point, `assert`, returns four validators that differ only in their message, sharing one private conversion; the shape snapshot reader and the error interface are module-private.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Classification checks the readable error structure (method, path, expected type, name, message and stack) rather than its class, then captures the payload value. A value that lacks any of those fields with the expected types, or whose property access throws, is not classified as a type guard failure and is rethrown unchanged; unrelated task errors are neither replaced nor swallowed.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the simulator validates and what it throws.
+ */
 export namespace NestiaSimulator {
+  /**
+   * Route facts the simulator needs to build its 400 error: the host, the path,
+   * and the method.
+   *
+   * `contentType` is the content type of the route's success response, which
+   * the generated code answers with; the simulated 400 is JSON whatever it is.
+   *
+   * @evidence contracts/common.md#principled-implementation The host, path, and method identify the request in the error, and the content type describes the success response of the generated function, which the generated code answers with.
+   * @evidence contracts/common.md#clear-and-simple-design A four-field record with no behavior.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The values are supplied by the generated SDK for its own route.
+   * @evidence contracts/common.md#meaningful-documentation The comment says what each part is used for, with the `contentType` member documenting when it is `null`.
+   */
   export interface IProps {
     host: string;
     path: string;
@@ -15,6 +39,19 @@ export namespace NestiaSimulator {
     contentType: string | null;
   }
 
+  /**
+   * Creates the validators of one simulated route: `param(name)`, `query`,
+   * `body`, and `headers`.
+   *
+   * Each validator takes the closure that performs the typia assertion. A
+   * failed assertion throws an `HttpError` with status 400 and a JSON body; any
+   * other error is rethrown as it is.
+   *
+   * @evidence contracts/common.md#principled-implementation The four validators share the conversion in `validate` and differ in the message they attach, which names the URL parameter or states that the query, body, or headers do not follow the promised type.
+   * @evidence contracts/common.md#clear-and-simple-design One function returning the four validators as an object, so a generated simulator has one import.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The HTTP error is the one the real server returns; nothing is simulated beyond running the assertion.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what it returns and what each validator throws.
+   */
   export const assert = (props: IProps) => {
     return {
       param: param(props),
@@ -54,13 +91,14 @@ export namespace NestiaSimulator {
       )(task);
 
   const validate =
-    (message: (exp: TypeGuardError) => string, path?: string) =>
+    (message: (exp: TypeGuardError) => string) =>
     (props: IProps) =>
     <T>(task: () => T): void => {
       try {
         task();
       } catch (exp) {
-        if (isTypeGuardError(exp))
+        const guard: TypeGuardError | null = readTypeGuardError(exp);
+        if (guard !== null)
           throw new HttpError(
             props.method,
             join_host_and_path(props.host, props.path),
@@ -69,11 +107,11 @@ export namespace NestiaSimulator {
               "Content-Type": "application/json",
             },
             JSON.stringify({
-              method: exp.method,
-              path: path ?? exp.path,
-              expected: exp.expected,
-              value: exp.value,
-              message: message(exp),
+              method: guard.method,
+              path: guard.path,
+              expected: guard.expected,
+              value: guard.value,
+              message: message(guard),
             }),
           );
         throw exp;
@@ -81,13 +119,27 @@ export namespace NestiaSimulator {
     };
 }
 
-const isTypeGuardError = (input: any): input is TypeGuardError =>
-  "string" === typeof input.method &&
-  (undefined === input.path || "string" === typeof input.path) &&
-  "string" === typeof input.expected &&
-  "string" === typeof input.name &&
-  "string" === typeof input.message &&
-  (undefined === input.stack || "string" === typeof input.stack);
+const readTypeGuardError = (input: any): TypeGuardError | null => {
+  if (typeof input !== "object" || input === null) return null;
+  try {
+    const method: unknown = input.method;
+    if (typeof method !== "string") return null;
+    const path: unknown = input.path;
+    if (path !== undefined && typeof path !== "string") return null;
+    const expected: unknown = input.expected;
+    if (typeof expected !== "string") return null;
+    const name: unknown = input.name;
+    if (typeof name !== "string") return null;
+    const message: unknown = input.message;
+    if (typeof message !== "string") return null;
+    const stack: unknown = input.stack;
+    if (stack !== undefined && typeof stack !== "string") return null;
+    const value: unknown = input.value;
+    return { method, path, expected, name, message, stack, value };
+  } catch {
+    return null;
+  }
+};
 
 interface TypeGuardError extends Error {
   method: string;

package/src/PathParameter.ts

@@ -2,6 +2,10 @@
  * The path parameters of a generated SDK function, as its URL carries them.
  *
  * @author Jeongho Nam - https://github.com/samchon
+ * @evidence contracts/common.md#principled-implementation A path parameter is one URL path segment, so the value must be encoded as one segment and must never spell a dot segment, which the URL parser would resolve away.
+ * @evidence contracts/common.md#clear-and-simple-design One namespace with one function, kept apart so both the SDK generator's output and hand-written callers use the same rule.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The rule applies to every value; no parameter name is special-cased.
+ * @evidence contracts/common.md#meaningful-documentation The comment states the purpose of the namespace and the function documents the dot-segment refusal.
  */
 export namespace PathParameter {
   /**
@@ -18,6 +22,10 @@ export namespace PathParameter {
    * @param value Value of the parameter
    * @returns The URI-encoded segment
    * @throws Error when the value is `.` or `..`
+   * @evidence contracts/common.md#principled-implementation encodeURIComponent produces a single segment for well-formed Unicode text and throws URIError for unpaired surrogates; nullish input becomes the text null. The encoded text . or .. is refused because the WHATWG URL parser treats it and its percent-encoded spelling as a dot segment.
+   * @evidence contracts/common.md#clear-and-simple-design One conversion and one guard, with the reason for the guard stated in the comment.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The guard prevents a request from silently reaching a different route, so it is a correctness check rather than a workaround for a test.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the encoding, the nullish rule, the refused segments, their reason, and the thrown error.
    */
   export const encode = (name: string, value: unknown): string => {
     const encoded: string = encodeURIComponent(

package/src/PlainFetcher.ts

@@ -8,15 +8,19 @@ import { FetcherBase } from "./internal/FetcherBase";
  *
  * `PlainFetcher` is a utility class designed for SDK functions generated by
  * [`@nestia/sdk`](https://nestia.io/docs/sdk/sdk), interacting with the remote
- * HTTP sever API. In other words, this is a collection of dedicated `fetch()`
+ * HTTP server API. In other words, this is a collection of dedicated `fetch()`
  * functions for `@nestia/sdk`.
  *
  * For reference, `PlainFetcher` class does not encrypt or decrypt the body data
  * at all. It just delivers plain data without any post processing. If you've
  * defined a controller method through `@EncryptedRoute` or `@EncryptedBody`
- * decorator, then {@liink EncryptedFetcher} class would be used instead.
+ * decorator, then {@link EncryptedFetcher} class would be used instead.
  *
  * @author Jeongho Nam - https://github.com/samchon
+ * @evidence contracts/common.md#principled-implementation The codecs preserve transformed bodies, while FetcherBase owns JSON, form and binary handling. Encrypted metadata is refused before transport. The shared pipeline removes caller Content-Type case-insensitively so multipart boundaries remain fetch-owned, normalizes only host/path separator boundaries, and classifies 200, 201 and the route's configured success status.
+ * @evidence contracts/common.md#clear-and-simple-design Two public operations that mirror `EncryptedFetcher`, with the encryption guard as their only own logic.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The refusal is the contract with the generated SDK, which chooses `EncryptedFetcher` for encrypted routes; no route or header is special-cased.
+ * @evidence contracts/common.md#meaningful-documentation The namespace prose says when the generated SDK uses this fetcher and that it does no encryption.
  */
 export namespace PlainFetcher {
   /**
@@ -25,6 +29,10 @@ export namespace PlainFetcher {
    * @param connection Connection information for the remote HTTP server
    * @param route Route information about the target API
    * @returns Nothing because of `HEAD` method
+   * @evidence contracts/common.md#principled-implementation The overloads narrow arguments by method; the implementation refuses encryption metadata and delegates to FetcherBase.request. Failed statuses become HttpError with their original text, successful HEAD has no data, and binary successes transfer response.body unchanged or create a synchronously closed empty stream if absent. Stream consumption and cancellation belong to the caller.
+   * @evidence contracts/common.md#clear-and-simple-design One guard and one delegation, with the overloads only splitting the types.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The guard follows the route metadata, not a path or a connection.
+   * @evidence contracts/common.md#meaningful-documentation Each overload documents its parameters and return value.
    */
   export function fetch(
     connection: IConnection,
@@ -74,19 +82,56 @@ export namespace PlainFetcher {
     })(connection, route, input, stringify);
   }
 
-  export function propagate<Output extends IPropagation<any, any>>(
+  /**
+   * Fetch function that returns every response as an {@link IPropagation}.
+   *
+   * An HTTP failure status is returned as a failed branch instead of being
+   * thrown. A route that declares an encrypted body and a transport failure
+   * still throw. The output must describe numeric status branches with boolean
+   * success and string or string-array headers; its data type remains
+   * caller-owned.
+   *
+   * @evidence contracts/common.md#principled-implementation The implementation refuses an encrypted route and delegates to `FetcherBase.propagate`. Its structural branch constraint accepts numeric literal successes, numeric range failures and unknown-status fallback without instantiating a status map with any, while requiring boolean success and actual numeric status/header shapes.
+   * @evidence contracts/common.md#clear-and-simple-design One guard and one delegation, with the overloads only splitting the types.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The function adds no status-specific branch: the success flag comes from the status rules in `FetcherBase`.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the returned union carries and which failures still throw.
+   */
+  export function propagate<
+    Output extends {
+      success: boolean;
+      status: number;
+      headers: Record<string, string | string[]>;
+      data: unknown;
+    },
+  >(
     connection: IConnection,
     route: IFetchRoute<"GET" | "HEAD">,
   ): Promise<Output>;
 
-  export function propagate<Input, Output extends IPropagation<any, any>>(
+  export function propagate<
+    Input,
+    Output extends {
+      success: boolean;
+      status: number;
+      headers: Record<string, string | string[]>;
+      data: unknown;
+    },
+  >(
     connection: IConnection,
     route: IFetchRoute<"DELETE" | "GET" | "HEAD" | "PATCH" | "POST" | "PUT">,
     input?: Input,
     stringify?: (input: Input) => string,
   ): Promise<Output>;
 
-  export async function propagate<Input, Output extends IPropagation<any, any>>(
+  export async function propagate<
+    Input,
+    Output extends {
+      success: boolean;
+      status: number;
+      headers: Record<string, string | string[]>;
+      data: unknown;
+    },
+  >(
     connection: IConnection,
     route: IFetchRoute<"DELETE" | "GET" | "HEAD" | "PATCH" | "POST" | "PUT">,
     input?: Input,

package/src/internal/FetcherBase.ts

@@ -6,20 +6,41 @@ import { IPropagation } from "../IPropagation";
 import { is_binary_response_content_type } from "./is_binary_response_content_type";
 import { join_host_and_path, normalize_route_path } from "./join_host_and_path";
 
-/** @internal */
+/**
+ * Shared transport pipeline with injected body codecs.
+ *
+ * @internal
+ */
 export namespace FetcherBase {
+  /**
+   * Body transformations supplied by the plain or encrypted fetcher.
+   *
+   * The encode input has already undergone the route's body transformation.
+   * Header records describe the corresponding request or response.
+   */
   export interface IProps {
+    /** Fetcher name used in request configuration errors. */
     className: string;
+
+    /** Convert a transformed request body into its wire representation. */
     encode: (
       input: any,
       headers: Record<string, IConnection.HeaderValue | undefined>,
     ) => string;
+
+    /** Decode a textual response not handled by a structured media branch. */
     decode: (
       input: string,
       headers: Record<string, IConnection.HeaderValue | undefined>,
     ) => any;
   }
 
+  /**
+   * Return successful response data and throw HttpError for a failed status.
+   *
+   * Binary response streams transfer to the caller for reading or cancellation;
+   * an absent binary body is represented by a closed empty stream.
+   */
   export const request =
     (props: IProps) =>
     async <Input, Output>(
@@ -45,6 +66,13 @@ export namespace FetcherBase {
       return result.data as Output;
     };
 
+  /**
+   * Return the classified HTTP response, including failed status payloads.
+   *
+   * Failed JSON responses are parsed when readable; malformed JSON remains
+   * text. Transport and successful-body decoding errors still reject. Binary
+   * response streams transfer to the caller for consumption or cancellation.
+   */
   export const propagate =
     (props: IProps) =>
     async <Input>(
@@ -55,7 +83,15 @@ export namespace FetcherBase {
     ): Promise<IPropagation<any, any>> =>
       _Propagate("propagate")(props)(connection, route, input, stringify);
 
-  /** @internal */
+  /**
+   * Executes one request and transfers binary stream ownership to its caller.
+   *
+   * A null successful binary body has no producer or bytes, so its replacement
+   * stream must start closed. Actual response streams retain their identity;
+   * reading and cancellation remain the caller's responsibility.
+   *
+   * @internal
+   */
   const _Propagate =
     (method: string) =>
     (props: IProps) =>
@@ -176,14 +212,16 @@ export namespace FetcherBase {
             );
             result.data = route.parseQuery ? route.parseQuery(query) : query;
           } else if (is_binary_response_content_type(route.response?.type))
-            result.data = response.body ?? new ReadableStream<Uint8Array>();
+            result.data =
+              response.body ??
+              new ReadableStream<Uint8Array>({
+                start: (controller) => controller.close(),
+              });
           else
             result.data = props.decode(await response.text(), result.headers);
         }
         event.output = result.data;
         return result;
-      } catch (exp) {
-        throw exp;
       } finally {
         event.completed_at = new Date();
         if (connection.logger)
@@ -215,7 +253,7 @@ const request_form_data_body = (input: Record<string, any>): FormData => {
     else encoded.append(key, value);
   };
   for (const [key, value] of Object.entries(input))
-    if (Array.isArray(value)) value.map(append(key));
+    if (Array.isArray(value)) value.forEach(append(key));
     else append(key)(value);
   return encoded;
 };

package/src/internal/is_binary_response_content_type.ts

@@ -1,3 +1,15 @@
+/**
+ * Reports whether a response content type carries a binary body.
+ *
+ * The parameters of the type (`; charset=...`) and its case are ignored. Image,
+ * video, and audio types, `application/octet-stream`, and `application/pdf` are
+ * binary, and the fetcher returns their body as a stream instead of text.
+ *
+ * @evidence contracts/common.md#principled-implementation The media type is the text before the first `;`, trimmed and lower-cased as HTTP defines, and is matched against the binary families and two exact types, so a parameter or a case variant cannot change the decision.
+ * @evidence contracts/common.md#clear-and-simple-design One predicate with a type guard, so the caller can narrow the route's content type.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The rule is a list of media-type families from the HTTP registry rather than a list of routes.
+ * @evidence contracts/common.md#meaningful-documentation The comment states the normalization and the binary types.
+ */
 export const is_binary_response_content_type = (
   input: string | null | undefined,
 ): input is string => {