eve-esi-types 3.1.6 → 3.2.0

package/docs/esi-tagged-types.md

@@ -1,120 +0,0 @@
-# ESI Tagged Types
-
-This document provides an overview of the types defined in the `eve-esi-types/v2/esi-tagged-types.d.ts` file. These types are used to handle EVE Online ESI responses.
-
-## LCamelCase
-
-Converts a string to lower camel case.
-
-```typescript
-type LCamelCase<S extends string> = S extends `${infer P1} ${infer P2}`
-  ? `${Lowercase<P1>}${Capitalize<P2>}` : Lowercase<S>;
-```
-
-### Example
-
-```typescript
-// returns "assets"
-LCamelCase<"Assets">
-
-// returns "factionWarfare"
-LCamelCase<"Faction Warfare">
-```
-
-## InferSomethingBy
-
-Infers something by a brand.
-
-```typescript
-type InferSomethingByBrand<N = number> = N & { __enum: "InferSomethingBy" };
-type InferSomethingByMethod  = InferSomethingByBrand<0>;
-type InferSomethingByTags    = InferSomethingByBrand<1>;
-type InferSomethingBy<Tag, AsType extends InferSomethingByBrand = InferSomethingByMethod> = {
-  [M in TESIEntryMethod]: TESIResponseOKMap[M] extends Record<`/${string}/`, { tag: infer ActualTag }>
-    ? AsType extends InferSomethingByTags
-      ? ActualTag : ActualTag extends Tag
-        ? M
-      : never
-    : never;
-}[TESIEntryMethod];
-```
-
-## ESITags
-
-Maps HTTP methods to their corresponding tags.
-
-```typescript
-type ESITags = InferSomethingBy<never, InferSomethingByTags>;
-```
-
-## InferMethod
-
-Infers the HTTP method based on the provided tag.
-
-```typescript
-type InferMethod<Tag> = InferSomethingBy<Tag>;
-```
-
-## TaggedEndpointRequestFunction2
-
-Creates a function type for making requests to tagged endpoints.
-
-```typescript
-type TaggedEndpointRequestFunction2<
-  M extends TESIEntryMethod, Tag extends ESITags,
-  ActualOpt extends Record<string, unknown> = {},
-  EndPoints extends SelectEndpointByTag<Tag, M> = SelectEndpointByTag<Tag, M>,
-> = <
-    REP extends ReplacePathParams<EndPoints> | EndPoints,
-    EPX extends _InferEndpointOrigin<REP, EndPoints> extends never ? REP: _InferEndpointOrigin<REP, EndPoints>,
-    PPM extends InferPathParams<REP, EPX>,
-    Opt extends IdentifyParameters<M, EPX, ActualOpt & PPM>,
-    Ret extends InferESIResponseResult<M, EPX>,
-    HasOpt = HasRequireParams<M, EPX, PPM>,
->(endpoint: REP, ...options: HasOpt extends 1 ? [Opt] : [Opt?]) => Promise<Ret>;
-```
-
-## ESITaggedEndpointRequest2
-
-Maps tags to their corresponding endpoint request functions.
-
-```typescript
-type ESITaggedEndpointRequest2<Tag extends ESITags, ActualOpt extends Record<string, unknown> = {}> = {
-  [tag in Tag]: {
-    [method in InferMethod<Tag>]: TaggedEndpointRequestFunction2<method, tag, ActualOpt>;
-  };
-}[Tag];
-```
-
-## SelectEndpointByTag
-
-Selects an endpoint by tag and method.
-
-```typescript
-type SelectEndpointByTag<
-  Tag extends ESITags, M extends TESIEntryMethod
-> = {
-  [EP in keyof TESIResponseOKMap[M]]: TESIResponseOKMap[M][EP] extends { tag: infer ActualTag }
-    ? ActualTag extends Tag
-      ? EP : never
-    : never;
-}[keyof TESIResponseOKMap[M]];
-```
-
-## TaggedESIRequestMap2
-
-Maps lower camel case tags to their corresponding endpoint request functions.
-
-```typescript
-type TaggedESIRequestMap2<ActualOpt extends Record<string, unknown> = {}> = {
-  [tag in ESITags as LCamelCase<tag>]: ESITaggedEndpointRequest2<tag, ActualOpt>;
-};
-```
-
-## TaggedESIRequestMapPartial2
-
-Creates a partial map of lower camel case tags to their corresponding endpoint request functions.
-
-```typescript
-type TaggedESIRequestMapPartial2<Props extends LCamelCase<ESITags>> = RequireThese<Partial<TaggedESIRequestMap2>, Props>;
-```

package/docs/v2/identify-parameters.md

@@ -1,74 +0,0 @@
-# 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

@@ -1,70 +0,0 @@
-# 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

@@ -1,44 +0,0 @@
-# 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

@@ -1,57 +0,0 @@
-# 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

@@ -1,67 +0,0 @@
-# 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.