eve-esi-types 3.2.4 → 3.2.7

package/{v2 → dist/v2}/experimental-esi-types.d.ts

@@ -9,9 +9,110 @@
  * THIS DTS IS AUTO GENERATED, DO NOT EDIT
  * 
  * @file eve-esi-types/v2/experimental-esi-types.d.ts
- * @summary This file is auto-generated and defines version 3.2.4 of the EVE Online ESI response types.
+ * @summary This file is auto-generated and defines version 3.2.7 of the EVE Online ESI response types.
  */
-import type { _ESIResponseType, PickPathParameters, UnionToTuple, Split } from "./index.d.ts";
+import type {
+  Split,
+  UnionToTuple,
+  RestrictKeys,
+  _ESIResponseType,
+  ESIEntryExtraKeys,
+  PickPathParameters,
+  ExtractPathParamKeys,
+  CombineIntersection,
+} from "./index.d.ts";
+
+
+/**
+ * Resolves the final request-parameter shape and response type for an ESI endpoint,
+ * and indicates whether any parameters are actually required.
+ *
+ * @template M             The HTTP method (e.g. `"get"`, `"post"`) of the request.
+ * @template EPx           The endpoint path, constrained to `ESIEndpointOf<M>` or a string.
+ * @template Opt           A record type of user-supplied options (e.g. query/body/path params).
+ * @template PathParams    A record type representing the path-parameter properties.
+ * @template EntryWithParams
+ *   By default, the merged type of the raw ESI response payload
+ *   (`_ESIResponseType<M, EPx>`) and `PathParams`.
+ * @template RequireKeys
+ *   The keys in `EntryWithParams` that represent actual request parameters,
+ *   i.e. all keys minus the built-in ESI metadata (`result`, `tag`, `cachedSeconds`).
+ * @template FinalOpt
+ *   The flattened intersection of:
+ *     - the subset of `Opt` whose keys are in `RequireKeys`, and
+ *     - a `Pick` of `EntryWithParams` over those same keys.
+ *
+ * @example
+ * ```ts
+ * // /characters/{character_id}/attributes/
+ * type ExampleEntry = {
+ *   result: GetCharactersCharacterIdAttributesOk;
+ *   tag: "Skills";
+ *   cachedSeconds: 120;
+ *   auth: true;
+ * };
+ * type ExampleOpt  = { auth: true; token: string };
+ * type ExamplePath = { character_id: number };
+ *
+ * // Suppose _ESIResponseType<"get", "/characters/{character_id}/attributes/"> = ExampleEntry
+ * type Desc = ResolveEndpointRequest<
+ *   "get",
+ *   "/characters/{character_id}/attributes/",
+ *   ExampleOpt,
+ *   ExamplePath
+ * >;
+ * // Desc resolves to:
+ * // [
+ * //   { auth: true; token: string; character_id: number; },
+ * //   GetCharactersCharacterIdAttributesOk,
+ * //   1
+ * // ]
+ * ```
+ *
+ * @see {@link ESIEndpointOf}
+ * @see {@link _ESIResponseType}
+ */
+export type ResolveEndpointRequest<
+  M extends TESIEntryMethod,
+  EPx extends ESIEndpointOf<M> | string,
+  Opt extends Record<string, unknown>,
+  PathParams extends Record<string, unknown>,
+  EntryWithParams = _ESIResponseType<M, EPx> & PathParams,
+  RequireKeys extends keyof EntryWithParams = Exclude<keyof EntryWithParams, ESIEntryExtraKeys>,
+  FinalOpt = CombineIntersection< RestrictKeys<Opt, RequireKeys> & Pick<EntryWithParams, RequireKeys> >
+> = [
+  [RequireKeys] extends [never] ? [FinalOpt?] : [FinalOpt],
+  EntryWithParams extends { result: infer R } ? R : never,
+];
+
+
+type TESIRequestFunctionContext<
+  Mtd extends TESIEntryMethod = TESIEntryMethod,
+  REP extends ReplacePathParams<ESIEndpointOf<Mtd>> | ESIEndpointOf<Mtd> = ReplacePathParams<ESIEndpointOf<Mtd>> | ESIEndpointOf<Mtd>,
+  ActualOpt extends Record<string, unknown> = Record<string, unknown>,
+
+  EPO extends ResolvedEndpoint<Mtd, REP> = ResolvedEndpoint<Mtd, REP>,
+  PPM extends InferPathParams<REP, EPO> = InferPathParams<REP, EPO>,
+  Opt extends IdentifyParameters<Mtd, EPO, ActualOpt, PPM> = IdentifyParameters<Mtd, EPO, ActualOpt, PPM>,
+  Ret extends InferESIResponseResult<Mtd, EPO> = InferESIResponseResult<Mtd, EPO>,
+  HasOpt = HasRequireParams<Mtd, EPO, PPM>,
+> = {
+  method: Mtd; endpoint: REP;
+} & (HasOpt extends 1 ? { options: Opt } : { options?: Opt }) & {
+  result?: Ret;
+};
+
+// - - - - - - - - - - - - - - - - - - - - - - - - - -
+//           TESIRequestFunctionWithContext
+// - - - - - - - - - - - - - - - - - - - - - - - - - -
+export type TESIRequestFunctionWithContext<
+  CTX extends TESIRequestFunctionContext,
+  Mtd extends TESIEntryMethod = CTX["method"],
+  // @ts-expect-error TODO: 2025/4/24
+  REP extends ReplacePathParams<ESIEndpointOf<Mtd>> | ESIEndpointOf<Mtd> = CTX["endpoint"],
+  ActualOpt extends Record<string, unknown> = CTX["options"]
+> = (context: CTX) => Promise<NonNullable<CTX["result"]>>;
+
 
 /**
  * Infers the response result type of an ESI endpoint based on a union of HTTP method and endpoint.
@@ -19,7 +120,7 @@ import type { _ESIResponseType, PickPathParameters, UnionToTuple, Split } from "
  * This utility type takes an endpoint union (`EPU`) in the format `${TESIEntryMethod}:${ESIEndpointAll}`
  * and infers the response result type from the corresponding ESI response map.
  * 
- * @template EPU - A union of HTTP method and endpoint in the format `${TESIEntryMethod}:${ESIEndpointAll}`.
+ * @template EPU A union of HTTP method and endpoint in the format `${TESIEntryMethod}:${ESIEndpointAll}`.
  * 
  * @remarks
  * This type uses advanced TypeScript features such as template literal types and conditional types
@@ -64,10 +165,10 @@ export type InferESIResponseResultFromUnion<
  * This utility type determines which endpoints can be chained after the current endpoint (`EP`),
  * based on the response type (`BaseResut`) and the URL pattern of potential next endpoints.
  * 
- * @template M - The HTTP method type (e.g., "get", "post", etc.), which must extend `TESIEntryMethod`.
- * @template EP - The current ESI endpoint under inspection; it extends `ESIEndpointOf<M>`.
- * @template BaseResut - Defaults to `InferESIResponseResult<M, EP>`; it is the inferred response result of the endpoint.
- * @template Endpoints - Defaults to `ESIEndpointOf<M>`; represents the union of all endpoints for method `M` to be considered as potential next endpoints.
+ * @template M The HTTP method type (e.g., "get", "post", etc.), which must extend `TESIEntryMethod`.
+ * @template EP The current ESI endpoint under inspection; it extends `ESIEndpointOf<M>`.
+ * @template BaseResut Defaults to `InferESIResponseResult<M, EP>`; it is the inferred response result of the endpoint.
+ * @template Endpoints Defaults to `ESIEndpointOf<M>`; represents the union of all endpoints for method `M` to be considered as potential next endpoints.
  * 
  * @remarks
  * This type uses advanced TypeScript features such as conditional types, template literal types, and type inference
@@ -93,17 +194,28 @@ export type ResolveNextEndpoint<
     : never;
 }[Endpoints];
 
+
+export type SplitEndpointUnion<
+  S extends ESIEndpointUnions, D extends string = ":",
+  AR extends any[] = Split<S, D>
+> = AR[0] extends TESIEntryMethod
+  ? AR[1] extends Exclude<ESIEndpointOf<AR[0]>, symbol>
+    ? AR: never
+  : never;
+// // Test cases
+// type Test1 = SplitEndpointUnion<"post:/universe/ids/">;
+
 /**
  * Resolves the next applicable ESI endpoint based on a union of HTTP method and endpoint.
  * 
  * This utility type determines which endpoints can be chained after the current endpoint (`EP`),
  * based on the response type (`BaseResut`) and the URL pattern of potential next endpoints.
  * 
- * @template EPU - A union of HTTP method and endpoint in the format `${TESIEntryMethod}:${ESIEndpointAll}`.
- * @template M - The HTTP method extracted from `EPU`.
- * @template EP - The current endpoint extracted from `EPU`.
- * @template BaseResut - The inferred response result of the endpoint.
- * @template Endpoints - The union of all endpoints for the given method.
+ * @template EPU A union of HTTP method and endpoint in the format `${TESIEntryMethod}:${ESIEndpointAll}`.
+ * @template M The HTTP method extracted from `EPU`.
+ * @template EP The current endpoint extracted from `EPU`.
+ * @template BaseResut The inferred response result of the endpoint.
+ * @template Endpoints The union of all endpoints for the given method.
  * 
  * @remarks
  * This type uses advanced TypeScript features such as conditional types and template literal types
@@ -117,10 +229,8 @@ export type ResolveNextEndpoint<
  */
 export type ResolveNextEndpointFromUnion<
   EPU extends ESIEndpointUnions,
