eve-esi-types 3.1.4 → 3.1.6

package/README.md

@@ -100,6 +100,6 @@ const ret = await esiRequest.universe.get("/universe/structures/", { query: { fi
 
 ## References
 
-- [`ESI Types Utility Definitions`](./docs/esi-types-util3.md)
+- [`ESI Types Utility Definitions`](./docs/v3/esi-types-util3.md)
 
 - [`ESI Tagged Types Utility Definitions`](./docs/esi-tagged-types.md)

package/docs/v2/identify-parameters.md

@@ -0,0 +1,74 @@
+# Explanation of the `IdentifyParameters` Type
+
+`IdentifyParameters` is an advanced TypeScript utility type designed to pinpoint the required parameters for an API endpoint by combining the key properties from the entry type and any additional options. This type ensures that all required parameters are explicitly marked as required, facilitating strong type-checking for API operations.
+
+## Type Definition
+
+```typescript
+type IdentifyParameters<
+  M extends TESIEntryMethod,
+  EPx extends ESIEndpointOf<M> | string,
+  Opt extends Record<string, unknown>,
+  AdditionalParams,
+  Entry = _ESIResponseType<M, EPx> & AdditionalParams,
+  RequireKeys = Exclude<keyof (Entry & AdditionalParams), "result" | "tag" | "cachedSeconds">
+  // @ts-expect-error 
+> = RestrictKeys<Opt, RequireKeys> & Pick<Entry, RequireKeys> & AdditionalParams;
+```
+
+## Template Parameters
+
+- **`M extends TESIEntryMethod`**  
+  Specifies the HTTP method (e.g., `"get"`, `"post"`, `"delete"`, etc.) used for the API request. This allows the type system to select the appropriate endpoint and response types.
+
+- **`EPx extends ESIEndpointOf<M> | string`**  
+  Denotes the endpoint path. It can be a specific parameterized endpoint corresponding to the method or a generic endpoint represented as a string.
+
+- **`Opt extends Record<string, unknown>`**  
+  Represents the additional options provided by the user. These options are expected to be an object whose keys are strings.
+
+- **`AdditionalParams`**  
+  These are extra parameters that, when merged with the entry type, give a more comprehensive view of the API parameters.
+
+- **`Entry = _ESIResponseType<M, EPx> & AdditionalParams`**  
+  This type combines the inferred response type for the given HTTP method and endpoint with the additional parameters. It serves as the base type from which the required keys are extracted.
+
+- **`RequireKeys = Exclude<keyof (Entry & AdditionalParams), "result" | "tag" | "cachedSeconds">`**  
+  This calculates the keys that are considered required by excluding common metadata keys (`"result"`, `"tag"`, and `"cachedSeconds"`) from the combined type.
+
+## How It Works
+
+1. **Merging Types**  
+   The type first merges the API response type (`_ESIResponseType<M, EPx>`) with any additional parameters passed as `AdditionalParams` to form the composite type `Entry`.
+
+2. **Identifying Required Keys**  
+   It then computes `RequireKeys` by taking the keys of the merged type and excluding the metadata keys (`"result"`, `"tag"`, `"cachedSeconds"`). These remaining keys are treated as required parameters.
+
+3. **Restricting Additional Options**  
+   The helper type `RestrictKeys<Opt, RequireKeys>` ensures that the additional options in `Opt` are limited only to the keys identified as required. This adds an extra layer of type-safety.
+
+4. **Final Combination**  
+   Finally, the type returns the intersection:
+   - `RestrictKeys<Opt, RequireKeys>` restricts `Opt` to only the required keys.
+   - `Pick<Entry, RequireKeys>` extracts the corresponding values from the merged entry type.
+   - `AdditionalParams` is intersected in the end, ensuring that any extra provided parameters are also included.
+   
+   This results in a final type that accurately represents only the required parameters for an API endpoint.
+
+## Practical Example
+
+```typescript
+type ExampleEntry = { result: string, tag: string, cachedSeconds: number, auth: string };
+type ExampleOpt = { auth: string };
+type IdentifiedParams = IdentifyParameters<"get", "/example/endpoint", ExampleOpt, ExampleEntry>;
+// Result: { auth: string } & { auth: string }
+```
+
+In this example:
+- `ExampleEntry` includes metadata keys along with the essential key `auth`.
+- `ExampleOpt` specifies that `auth` is required.
+- `IdentifyParameters` processes these inputs and produces a type that enforces the `auth` parameter as required, ensuring accurate and reliable type-checking.
+
+---
+
+`IdentifyParameters` thus plays a crucial role in extracting and enforcing the required parameters from API definitions, merging inherent parameters with additional options into a concise, strongly-typed structure.

package/docs/v2/if-parameterized-path.md

@@ -0,0 +1,70 @@
+# Explanation of the `IfParameterizedPath` Type
+
+`IfParameterizedPath` is a conditional TypeScript utility type that checks whether a given endpoint path (`EP`) is parameterized—i.e., contains a parameterized segment enclosed in `{}`—and, if so, determines the required type for its numeric replacements. Depending on the number of parameters detected, it returns different types:
+- Returns `number` if exactly one parameter is detected.
+- Returns `[number, number]` if two parameters are detected.
+- Otherwise, it returns the fallback type `Opt` (which defaults to `never`).
+
+## Type Definition
+
+```typescript
+type IfParameterizedPath<EP extends unknown, Opt = never> = EP extends `${string}/{${string}}${string}`
+  ? PickPathParameters<EP> extends never
+      ? Opt : InferKeysLen<PickPathParameters<EP>> extends 1
+        ? number : [number, number]
+  : Opt;
+```
+
+## Template Parameters
+
+- **`EP extends unknown`**  
+  The endpoint path as a string literal. This path may contain dynamic segments (e.g., `"/users/{user_id}/posts/{post_id}"`) that need to be replaced with numerical values.
+
+- **`Opt`**  
+  The fallback type to return if `EP` is not parameterized. By default, this is set to `never`.
+
+## How It Works
+
+1. **Pattern Matching**  
+   The type checks if `EP` matches the pattern:
+   ```typescript
+   EP extends `${string}/{${string}}${string}`
+   ```
+   This verifies that `EP` includes at least one parameter wrapped in curly braces.
+
+2. **Extracting Parameters**  
+   If `EP` is parameterized, `PickPathParameters<EP>` is used to extract the dynamic segments:
+   - If `PickPathParameters<EP>` evaluates to `never` (indicating no valid parameters were found), the type returns `Opt`.
+   - Otherwise, it proceeds to the next step.
+
+3. **Determining the Number of Parameters**  
+   The type uses `InferKeysLen<PickPathParameters<EP>>` to count the number of extracted parameters:
+   - If exactly one parameter is found, it returns `number`—indicating a single numeric replacement.
+   - Otherwise (implicitly for two parameters as per the provided description), it returns `[number, number]`.
+
+4. **Fallback for Non-Parameterized Paths**  
+   If `EP` does not match the parameterized pattern, the type simply returns `Opt`.
+
+## Practical Example
+
+For an endpoint with one parameter:
+```typescript
+type SingleParam = IfParameterizedPath<"/users/{user_id}/profile">;
+// Evaluates to: number
+```
+
+For an endpoint with two parameters:
+```typescript
+type TwoParams = IfParameterizedPath<"/users/{user_id}/posts/{post_id}">;
+// Evaluates to: [number, number]
+```
+
+And for a non-parameterized endpoint:
+```typescript
+type NotParam = IfParameterizedPath<"/about">;
+// Evaluates to: never (using the default for Opt)
+```
+
+---
+
+`IfParameterizedPath` provides a precise mechanism for type-level validation of endpoint structures by determining the necessary numerical replacements for dynamic segments, ensuring robust type-checking for API endpoint definitions.

package/docs/v2/infer-esi-response-result.md

@@ -0,0 +1,44 @@
+# Explanation of the `InferESIResponseResult` Type
+
+`InferESIResponseResult` is a utility TypeScript type designed to extract the type of the `result` property from an ESI response based on a given HTTP method and endpoint. It relies on the underlying `_ESIResponseType`, which represents the full response type for the specified method and endpoint. If this inferred response type includes a `result` key, the type captures and returns its type; otherwise, it defaults to `never`.
+
+## Type Definition
+
+```typescript
+type InferESIResponseResult<
+  M extends TESIEntryMethod,
+  EPx extends ESIEndpointOf<M> | string
+> = _ESIResponseType<M, EPx> extends { result: infer U } ? U : never;
+```
+
+## Template Parameters
+
+- **`M extends TESIEntryMethod`**  
+  The HTTP method (e.g., `"get"`, `"post"`, `"delete"`, etc.) used for the request. This helps determine the proper response type from the API endpoints.
+
+- **`EPx extends ESIEndpointOf<M> | string`**  
+  The endpoint path, which can either be one of the predefined parameterized endpoints associated with the HTTP method `M` or a generic string representing an endpoint.
+
+## How It Works
+
+1. **Inferring the Response Type:**  
+   The type first evaluates `_ESIResponseType<M, EPx>`, which returns the anticipated response type for the given HTTP method and endpoint.
+
+2. **Extracting the `result` Property:**  
+   It then uses a conditional type with the `infer` keyword:
+   ```typescript
+   _ESIResponseType<M, EPx> extends { result: infer U } ? U : never;
+   ```
+   - If the response type has a `result` property, `U` is inferred as the type of that property.
+   - If there is no `result` property, the type evaluates to `never`.
+
+## Practical Example
+
+```typescript
+type Result = InferESIResponseResult<"get", "/characters/{character_id}/">;
+// The type 'Result' represents the type of the 'result' field in the response for the GET request to the specified endpoint.
+```
+
+---
+
+`InferESIResponseResult` enhances type safety by allowing developers to directly access the portion of the API response that contains the primary data of interest. This makes it easier to work with and validate the structure of responses in a strongly-typed manner.

package/docs/v2/require-these.md

@@ -0,0 +1,57 @@
+# Explanation of the `RequireThese` Type
+
+The `RequireThese` type is a utility type that takes an existing type `T` and a subset of its keys `K`, and marks those keys as **required**. The rest of the properties in `T` remain unchanged. This is especially useful when you want to enforce that certain properties are provided while leaving other properties optional or in their original state.
+
+## Type Definition
+
+```typescript
+type RequireThese<T, K extends keyof T> = {
+  [P in keyof T as P extends K ? P : never]-?: T[P];
+} & {
+  [P in keyof T as P extends K ? never : P]: T[P];
+};
+```
+
+## How It Works
+
+1. **Selecting Required Keys**  
+   The first mapped type:
+   ```typescript
+   {
+     [P in keyof T as P extends K ? P : never]-?: T[P];
+   }
+   ```
+   - Iterates over each property key `P` in `T`.
+   - Uses a conditional type `P extends K ? P : never` to filter in only the keys that are specified in `K`.
+   - The `-?` operator removes the optional modifier, ensuring that these properties are marked as required.
+
+2. **Preserving Other Keys**  
+   The second mapped type:
+   ```typescript
+   {
+     [P in keyof T as P extends K ? never : P]: T[P];
+   }
+   ```
+   - Iterates over each property key `P` in `T`.
+   - Uses a conditional type to exclude the keys in `K` (by returning `never` for them), effectively preserving only the properties not in `K` in their original form.
+
+3. **Combining the Results**  
+   The intersection (`&`) of the two mapped types results in a new type that:
+   - Contains all keys in `K` as required.
+   - Contains all keys not in `K` with their original modifiers (optional or required).
+
+## Practical Example
+
+```typescript
+type Original = { a?: number; b?: string; c: boolean };
+type RequiredA = RequireThese<Original, 'a'>;
+// Evaluates to: { a: number; b?: string; c: boolean }
+```
+
+In this example:
+- The property `a` is transformed from an optional property to a required property.
+- The properties `b` and `c` retain their original statuses, with `b` remaining optional and `c` remaining required.
+
+---
+
+`RequireThese` provides a concise way to enforce the presence of selected properties within a type, making it an effective tool for enhancing type safety in TypeScript.

package/docs/v3/esi-enhanced-function-signature.md

@@ -0,0 +1,67 @@
+# Explanation of the `TESIEnhancedRequestFunctionSignature` Type
+
+`TESIEnhancedRequestFunctionSignature` is a highly generic function signature type for performing enhanced ESI requests.  
+It extends a base request function signature by injecting a prepended parameter at the beginning of the function call,  
+thereby providing extra context or enabling pre-processing prior to executing the request.  
+
+This signature adapts to the specifics of the chosen HTTP method, endpoint configuration, inferred path parameters,  
+and additional request options—making it ideal for advanced API interactions where both flexibility and strict type-safety are required.
+
+## Generic Parameters
+
+- **`PrependParam`**: The type of the additional parameter that is injected at the beginning of the function call.
+- **`ActualOpt`**: An object representing the default options (typically extending `ESIRequestOptions`) used for the request.
+
+## Function Generic Parameters
+
+- **`Mtd`**: The ESI request method type (e.g., GET, POST, DELETE) as defined in `TESIEntryMethod`.
+- **`REP`**: The endpoint type, which can be either a version with replaced path parameters (via `ReplacePathParams`) or the raw endpoint type from `ESIEndpointOf<Mtd>`.
+- **`EPX`**: The resolved endpoint type, derived from `REP` and `Mtd`.
+- **`PPM`**: The type representing the inferred path parameters extracted from `REP` and `EPX`.
+- **`Opt`**: The type for additional request options, as deduced from the HTTP method (`Mtd`), endpoint (`EPX`), the default options (`ActualOpt`), and the inferred path parameters (`PPM`).
+- **`Ret`**: The type of the response result from the ESI request, as inferred from the method and the endpoint.
+- **`HasOpt`**: An internal flag, computed via `HasRequireParams<Mtd, EPX, PPM>`, used to determine whether the request options (`Opt`) are required (evaluating to `1`) or optional (evaluating to `0`).
+
+## Parameters
+
+- **`prependParam: PrependParam`**  
+  A prepended parameter that supplies additional context or configuration necessary for the request.
+  
+- **`method: Mtd`**  
+  The HTTP method for the request.
+
+- **`endpoint: REP`**  
+  The API endpoint, which may include path parameter replacements (as provided by `ReplacePathParams`).
+
+- **`...options: HasOpt extends 1 ? [Opt] : [Opt?]`**  
+  A rest parameter representing additional options for the request. This is required if `HasOpt` is `1` (indicating that some options are mandatory), otherwise it is optional.
+
+## Return Value
+
+- Returns a `Promise<Ret>` that resolves with the response from the ESI endpoint, where `Ret` reflects the inferred result type.
+
+## Type Definition
+
+```typescript
+type TESIEnhancedRequestFunctionSignature<
+  PrependParam extends unknown, ActualOpt extends Record<string, unknown>
+> = <
+  Mtd extends TESIEntryMethod,
+  REP extends ReplacePathParams<ESIEndpointOf<Mtd>> | ESIEndpointOf<Mtd>,
+  EPX extends ResolvedEndpoint<REP, Mtd>,
+  PPM extends InferPathParams<REP, EPX>,
+  Opt extends IdentifyParameters<Mtd, EPX, ActualOpt, PPM>,
+  Ret extends InferESIResponseResult<Mtd, EPX>,
+  HasOpt = HasRequireParams<Mtd, EPX, PPM>
+>(
+  prependParam: PrependParam,
+  method: Mtd,
+  endpoint: REP,
+  ...options: HasOpt extends 1 ? [Opt] : [Opt?]
+) => Promise<Ret>;
+```
+
+---
+
+`TESIEnhancedRequestFunctionSignature` combines dynamic type inference with advanced parameter and return type handling to support complex API interactions in a type-safe manner.  
+It ensures that extra configuration is accounted for at the start of the function call, aligning the signature with the specific needs of the API endpoint and HTTP method being used.

package/docs/v3/has-require-params.md

@@ -0,0 +1,50 @@
+# Explanation of the `HasRequireParams` Type
+
+`HasRequireParams` is a conditional TypeScript utility type designed to determine whether an API entry has any required parameters, including additional options. It does so by leveraging the `PickRequireParams` type to extract the keys from an entry type that are considered required once common metadata keys (`"result"`, `"tag"`, and `"cachedSeconds"`) have been excluded. If there remain any keys after this exclusion, it means the entry has required parameters, and the type evaluates to `1`; otherwise, it evaluates to `0`.
+
+## Type Definition
+
+```typescript
+type HasRequireParams<
+  M extends TESIEntryMethod,
+  EPx extends ESIEndpointOf<M> | string,
+  AdditionalParams,
+> = PickRequireParams<M, EPx, AdditionalParams> extends never ? 0 : 1;
+```
+
+## Template Parameters
+
+- **`M extends TESIEntryMethod`**  
+  Represents the HTTP method (like `"get"`, `"post"`, `"delete"`, etc.) for the request. This helps identify the correct set of endpoints and types associated with that method.
+
+- **`EPx extends ESIEndpointOf<M> | string`**  
+  Denotes the endpoint path. It can be a specific parameterized endpoint from a predefined set (based on the HTTP method) or a generic string.
+
+- **`AdditionalParams`**  
+  Contains any extra parameters that should be considered during the evaluation. These are merged with the entry type to form a complete set of properties before excluding the metadata keys.
+
+## How It Works
+
+1. **Extracting Required Parameters**  
+   The type starts by merging the entry type with `AdditionalParams` and then uses `PickRequireParams` to exclude common metadata keys (`"result"`, `"tag"`, and `"cachedSeconds"`). This extraction isolates the parameters that are truly required for the API call.
+
+2. **Conditional Evaluation**  
+   - If the resulting type from `PickRequireParams` is `never` (meaning there are no keys left), then `HasRequireParams` evaluates to `0`.
+   - Otherwise, if there exists at least one required parameter, it evaluates to `1`.
+
+## Practical Example
+
+```typescript
+type ExampleEntry = { result: string, tag: string, cachedSeconds: number, auth: string };
+type HasRequired = HasRequireParams<"get", "/example/endpoint", { auth: string }>;
+// Evaluates to: 1
+```
+
+In this example:
+- The `ExampleEntry` type includes metadata keys as well as an essential key `auth`.
+- After merging with `AdditionalParams` (which also includes `{ auth: string }`) and excluding the metadata keys, `auth` remains.
+- Since there is a required parameter (`auth`), `HasRequireParams` evaluates to `1`.
+
+---
+
+`HasRequireParams` provides a straightforward mechanism to check if any required parameters exist for a given API entry, assisting in enhancing type safety and clarity in API definitions.

package/docs/v3/infer-endpoint-origin.md

@@ -0,0 +1,57 @@
+# Explanation of the `InferEndpointOrigin` Type
+
+`InferEndpointOrigin` is a utility TypeScript type that deduces the original parameterized endpoint from a real endpoint string and a specified HTTP method. It does so by mapping over all possible parameterized endpoints associated with the given HTTP method, and selecting the one whose transformed version (via `ReplacePathParams`) matches the real endpoint. This technique enables you to recover the canonical endpoint structure from a concrete URL.
+
+## Type Definition
+
+```typescript
+type InferEndpointOrigin<
+  RealEP extends unknown, M extends TESIEntryMethod,
+  Endpoints extends ESIEndpointOf<M> = ESIEndpointOf<M>
+> = {
+  [EP in Endpoints]: RealEP extends ReplacePathParams<EP>
+    ? EP : never;
+}[Endpoints];
+```
+
+## Template Parameters
+
+- **`RealEP extends unknown`**  
+  The real endpoint path, e.g., `"/characters/123/fittings/456/"`, representing the concrete URL accessed in a request.
+
+- **`M extends TESIEntryMethod`**  
+  The HTTP method (such as `"get"`, `"post"`, `"delete"`, etc.) used to determine which endpoints are applicable.
+
+- **`Endpoints extends ESIEndpointOf<M> = ESIEndpointOf<M>`**  
+  The union of all possible parameterized endpoints for the given HTTP method. These endpoints generally include dynamic segments in their definition, like `"/characters/{character_id}/fittings/{fitting_id}/"`.
+
+## How It Works
+
+1. **Mapping Over Endpoints**  
+   The type creates a mapped type where it iterates over each possible endpoint (`EP`) in the `Endpoints` union:
+   ```typescript
+   RealEP extends ReplacePathParams<EP> ? EP : never;
+   ```
+   - **Condition:** It checks if the real endpoint `RealEP` is assignable to the version of `EP` produced by `ReplacePathParams` (i.e., with its dynamic segments replaced by `${number}`).
+   - **Outcome:**  
+     - If the condition holds true, it retains `EP`—indicating that this is the matching original endpoint.
+     - Otherwise, it assigns `never` for that endpoint.
+
+2. **Indexing the Mapped Type**  
+   After processing all endpoints, the type uses an index lookup `[Endpoints]` to extract the union of all endpoints that passed the conditional check (i.e., where the condition did not yield `never`). In typical usage, this results in a single matching endpoint.
+
+## Practical Example
+
+```ts
+type Original = InferEndpointOrigin<"/characters/123/fittings/456/", "delete">;
+// Evaluates to: "/characters/{character_id}/fittings/{fitting_id}/"
+```
+
+In this example:
+- The real endpoint `"/characters/123/fittings/456/"` is compared against each parameterized endpoint available for the `"delete"` method.
+- When the condition `RealEP extends ReplacePathParams<EP>` is satisfied, it indicates that the endpoint structure matches. Accordingly, the original parameterized endpoint (`EP`) is selected.
+- The final resulting type is the parameterized endpoint, `"/characters/{character_id}/fittings/{fitting_id}/"`.
+
+---
+
+`InferEndpointOrigin` thus serves as a robust mechanism to align concrete URLs with their original endpoint definitions, ensuring accurate type-checking for API route definitions.

package/docs/v3/infer-path-params.md

@@ -0,0 +1,41 @@
+# Explanation of the `InferPathParams` Type
+
+`InferPathParams` is a conditional utility TypeScript type that infers path parameters by comparing the real endpoint path (`RealEP`) with the resolved endpoint path (`EPx`). It determines the appropriate type for the path parameters based on whether the real endpoint extends the resolved endpoint.
+
+## Type Definition
+
+```typescript
+type InferPathParams<
+  RealEP extends unknown, EPx extends unknown
+> = RealEP extends EPx ? _IfNeedPathParams<EPx> : TPathParamsNever;
+```
+
+## Template Parameters
+
+- **`RealEP extends unknown`**  
+  Represents the real endpoint path, which is the original route definition provided in your API.
+
+- **`EPx extends unknown`**  
+  Represents the resolved endpoint path, which may be a transformed or standardized version of the real endpoint.
+
+## How It Works
+
+1. **Conditional Check**  
+   The type first evaluates whether `RealEP` extends `EPx`:
+   - If **true**, it indicates that the real endpoint is compatible with the resolved endpoint.
+
+2. **Path Parameter Inference**  
+   - When the condition is met, the type returns `_IfNeedPathParams<EPx>`, a helper type that likely infers and extracts the necessary path parameters embedded within `EPx`.
+   - Otherwise, it returns `TPathParamsNever`, a type signaling that no valid path parameters could be inferred or that they are not needed.
+
+## Practical Example
+
+Consider a scenario where you have:
+- A real endpoint like `"/characters/{character_id}"`.
+- A resolved endpoint that might incorporate specific formatting or type annotations.
+
+Using `InferPathParams`, if the real endpoint correctly extends the resolved endpoint, `_IfNeedPathParams` will process `EPx` to extract dynamic segments (such as converting `{character_id}` to an interpolated type). If not, it falls back to `TPathParamsNever`.
+
+---
+
+This type is instrumental in achieving type safety in API route definitions. By conditionally inferring path parameters, it ensures that only valid and necessary parameters are extracted, promoting robust type-checking and eliminating unnecessary types.

package/docs/v3/pick-require-params.md

@@ -0,0 +1,56 @@
+# Explanation of the `PickRequireParams` Type
+
+`PickRequireParams` is an advanced TypeScript utility type designed to extract the required keys from an entry type after merging it with additional parameters. It achieves this by excluding specific keys—namely, `"result"`, `"tag"`, and `"cachedSeconds"`—which are considered metadata or non-essential for defining required parameters. This type proves extremely useful when determining which parameters are needed for a particular API operation.
+
+## Type Definition
+
+```typescript
+type PickRequireParams<
+  M extends TESIEntryMethod,
+  EPx extends ESIEndpointOf<M> | string,
+  AdditionalParams,
+  Entry = _ESIResponseType<M, EPx>
+> = Exclude<keyof (Entry & AdditionalParams), "result" | "tag" | "cachedSeconds">;
+```
+
+## Template Parameters
+
+- **`M extends TESIEntryMethod`**  
+  Denotes the HTTP method (such as `"get"`, `"post"`, etc.) used for the request. This helps narrow down the endpoint and response types applicable for the method.
+
+- **`EPx extends ESIEndpointOf<M> | string`**  
+  Represents the endpoint path. It can either be a specific parameterized endpoint from a predefined collection (for the given HTTP method) or a generic string.
+
+- **`AdditionalParams`**  
+  Contains any extra parameters that need to be considered. These are merged with the entry type to facilitate a comprehensive parameter extraction.
+
+- **`Entry = _ESIResponseType<M, EPx>`**  
+  By default, this infers the response type corresponding to the HTTP method and endpoint provided. The resulting type is combined with `AdditionalParams` to determine the full set of keys available before excluding the non-required ones.
+
+## How It Works
+
+1. **Merging Types**  
+   The type starts by merging `Entry` with `AdditionalParams` using an intersection (`Entry & AdditionalParams`). This combined type gathers all properties from both sources.
+
+2. **Extracting Keys**  
+   Using `keyof` on the merged type yields a union of all property keys present in either `Entry` or `AdditionalParams`.
+
+3. **Excluding Unwanted Keys**  
+   The `Exclude` utility then removes the keys `"result"`, `"tag"`, and `"cachedSeconds"` from the union. These keys are typically reserved for metadata or caching information and are not required as input parameters.
+
+## Practical Example
+
+```typescript
+type ExampleEntry = { result: string, tag: string, cachedSeconds: number, auth: string };
+type RequiredParams = PickRequireParams<"get", "/example/endpoint", { auth: string }, ExampleEntry>;
+// Result: "auth"
+```
+
+In this example:
+- The `ExampleEntry` type contains metadata keys (`result`, `tag`, `cachedSeconds`) and an essential key `auth`.
+- After merging with `AdditionalParams` (which provides `{ auth: string }`), the `PickRequireParams` type excludes the metadata keys.
+- The final resulting type, `RequiredParams`, is `"auth"`, representing the required parameter.
+
+---
+
+`PickRequireParams` provides a powerful approach to isolating the essential parameters needed for API operations, ensuring that extraneous metadata does not interfere with type-safety and clarity in your API definitions.

package/docs/v3/replace-path-params.md

@@ -0,0 +1,60 @@
+# Explanation of the `ReplacePathParams` Type
+
+`ReplacePathParams` is a recursive TypeScript type designed to replace dynamic segments—specifically,  
+the path parameters enclosed in curly braces—in a string literal with a standardized template literal interpolation of `${number}`.  
+This is especially useful when defining API endpoints where parameters in the URL are expected to be numeric.
+
+## Type Definition
+
+```typescript
+type ReplacePathParams<T extends unknown> = T extends `${infer Start}{${infer Param}}${infer End}`
+  ? `${Start}${number}${ReplacePathParams<End>}`
+  : T;
+```
+
+### Parameters
+
+ + T extends unknown Although T is declared with the type unknown, it is intended to be a string literal representing the endpoint path.  
+   The type processes the string to find dynamic segments that need to be replaced.
+
+### How It Works
+
+1. Pattern Matching The type checks if the input string T matches the pattern:
+
+   `${infer Start}{${infer Param}}${infer End}`
+
+ + `Start`: Captures the substring leading up to the first occurrence of a path parameter.
+
+ + `{${infer Param}}`: Matches a section of the string enclosed in curly braces. The content inside the braces, which is the path parameter's name, is stored temporarily in Param.
+
+ + `End`: Captures the remaining part of the string following the matched dynamic segment.
+
+2. **Recursive Replacement** If the pattern is matched:
+
+ + The matching segment `{${infer Param}}` is replaced with `${number}`.
+
+ + The type then recursively applies itself to the remainder of the string (`End`) by calling `ReplacePathParams<End>`,  
+   ensuring that all occurrences of path parameters are replaced.
+
+3. Base Case If `T` does not contain any substring that fits the pattern (i.e., no occurrence of a dynamic segment in curly braces),  
+   the type simply evaluates to `T` without modification. This serves as the termination condition for the recursion.
+
+### Practical Example
+
+```ts
+type Example = ReplacePathParams<"/characters/{character_id}/fittings/{fitting_id}/">;
+// Evaluates to: "/characters/${number}/fittings/${number}/"
+```
+
+In this example:
+
+1. The first dynamic segment `{character_id}` is replaced with `${number}`.
+
+1. The type then recursively processes the remaining string, encountering and replacing {fitting_id} with `${number}`.
+
+1. The final resulting type is `"/characters/${number}/fittings/${number}/"`.
+
+---
+
+The `ReplacePathParams` type is a powerful tool for transforming endpoint strings into a more standardized format.  
+This is especially beneficial when type-checking API route definitions or dynamically generating strongly-typed URL strings based on certain conditions.

package/docs/v3/resolved-endpoint.md

@@ -0,0 +1,44 @@
+# Explanation of the `ResolvedEndpoint` Type
+
+`ResolvedEndpoint` is a utility TypeScript type that determines the final, "resolved" endpoint based on a given real endpoint and the specific HTTP method. It leverages the `InferEndpointOrigin` type to deduce the original parameterized endpoint from the real endpoint. If no matching parameterized endpoint is found (i.e., the inference results in `never`), it defaults back to the real endpoint.
+
+## Type Definition
+
+```typescript
+type ResolvedEndpoint<
+  RealEP extends unknown, M extends TESIEntryMethod,
+> = InferEndpointOrigin<RealEP, M> extends never ? RealEP : InferEndpointOrigin<RealEP, M>;
+```
+
+## Template Parameters
+
+- **`RealEP extends unknown`**  
+  The real endpoint path, representing the actual URL used in a request (for example, `"/characters/123/fittings/456/"`).
+
+- **`M extends TESIEntryMethod`**  
+  The HTTP method (such as `"get"`, `"post"`, `"delete"`, etc.) used for the request. This is used to narrow down which set of parameterized endpoints should be considered.
+
+## How It Works
+
+1. **Endpoint Inference**  
+   The type starts by invoking `InferEndpointOrigin<RealEP, M>`, which attempts to map the real endpoint to its original parameterized form (e.g., converting `"/characters/123/fittings/456/"` to `"/characters/{character_id}/fittings/{fitting_id}/"`).
+
+2. **Conditional Resolution**  
+   - If `InferEndpointOrigin<RealEP, M>` results in `never`, it means no matching parameterized endpoint could be inferred from the given real endpoint. In such cases, the type falls back and returns `RealEP` as is.
+   - If the inference is successful, the resolved parameterized endpoint is returned.
+
+## Practical Example
+
+```ts
+type Resolved = ResolvedEndpoint<"/characters/123/fittings/456/", "delete">;
+// Evaluates to: "/characters/{character_id}/fittings/{fitting_id}/"
+```
+
+In this example:
+- The real endpoint `"/characters/123/fittings/456/"` along with the HTTP method `"delete"` is provided.
+- `InferEndpointOrigin` successfully maps it to its original form (`"/characters/{character_id}/fittings/{fitting_id}/"`), so that becomes the resolved endpoint.
+- If the mapping had failed (i.e., if no parameterized endpoint matched), the type would have defaulted to returning the original real endpoint.
+
+---
+
+`ResolvedEndpoint` thus ensures that you get a consistent and properly parameterized endpoint format, which is crucial for maintaining type safety and clarity in API route definitions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve-esi-types",
-  "version": "3.1.4",
+  "version": "3.1.6",
   "description": "Extracted the main type of ESI. use for ESI request response types (version 2 only)",
   "main": "v2/index.d.ts",
   "scripts": {

package/v2/esi-tagged-types.d.ts

@@ -9,7 +9,7 @@
  * THIS DTS IS AUTO GENERATED, DO NOT EDIT
  * 
  * @file eve-esi-types/v2/esi-tagged-types.d.ts
- * @summary This file is auto-generated and defines version 3.1.4 of the EVE Online ESI response types.
+ * @summary This file is auto-generated and defines version 3.1.6 of the EVE Online ESI response types.
  */
 import { TESIResponseOKMap } from "./index.d.ts";
 export * from "./index.d.ts";

package/v2/index.d.ts

@@ -9,7 +9,7 @@
  * THIS DTS IS AUTO GENERATED, DO NOT EDIT
  * 
  * @file eve-esi-types/v2/index.d.ts
- * @summary This file is auto-generated and defines version 3.1.4 of the EVE Online ESI response types.
+ * @summary This file is auto-generated and defines version 3.1.6 of the EVE Online ESI response types.
  */
 import type { TESIResponseOKMap } from "./response-map.d.ts";
 export type { TESIResponseOKMap } from "./response-map.d.ts";
@@ -91,10 +91,13 @@ export declare type TESICachedSeconds<
       : never
   }[ESIEndpointOf<M>];
 }[Method];
-// declare const cacheSecGet: TESICachedSeconds<"get">;
-// declare const cache5sec: TESICachedSeconds<"put">;
-// declare const cache3600sEndpoint: TESICachedSeconds<"post", 1>;
-// TODO: 2025/3/17 How do I get rid of `pathParams` completely?
+
+/**
+ * Indicates that no path parameters are allowed.
+ *
+ * This type serves as a compile-time signal for endpoints that do not support dynamic URL segments.  
+ * By using this type, it is clear that no path parameters should be provided.
+ */
 export declare type TPathParamsNever = { /* pathParams?: never */ };
 
 // local types
@@ -143,7 +146,7 @@ export type _IfNeedPathParams<EP extends unknown> = IfParameterizedPath<EP> exte
  * 
  * @template M - The HTTP method (e.g., "get", "post").
  * @template EP - The endpoint path.
- * @deprecated 2025/3/17 12:12:33
+ * @deprecated 2025/3/17
  */
 export type __InferESIResponseResult<
   M extends TESIEntryMethod,
@@ -155,7 +158,7 @@ export type __InferESIResponseResult<
  * @template Entry - The entry type to identify parameters for.
  * @template Opt - The type of the parameters.
  * @type {Opt & Pick<Entry, Exclude<keyof Entry, "result">>}
- * @deprecated 2025/3/17 12:12:33
+ * @deprecated 2025/3/17
  */
 export type __IdentifyParameters<
   Entry, Opt,
@@ -227,6 +230,7 @@ declare global {
    * type RequiredA = RequireThese<Original, 'a'>;
    * // Result: { a: number; b?: string; c: boolean }
    * ```
+   * @see Documentation of [`RequireThese`](../docs/v2/require-these.md)
    */
   type RequireThese<T, K extends keyof T> = {
     [P in keyof T as P extends K ? P : never]-?: T[P];
@@ -303,6 +307,7 @@ declare global {
    *   otherwise optional.
    *
    * @returns {Promise<Ret>} A promise that resolves with the result type `Ret`, representing the response data from the ESI endpoint.
+   * @see Documentation of [`TESIEnhancedRequestFunctionSignature`](../docs/v3/esi-enhanced-function-signature.md)
    */
   type TESIEnhancedRequestFunctionSignature<
     PrependParam extends unknown, ActualOpt extends Record<string, unknown>
@@ -361,6 +366,7 @@ declare global {
    * type Example = ReplacePathParams<"/characters/{character_id}/fittings/{fitting_id}/">;
    * // Result: `/characters/${number}/fittings/${number}/`
    * ```
+   * @see Documentation of [`ReplacePathParams`](../docs/v3/replace-path-params.md)
    */
   type ReplacePathParams<T extends unknown> = T extends `${infer Start}{${infer Param}}${infer End}`
     ? `${Start}${number}${ReplacePathParams<End>}` : T;
@@ -378,7 +384,8 @@ declare global {
    * @returns {TPathParamsNever | _IfNeedPathParams<EPx>}
    * @see {@link _IfNeedPathParams}
    * @see {@link TPathParamsNever}
-   * @date 2025/3/17 4:32:47
+   * @see Documentation of [`InferPathParams`](../docs/v3/infer-path-params.md)
+   * @date 2025/3/17
    */
   type InferPathParams<
     RealEP extends unknown, EPx extends unknown
@@ -401,6 +408,7 @@ declare global {
    * ```
    * @see {@link ESIEndpointOf}
    * @see {@link ReplacePathParams}
+   * @see Documentation of [`InferEndpointOrigin`](../docs/v3/infer-endpoint-origin.md)
    */
   type InferEndpointOrigin<
     RealEP extends unknown, M extends TESIEntryMethod,
@@ -420,9 +428,8 @@ declare global {
    * type Resolved = ResolvedEndpoint<"/characters/123/fittings/456/", "delete">;
    * // Result: "/characters/{character_id}/fittings/{fitting_id}/"
    * ```
-   * DONE: 2025/3/17 4:12:09 Ok, works
-   * 
    * @see {@link InferEndpointOrigin}
+   * @see Documentation of [`ResolvedEndpoint`](../docs/v3/resolved-endpoint.md)
    */
   type ResolvedEndpoint<
     RealEP extends unknown, M extends TESIEntryMethod,
@@ -447,6 +454,7 @@ declare global {
    * ```
    * @see {@link ESIEndpointOf}
    * @see {@link _ESIResponseType}
+   * @see Documentation of [`PickRequireParams`](../docs/v3/pick-require-params.md)
    */
   type PickRequireParams<
     M extends TESIEntryMethod,
@@ -471,6 +479,7 @@ declare global {
    * ```
    * @see {@link ESIEndpointOf}
    * @see {@link PickRequireParams}
+   * @see Documentation of [`HasRequireParams`](../docs/v3/has-require-params.md)
    */
   type HasRequireParams<
     M extends TESIEntryMethod,
@@ -488,6 +497,7 @@ declare global {
    * @template Opt The type to return if `EP` is not parameterized.
    * @returns {number | [number, number] | Opt} 
    * Returns `number` if there is one parameter, `[number, number]` if there are two parameters, otherwise `Opt`.
+   * @see Documentation of [`IfParameterizedPath`](../docs/v2/if-parameterized-path.md)
    */
   type IfParameterizedPath<EP extends unknown, Opt = never> = EP extends `${string}/{${string}}${string}`
     ? PickPathParameters<EP> extends never
@@ -517,6 +527,7 @@ declare global {
    * @see {@link RequireThese}
    * @see {@link ESIEndpointOf}
    * @see {@link _ESIResponseType}
+   * @see Documentation of [`IdentifyParameters`](../docs/v2/identify-parameters.md)
    */
   //* ctt
   type IdentifyParameters<
@@ -555,6 +566,7 @@ declare global {
    * ```
    * @see {@link ESIEndpointOf}
    * @see {@link _ESIResponseType}
+   * @see Documentation of [`InferESIResponseResult`](../docs/v2/infer-esi-response-result.md)
    */
   type InferESIResponseResult<
     M extends TESIEntryMethod,
@@ -578,7 +590,8 @@ declare global {
   type TESIEntryMethod = keyof TESIResponseOKMap;
 
   /**
-   * @date 2025/3/16 21:45:50
+   * Represents endpoints using `TESIEntryMethod`.
+   * @date 2025/3/16
    */
   type ESIEndpointOf<M extends TESIEntryMethod> = keyof TESIResponseOKMap[M];
   /**

package/v2/response-map.d.ts

@@ -9,7 +9,7 @@
  * THIS DTS IS AUTO GENERATED, DO NOT EDIT
  * 
  * @file eve-esi-types/v2/response-map.d.ts
- * @summary This file is auto-generated and defines version 3.1.4 of the EVE Online ESI response types.
+ * @summary This file is auto-generated and defines version 3.1.6 of the EVE Online ESI response types.
  */
 import "./types-index.d.ts";
 

package/v2/types-index.d.ts

@@ -9,7 +9,7 @@
  * THIS DTS IS AUTO GENERATED, DO NOT EDIT
  * 
  * @file eve-esi-types/v2/types-index.d.ts
- * @summary This file is auto-generated and defines version 3.1.4 of the EVE Online ESI response types.
+ * @summary This file is auto-generated and defines version 3.1.6 of the EVE Online ESI response types.
  */
 import "./get_wars_ok.d.ts";
 import "./get_status_ok.d.ts";