@nestia/fetcher 14.0.0 → 14.0.2

package/lib/internal/is_binary_response_content_type.mjs

@@ -1,4 +1,16 @@
 //#region src/internal/is_binary_response_content_type.ts
+/**
+* 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.
+*/
 const is_binary_response_content_type = (input) => {
 	if (typeof input !== "string") return false;
 	const value = input.split(";")[0].trim().toLowerCase();

package/lib/internal/is_binary_response_content_type.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"is_binary_response_content_type.mjs","names":[],"sources":["../../src/internal/is_binary_response_content_type.ts"],"sourcesContent":["export const is_binary_response_content_type = (\n  input: string | null | undefined,\n): input is string => {\n  if (typeof input !== \"string\") return false;\n\n  const value: string = input.split(\";\")[0]!.trim().toLowerCase();\n  return (\n    value.startsWith(\"image/\") ||\n    value.startsWith(\"video/\") ||\n    value.startsWith(\"audio/\") ||\n    value === \"application/octet-stream\" ||\n    value === \"application/pdf\"\n  );\n};\n"],"mappings":";AAAA,MAAa,mCACX,UACoB;CACpB,IAAI,OAAO,UAAU,UAAU,OAAO;CAEtC,MAAM,QAAgB,MAAM,MAAM,GAAG,CAAC,CAAC,EAAE,CAAE,KAAK,CAAC,CAAC,YAAY;CAC9D,OACE,MAAM,WAAW,QAAQ,KACzB,MAAM,WAAW,QAAQ,KACzB,MAAM,WAAW,QAAQ,KACzB,UAAU,8BACV,UAAU;AAEd"}
+{"version":3,"file":"is_binary_response_content_type.mjs","names":[],"sources":["../../src/internal/is_binary_response_content_type.ts"],"sourcesContent":["/**\n * Reports whether a response content type carries a binary body.\n *\n * The parameters of the type (`; charset=...`) and its case are ignored. Image,\n * video, and audio types, `application/octet-stream`, and `application/pdf` are\n * binary, and the fetcher returns their body as a stream instead of text.\n *\n * @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.\n * @evidence contracts/common.md#clear-and-simple-design One predicate with a type guard, so the caller can narrow the route's content type.\n * @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.\n * @evidence contracts/common.md#meaningful-documentation The comment states the normalization and the binary types.\n */\nexport const is_binary_response_content_type = (\n  input: string | null | undefined,\n): input is string => {\n  if (typeof input !== \"string\") return false;\n\n  const value: string = input.split(\";\")[0]!.trim().toLowerCase();\n  return (\n    value.startsWith(\"image/\") ||\n    value.startsWith(\"video/\") ||\n    value.startsWith(\"audio/\") ||\n    value === \"application/octet-stream\" ||\n    value === \"application/pdf\"\n  );\n};\n"],"mappings":";;;;;;;;;;;;;AAYA,MAAa,mCACX,UACoB;CACpB,IAAI,OAAO,UAAU,UAAU,OAAO;CAEtC,MAAM,QAAgB,MAAM,MAAM,GAAG,CAAC,CAAC,EAAE,CAAE,KAAK,CAAC,CAAC,YAAY;CAC9D,OACE,MAAM,WAAW,QAAQ,KACzB,MAAM,WAAW,QAAQ,KACzB,MAAM,WAAW,QAAQ,KACzB,UAAU,8BACV,UAAU;AAEd"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestia/fetcher",
-  "version": "14.0.0",
+  "version": "14.0.2",
   "description": "Fetcher library of Nestia SDK",
   "main": "lib/index.js",
   "exports": {
@@ -56,8 +56,9 @@
     "access": "public"
   },
   "scripts": {
-    "build": "rimraf lib && ttsc && rolldown -c && node ../../deploy/verify-package-exports.cjs --require-main --esm",
-    "dev": "rimraf lib && ttsc --watch"
+    "build": "rimraf lib && ttsc && rolldown -c",
+    "dev": "rimraf lib && ttsc --watch",
+    "evidence": "evidence"
   },
   "types": "lib/index.d.ts"
 }