-  SplitM_EP = Split<EPU>,
-  // @ts-expect-error
+  SplitM_EP extends [TESIEntryMethod, any] = SplitEndpointUnion<EPU>,
   M extends TESIEntryMethod = SplitM_EP[0],
-  // @ts-expect-error
   EP extends Exclude<ESIEndpointOf<M>, symbol> = SplitM_EP[1],
   BaseResut extends InferESIResponseResult<M, EP> = InferESIResponseResult<M, EP>,
   Endpoints extends ESIEndpointOf<M> = ESIEndpointOf<M>,
@@ -138,9 +248,9 @@ export type ResolveNextEndpointFromUnion<
  * This utility type checks if the response type (`Entry`) of the current endpoint satisfies the requirements
  * for the next endpoint (`NextEP`), such as having the necessary path parameters.
  * 
- * @template BaseResut - The response type of the current endpoint (e.g., `number[]` or an array of objects).
- * @template NextEP - The next endpoint to validate.
- * @template Debug - Optional debug flag; if set to `1`, additional debug information is returned.
+ * @template BaseResut The response type of the current endpoint (e.g., `number[]` or an array of objects).
+ * @template NextEP The next endpoint to validate.
+ * @template Debug Optional debug flag; if set to `1`, additional debug information is returned.
  * 
  * @remarks
  * This type assumes that if the response type is `number[]`, the next endpoint is always valid. For object arrays,