package/src/AesPkcs5.ts

@@ -1,14 +1,23 @@
 import crypto from "crypto";
 
 /**
- * Utility class for the AES-128/256 encryption.
+ * Utilities for AES-CBC encryption.
  *
- * - AES-128/256
+ * - AES-128/192/256
  * - CBC mode
  * - PKCS#5 Padding
  * - Base64 Encoding
  *
+ * The key and the initializer vector are strings that Node reads as UTF-8
+ * bytes. The variant is chosen by the key's byte length: 16, 24, and 32 bytes
+ * select AES-128, AES-192, and AES-256, and any other length is refused by the
+ * cipher.
+ *
  * @author Jeongho Nam - https://github.com/samchon
+ * @evidence contracts/common.md#principled-implementation The functions call Node's `createCipheriv` and `createDecipheriv` with AES in CBC mode, whose default padding is PKCS#5/PKCS#7, and exchange base64 text; the variant is derived from the key's UTF-8 byte length, which is the length Node actually reads, so a key of 16, 24, or 32 bytes selects AES-128, AES-192, or AES-256 and any other length is refused by the cipher. CBC carries no authentication tag, so the format offers confidentiality without integrity; the mode and encoding are fixed by the wire format `@nestia/core`'s encrypted decorators use, so this namespace cannot change them alone.
+ * @evidence contracts/common.md#clear-and-simple-design Two functions with the same three inputs and no state; the variant selection is one expression in each because the two directions share nothing else.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The primitives are the platform's crypto module with no custom cipher, padding, or key derivation; nothing is hardcoded to a key or an initializer vector.
+ * @evidence contracts/common.md#meaningful-documentation The comment names the algorithm, the mode, the padding, and the encoding, and states how the key length selects the variant.
  */
 export namespace AesPkcs5 {
   /**
@@ -18,9 +27,13 @@ export namespace AesPkcs5 {
    * @param key Key value of the encryption.
    * @param iv Initializer Vector for the encryption
    * @returns Encrypted data
+   * @evidence contracts/common.md#principled-implementation The plain text is read as UTF-8, encrypted in CBC mode with the key and the initializer vector, and emitted as base64 by concatenating the update and final outputs, so the result decrypts to the same text with the same key and vector.
+   * @evidence contracts/common.md#clear-and-simple-design A single expression over one cipher object, with the cipher name derived from the key in the line above.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The key and the vector come only from the caller, and a key of unsupported size makes Node throw instead of being padded or truncated.
+   * @evidence contracts/common.md#meaningful-documentation The parameters and the return value are documented, and the namespace comment states the byte-length rule for the key.
    */
   export function encrypt(data: string, key: string, iv: string): string {
-    const bytes: number = key.length * 8;
+    const bytes: number = Buffer.byteLength(key, "utf8") * 8;
     const cipher = crypto.createCipheriv(`AES-${bytes}-CBC`, key, iv);
     return cipher.update(data, "utf8", "base64") + cipher.final("base64");
   }
@@ -32,9 +45,13 @@ export namespace AesPkcs5 {
    * @param key Key value of the decryption.
    * @param iv Initializer Vector for the decryption
    * @returns Decrypted data.
+   * @evidence contracts/common.md#principled-implementation The base64 text is decrypted in CBC mode with the key and the initializer vector, and the update and final outputs are concatenated as UTF-8, so `decrypt(encrypt(x))` returns `x`; wrong keys or corrupted text make the final block check throw rather than return garbage silently in the usual case, although CBC without a tag cannot detect every alteration.
+   * @evidence contracts/common.md#clear-and-simple-design A single expression over one decipher object, mirroring `encrypt`.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It uses the platform's decipher and does not catch its errors, so a padding or key failure reaches the caller.
+   * @evidence contracts/common.md#meaningful-documentation The parameters and the return value are documented, and the namespace comment states the byte-length rule for the key.
    */
   export function decrypt(data: string, key: string, iv: string): string {
-    const bytes: number = key.length * 8;
+    const bytes: number = Buffer.byteLength(key, "utf8") * 8;
     const decipher = crypto.createDecipheriv(`AES-${bytes}-CBC`, key, iv);
     return decipher.update(data, "base64", "utf8") + decipher.final("utf8");
   }

package/src/EncryptedFetcher.ts

@@ -20,6 +20,10 @@ import { FetcherBase } from "./internal/FetcherBase";
  * {@link PlainFetcher} class would be used instead.
  *
  * @author Jeongho Nam - https://github.com/samchon
+ * @evidence contracts/common.md#principled-implementation A per-call codec encrypts the request body only when the route declares its request encrypted and decrypts the response body only when the route declares its response encrypted; the password is read from the connection, directly or through a closure that receives the headers, the body text, and the direction, where the body is the serialized plain text when encoding and the received cipher text when decoding, as on the server, and the request pipeline itself is shared with `PlainFetcher`.
+ * @evidence contracts/common.md#clear-and-simple-design Two public operations, `fetch` and `propagate`, share one private `codec` builder, so the encryption policy exists once and the transport lives in `FetcherBase`.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No route, header, or key is special-cased: encryption follows the route metadata that `@nestia/sdk` generates, and a missing password is a thrown error rather than a silent plain request.
+ * @evidence contracts/common.md#meaningful-documentation The namespace prose says when the generated SDK uses this fetcher instead of `PlainFetcher`.
  */
 export namespace EncryptedFetcher {
   /**
@@ -28,6 +32,10 @@ export namespace EncryptedFetcher {
    * @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 the route method to the argument list and return type that method allows; the implementation builds the codec, which throws before any request when an encrypted route has no password, and delegates to `FetcherBase.request`, which returns the body on success and throws `HttpError` otherwise.
+   * @evidence contracts/common.md#clear-and-simple-design The implementation is one delegation, and the overloads exist only for the type-level split between `HEAD`, `GET`, and the body methods.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The function gates on the route's declared encryption and adds no branch for a particular path or password.
+   * @evidence contracts/common.md#meaningful-documentation Each overload documents its parameters and return value.
    */
   export function fetch(
     connection: IConnection,
@@ -66,75 +74,91 @@ export namespace EncryptedFetcher {
     input?: Input,
     stringify?: (input: Input) => string,
   ): Promise<Output> {
-    if (
-      (route.request?.encrypted === true || route.response?.encrypted) &&
-      connection.encryption === undefined
-    )
-      throw new Error(
-        "Error on EncryptedFetcher.fetch(): the encryption password has not been configured.",
-      );
-    const closure =
-      typeof connection.encryption === "function"
-        ? (direction: "encode" | "decode") =>
-            (
-              headers: Record<string, IConnection.HeaderValue | undefined>,
-              body: string,
-            ) =>
-              (connection.encryption as IEncryptionPassword.Closure)({
-                headers,
-                body,
-                direction,
-              })
-        : () => () => connection.encryption as IEncryptionPassword;
-
-    return FetcherBase.request({
-      className: "EncryptedFetcher",
-      encode:
-        route.request?.encrypted === true
-          ? (input, headers) => {
-              const p: IEncryptionPassword = closure("encode")(headers, input);
-              return AesPkcs5.encrypt(
-                (stringify ?? JSON.stringify)(input),
-                p.key,
-                p.iv,
-              );
-            }
-          : (input) => input,
-      decode:
-        route.response?.encrypted === true
-          ? (input, headers) => {
-              const p: IEncryptionPassword = closure("decode")(headers, input);
-              const s: string = AesPkcs5.decrypt(input, p.key, p.iv);
-              return s.length ? JSON.parse(s) : s;
-            }
-          : (input) => input,
-    })(connection, route, input, stringify);
+    return FetcherBase.request(
+      codec({ method: "fetch", connection, route, stringify }),
+    )(connection, route, input, stringify);
   }
 
-  export function propagate<Output extends IPropagation<any, any>>(
+  /**
+   * Fetch function that returns every response as an {@link IPropagation},
+   * encrypting and decrypting the bodies the route declares encrypted.
+   *
+   * An HTTP failure status is returned as a failed branch instead of being
+   * thrown. A missing encryption password 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 It builds the same codec as `fetch` 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 The implementation is one delegation to the shared pipeline, and the overloads only split the argument types by method.
+   * @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,
     stringify?: (input: Input) => string,
   ): Promise<Output> {
+    return FetcherBase.propagate(
+      codec({ method: "propagate", connection, route, stringify }),
+    )(connection, route, input, stringify) as Promise<Output>;
+  }
+
+  /**
+   * Builds the body codec of one call: encrypt the request body when the route
+   * declares it encrypted, and decrypt the response body likewise.
+   *
+   * Refuses the call before any request when the route needs a password and the
+   * connection has none.
+   */
+  const codec = <Input>(props: {
+    method: "fetch" | "propagate";
+    connection: IConnection;
+    route: IFetchRoute<"DELETE" | "GET" | "HEAD" | "PATCH" | "POST" | "PUT">;
+    stringify: ((input: Input) => string) | undefined;
+  }): FetcherBase.IProps => {
+    const { connection, route, stringify } = props;
     if (
       (route.request?.encrypted === true || route.response?.encrypted) &&
       connection.encryption === undefined
     )
       throw new Error(
-        "Error on EncryptedFetcher.propagate(): the encryption password has not been configured.",
+        `Error on EncryptedFetcher.${props.method}(): the encryption password has not been configured.`,
       );
     const closure =
       typeof connection.encryption === "function"
@@ -149,18 +173,14 @@ export namespace EncryptedFetcher {
                 direction,
               })
         : () => () => connection.encryption as IEncryptionPassword;
-
-    return FetcherBase.propagate({
+    return {
       className: "EncryptedFetcher",
       encode:
         route.request?.encrypted === true
           ? (input, headers) => {
-              const p: IEncryptionPassword = closure("encode")(headers, input);
-              return AesPkcs5.encrypt(
-                (stringify ?? JSON.stringify)(input),
-                p.key,
-                p.iv,
-              );
+              const text: string = (stringify ?? JSON.stringify)(input);
+              const p: IEncryptionPassword = closure("encode")(headers, text);
+              return AesPkcs5.encrypt(text, p.key, p.iv);
             }
           : (input) => input,
       decode:
@@ -171,6 +191,6 @@ export namespace EncryptedFetcher {
               return s.length ? JSON.parse(s) : s;
             }
           : (input) => input,
-    })(connection, route, input, stringify) as Promise<Output>;
-  }
+    };
+  };
 }

package/src/FormDataInput.ts

@@ -17,12 +17,15 @@
  * array of `File` class, it converts it to an array of union type of `File` and
  * {@link FormDataInput.IFileProps} type too.
  *
- * Before | After ----------|------------------------ `boolean` | `boolean`
- * `bigint` | `bigint` `number` | `number` `string` | `string` `File` | `File \|
- * IFileProps`
+ * Atomic fields retain their original types; file fields accept either a File
+ * or the React Native file descriptor.
  *
  * @author Jeongho Nam - https://github.com/samchon
  * @template T Target object type.
+ * @evidence contracts/common.md#principled-implementation The mapped type delegates each field to a distributive value conversion, so file alternatives and file-array alternatives accept React Native descriptors even when optional or mixed with another field type. Arrays and functions at the outer body level become never because a form body is an object of named fields.
+ * @evidence contracts/common.md#clear-and-simple-design One conditional over the object type, delegating the per-value rule to `FormDataInput.Value`.
+ * @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 the React Native motive, which fields are converted, and the platform limit of descriptors.
  */
 export type FormDataInput<T extends object> =
   T extends Array<any>
@@ -30,9 +33,7 @@ export type FormDataInput<T extends object> =
     : T extends Function
       ? never
       : {
-          [P in keyof T]: T[P] extends Array<infer U>
-            ? FormDataInput.Value<U>[]
-            : FormDataInput.Value<T[P]>;
+          [P in keyof T]: FormDataInput.Value<T[P]>;
         };
 export namespace FormDataInput {
   /**
@@ -43,8 +44,18 @@ export namespace FormDataInput {
    * If the original value type is a `File` class, `Value<T>` converts it to an
    * union type of `File` and {@link IFileProps} type which is a structured data
    * for the URI file location in the React Native environment.
+   *
+   * @evidence contracts/common.md#principled-implementation Distribution examines each optional or union alternative separately; mutable arrays convert their immediate File elements, File becomes File or its descriptor, and other scalar alternatives retain their types.
+   * @evidence contracts/common.md#clear-and-simple-design One value conversion owns scalar and array handling, so the outer mapped type applies one rule to every field.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the conversion for `File` values.
    */
-  export type Value<T> = T extends File ? T | IFileProps : T;
+  export type Value<T> =
+    T extends Array<infer U>
+      ? (U extends File ? U | IFileProps : U)[]
+      : T extends File
+        ? T | IFileProps
+        : T;
 
   /**
    * Properties of a file.
@@ -53,19 +64,24 @@ export namespace FormDataInput {
    * `File` class instance in the `FormData` request.
    *
    * Just put the {@link uri URI address} of the local file system with the
-   * file's {@link name} and {@link type}. It would be casted to the `File` class
-   * instance automatically in the `FormData` request.
+   * file's {@link name} and {@link type}. React Native's FormData implementation
+   * consumes this descriptor; the fetcher does not construct a File instance.
    *
    * Note that, this `IFileProps` type works only in the React Native
    * environment. If you are developing a Web or NodeJS application, you have to
    * utilize the `File` class instance directly.
+   *
+   * @evidence contracts/common.md#principled-implementation React Native has no `File` class, so a file is described by the local URI, the file name, and the content type, which is the shape its FormData implementation accepts.
+   * @evidence contracts/common.md#clear-and-simple-design A three-field record with no behavior.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the platform limit and each field is documented.
    */
   export interface IFileProps {
     /**
      * URI address of the file.
      *
      * In the React Native, the URI address in the local file system can replace
-     * the `File` class instance. If
+     * the `File` class instance.
      *
      * @format uri
      */

package/src/IConnection.ts

@@ -5,16 +5,16 @@ import { IFetchEvent } from "./IFetchEvent";
 /**
  * Connection information.
  *
- * `IConnection` is an interface ttype who represents connection information of
- * the remote HTTP server. You can target the remote HTTP server by wring the
+ * `IConnection` is an interface type that represents connection information of
+ * the remote HTTP server. You can target the remote HTTP server by writing the
  * {@link IConnection.host} variable down. Also, you can configure special header
  * values by specializing the {@link IConnection.headers} variable.
  *
  * If the remote HTTP server encrypts or decrypts its body data through the
- * AES-128/256 algorithm, specify the {@link IConnection.encryption} with
+ * AES-128/192/256 algorithm, specify the {@link IConnection.encryption} with
  * {@link IEncryptionPassword} or {@link IEncryptionPassword.Closure} variable.
  *
- * @author Jenogho Nam - https://github.com/samchon
+ * @author Jeongho Nam - https://github.com/samchon
  * @author Seungjun We - https://github.com/SeungjunWe
  */
 export interface IConnection<
@@ -23,8 +23,11 @@ export interface IConnection<
   /** Host address of the remote HTTP server. */
   host: string;
 
-  /** Header values delivered to the remote HTTP server. */
-  headers?: Record<string, IConnection.HeaderValue> &
+  /**
+   * Header values delivered to the remote HTTP server; undefined entries are
+   * omitted.
+   */
+  headers?: Record<string, IConnection.HeaderValue | undefined> &
     IConnection.Headerify<Headers>;
 
   /**
@@ -37,7 +40,7 @@ export interface IConnection<
    * By the way, to utilize this simulation mode, SDK library must be generated
    * with {@link INestiaConfig.simulate} option, too. Open `nestia.config.ts`
    * file, and configure {@link INestiaConfig.simulate} property to be `true`.
-   * Them, newly generated SDK library would have a built-in mock-up data
+   * Then, newly generated SDK library would have a built-in mock-up data
    * generator.
    *
    * @default false
@@ -47,9 +50,17 @@ export interface IConnection<
   /**
    * Logger function.
    *
-   * This function is called when the fetch event is completed.
+   * This function is called and awaited after transport and response
+   * processing, whether they succeeded or failed. Configuration, body encoding
+   * and URL errors that occur before transport do not produce an event. Logger
+   * errors are ignored; event input and output share the caller's payload
+   * references, so a logger should treat them as read-only.
    *
    * @param event Event information of the fetch event.
+   * @evidence contracts/common.md#principled-implementation The callback receives the event from the transport finally block after completed_at is set. respond_at and status stay null without a response, and output stays undefined if body processing throws. Its rejection is ignored, but its argument includes mutable payload references and its awaiting can delay completion.
+   * @evidence contracts/common.md#clear-and-simple-design One optional callback with a single event argument.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The optional callback uses the connection's supported logging boundary; the pipeline catches its errors without replacing a transport or decoding failure.
+   * @evidence contracts/common.md#meaningful-documentation The comment states when the callback runs, which pretransport errors create no event, that it is awaited, and why shared payload references should be treated as read-only.
    */
   logger?: (event: IFetchEvent) => Promise<void>;
 
@@ -77,6 +88,15 @@ export interface IConnection<
    */
   fetch?: typeof fetch;
 }
+/**
+ * Support types of {@link IConnection}: the fetch options, the allowed header
+ * values, and the header mapping.
+ *
+ * @evidence contracts/common.md#principled-implementation The merged connection interface and namespace share one public identity for addressing, transport settings and support types. Header entries accept HeaderValue or undefined omission, while Headerify retains name-specific constraints; the HeaderValue union continues to exclude null and objects.
+ * @evidence contracts/common.md#clear-and-simple-design The interface separates addressing, header input, simulation, observation, encryption and fetch options; three supporting types organize their representations without runtime members.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It contains types only.
+ * @evidence contracts/common.md#meaningful-documentation The interface member comments explain addressing, omitted headers and optional transport settings; the logger separately documents completion, awaiting and ignored errors. Each support type has its own documentation.
+ */
 export namespace IConnection {
   /**
    * Additional options for the `fetch` function.
@@ -84,9 +104,14 @@ export namespace IConnection {
    * Almost same with {@link RequestInit} type of the {@link fetch} function, but
    * `body`, `headers` and `method` properties are omitted.
    *
-   * The reason why defining duplicated definition of {@link RequestInit} is for
-   * legacy NodeJS environments, which does not have the {@link fetch} function
-   * type.
+   * The explicit option record exposes the supported subset independently of
+   * changes to {@link RequestInit}. DOM types are still required by the
+   * connection's custom fetch and abort signal members.
+   *
+   * @evidence contracts/common.md#principled-implementation The record exposes a subset of RequestInit options while omitting body, headers and method, whose construction belongs to the route pipeline; AbortSignal and the connection's fetch member still depend on DOM declarations.
+   * @evidence contracts/common.md#clear-and-simple-design A flat option record, with each member mirroring one field of the standard request options.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type; the fetcher spreads the options into the request and then sets the method and headers itself.
+   * @evidence contracts/common.md#meaningful-documentation The comment explains the supported subset and remaining DOM type dependency, and each member documents the standard field's meaning.
    */
   export interface IOptions {
     /**
@@ -161,17 +186,20 @@ export namespace IConnection {
    * Type of allowed header values.
    *
    * Only atomic or array of atomic values are allowed.
+   *
+   * @evidence contracts/common.md#principled-implementation A header value is a string, boolean, number, or bigint, or an array of the non-string atomic types or of strings, which the request pipeline stringifies, one header line per array element.
+   * @evidence contracts/common.md#clear-and-simple-design A single union of the allowed atomic and array values.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment states that only atomic values and arrays of them are allowed.
    */
   export type HeaderValue =
     | string
     | boolean
     | number
     | bigint
-    | string
     | Array<boolean>
     | Array<number>
     | Array<bigint>
-    | Array<number>
     | Array<string>;
 
   /**
@@ -182,7 +210,7 @@ export namespace IConnection {
    *
    * Below are list of prohibited in HTTP headers.
    *
-   * 1. Value type one of {@link HeaderValue}
+   * 1. Value type is neither {@link HeaderValue} nor omitted `undefined`
    * 2. Key is "set-cookie", but value is not an Array type
    * 3. Key is one of them, but value is Array type
    *
@@ -204,12 +232,17 @@ export namespace IConnection {
    * - "retry-after"
    * - "server"
    * - "user-agent"
+   *
+   * @evidence contracts/common.md#principled-implementation Each key admits only HeaderValue or omitted undefined. Classifying the defined value domain preserves optional array set-cookie inputs; singleton headers reject any array member even in a scalar/array union. An undefined-only domain transmits nothing and stays permitted. Lowercase keys follow HTTP's case-insensitive names, and ordinary keys retain their type.
+   * @evidence contracts/common.md#clear-and-simple-design One mapped type that rejects an entry by turning it into `never`, with the rule spelled out in the comment.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment lists the prohibited cases and the singleton headers.
    */
   export type Headerify<T extends object | undefined> = {
     [P in keyof T]?: T[P] extends HeaderValue | undefined
       ? P extends string
         ? Lowercase<P> extends "set-cookie"
-          ? T[P] extends Array<HeaderValue>
+          ? Exclude<T[P], undefined> extends Array<HeaderValue>
             ? T[P] | undefined
             : never
           : Lowercase<P> extends
@@ -231,9 +264,12 @@ export namespace IConnection {
                 | "retry-after"
                 | "server"
                 | "user-agent"
-            ? T[P] extends Array<HeaderValue>
-              ? never
-              : T[P] | undefined
+            ? Extract<
+                Exclude<T[P], undefined>,
+                Array<HeaderValue>
+              > extends never
+              ? T[P] | undefined
+              : never
             : T[P] | undefined
         : never
       : never;

package/src/IEncryptionPassword.ts

@@ -4,11 +4,15 @@ import { IConnection } from "./IConnection";
  * Encryption password.
  *
  * `IEncryptionPassword` is a type of interface who represents encryption
- * password used by the {@link Fetcher} with AES-128/256 algorithm. If your
+ * password used by the {@link Fetcher} with AES-128/192/256 algorithm. If your
  * encryption password is not fixed but changes according to the input content,
  * you can utilize the {@link IEncryptionPassword.Closure} function type.
  *
  * @author Jeongho Nam - https://github.com/samchon
+ * @evidence contracts/common.md#principled-implementation A key and an initialization vector are the two inputs of AES-CBC, so the interface holds exactly them, as strings that `AesPkcs5` reads as UTF-8 bytes.
+ * @evidence contracts/common.md#clear-and-simple-design A two-field record whose namespace adds the closure form for passwords that depend on the message.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+ * @evidence contracts/common.md#meaningful-documentation The comment says what the object represents and links the closure form.
  */
 export interface IEncryptionPassword {
   /** Secret key. */
@@ -24,6 +28,11 @@ export namespace IEncryptionPassword {
    * `IEncryptionPassword.Closure` is a type of closure function who are
    * returning the {@link IEncryptionPassword} object. It would be used when your
    * encryption password be changed according to the input content.
+   *
+   * @evidence contracts/common.md#principled-implementation A call signature from the message context to a password lets a server-driven scheme choose the key from the headers, the body, and the direction of each call.
+   * @evidence contracts/common.md#clear-and-simple-design A callable interface with one signature and no members.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment states when to use it and documents the parameter and the return value.
    */
   export interface Closure {
     /**
@@ -35,7 +44,14 @@ export namespace IEncryptionPassword {
     (props: IProps): IEncryptionPassword;
   }
 
-  /** Properties for the closure. */
+  /**
+   * Properties for the closure.
+   *
+   * @evidence contracts/common.md#principled-implementation The record carries what a password closure can choose by: the request or response headers, the body text, and whether the body is being encoded or decoded.
+   * @evidence contracts/common.md#clear-and-simple-design A three-field record with no behavior.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment names it as the closure's properties; the direction values are self-descriptive.
+   */
   export interface IProps {
     headers: Record<string, IConnection.HeaderValue | undefined>;
     body: string;

package/src/IFetchEvent.ts

@@ -1,31 +1,44 @@
-// import { IConnection } from "./IConnection";
 import { IFetchRoute } from "./IFetchRoute";
 
+/**
+ * Event of one completed fetch, passed to {@link IConnection.logger}.
+ *
+ * `status` and `respond_at` are `null` when no response arrived, and
+ * `completed_at` is set after response processing or transport failure. Binary
+ * success streams are handed to the caller without reading their bytes, so this
+ * timestamp does not measure the duration of their consumption. `input` is the
+ * value the caller passed and `output` is the response data, the error body for
+ * a failed status, or `undefined` when the request threw. These values retain
+ * their original references. Errors before transport, such as encoding or URL
+ * construction failures, do not create a logged event.
+ *
+ * @evidence contracts/common.md#principled-implementation The event records the route, the request input, the observed status and output, and the three instants of the exchange, which is what a logger or a benchmark needs to compute latency and to group by endpoint.
+ * @evidence contracts/common.md#clear-and-simple-design A flat record; the two nullable members mark the states with no response.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Every value is measured by the pipeline; none is defaulted to a plausible value.
+ * @evidence contracts/common.md#meaningful-documentation The comment states the states with no response and what input and output hold.
+ */
 export interface IFetchEvent {
+  /** Metadata used to execute the request. */
   route: IFetchRoute<"DELETE" | "GET" | "HEAD" | "PATCH" | "POST" | "PUT">;
+
+  /** Route path normalized to one leading slash. */
   path: string;
+
+  /** Received HTTP status, or null when transport produced no response. */
   status: number | null;
+
+  /** Original request value; no defensive copy is made. */
   input: any;
+
+  /** Decoded payload or transferred binary stream, absent on processing error. */
   output: any;
+
+  /** Start of the transport operation, after request preparation. */
   started_at: Date;
+
+  /** Response arrival, before response body processing; null without a response. */
   respond_at: Date | null;
+
+  /** End of response processing, before the logger is awaited. */
   completed_at: Date;
 }
-// export namespace IFetchEvent {
-//   export interface IFunction {
-//     (connection: IConnection, ...args: any[]): Promise<any>;
-//     METADATA: {
-//       method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS";
-//       path: string;
-//       request: null | {
-//         type: string;
-//         encrypted: boolean;
-//       };
-//       response: null | {
-//         type: string;
-//         encrypted: boolean;
-//       };
-//     };
-//     status: null | number;
-//   }
-// }