@@ -165,10 +275,10 @@ export type ValidateNextEndpoint<
  * Validates whether the elements of an object array satisfy the path parameter requirements
  * for a given endpoint.
  * 
- * @template BaseResut - The response type of the current endpoint (e.g., an array of objects).
- * @template NextEP - The next endpoint to validate.
- * @template Debug - Optional debug flag; if set to `1`, additional debug information is returned.
- * @template PathParams - Defaults to `UnionToTuple<PickPathParameters<NextEP>>`; represents the path parameters of the next endpoint.
+ * @template BaseResut The response type of the current endpoint (e.g., an array of objects).
+ * @template NextEP The next endpoint to validate.
+ * @template Debug Optional debug flag; if set to `1`, additional debug information is returned.
+ * @template PathParams Defaults to `ExtractPathParamsTuple<NextEP>`; represents the path parameters of the next endpoint.
  * 
  * @remarks
  * This type assumes that if the response type is an array of objects, it checks whether the required
@@ -186,7 +296,7 @@ type ValidateEndpointParamsInArray<
   BaseResut extends unknown, // SomeType[]
   NextEP extends string,
   Debug = 0,
-  PathParams extends any[] = UnionToTuple<PickPathParameters<NextEP>>,
+  PathParams extends any[] = ExtractPathParamKeys<NextEP>,
 > = BaseResut extends (infer O)[]
   ? PathParams[1] extends keyof O ? NonNullable<O[PathParams[1]]> extends number
     ? Debug extends 1 // development
@@ -204,9 +314,9 @@ type ValidateEndpointParamsInArray<
  * // Does not validate the EP result, just infers the next endpoint to request
  * ```
  * 
- * @template M - The HTTP method to use for the request.
- * @template EP - The endpoint from which the next parameterized endpoint to request is inferred.
- * @template Endpoints - The possible endpoints for the given method.
+ * @template M The HTTP method to use for the request.
+ * @template EP The endpoint from which the next parameterized endpoint to request is inferred.
+ * @template Endpoints The possible endpoints for the given method.
  * 
  * ```ts
  * type NextEndpoint = ResolveNextEndpointLoos<"get", "/markets/groups/">;
@@ -219,7 +329,7 @@ type ValidateEndpointParamsInArray<
 export type ResolveNextEndpointLoos<
   M extends TESIEntryMethod,
   /* ctt
-  // DEVNOTE: As it turns out, the behavior of this utility type is broken unless you use the "skipLibCheck=true".
+  // DEVNOTE: By applying "skipLibCheck=true", typescript semantics error will not occur.
   EP extends ESIEndpointOf<M> = ESIEndpointOf<M>,
   Endpoints extends ESIEndpointOf<M> = ESIEndpointOf<M>,
   /*/
@@ -255,7 +365,7 @@ export type ESIEndpointUnions = {
  * if the inferred response type (`InferESIResponseResultFromUnion<EPU>`) matches the specified type `T`.
  * If it matches, the endpoint is included; otherwise, it is excluded.
  * 
- * @template T - The response type to filter endpoints by.
+ * @template T The response type to filter endpoints by.
  * 
  * @example
  * ``` ts
@@ -274,7 +384,7 @@ export type FilterEndpointUnionsByResponse<T> = {
  * `ResolveNextEndpoint2` to determine if the endpoint is valid. If valid, the endpoint
  * is included in the result; otherwise, it is excluded.
  * 
- * @template EPUs - The list of filtered endpoints to process.
+ * @template EPUs The list of filtered endpoints to process.
  * 
  * @example
  * ``` ts