eve-esi-types 2.2.0 → 2.2.4

package/v2/index.d.ts

@@ -9,7 +9,7 @@
  * THIS TSD IS AUTO GENERATED, DO NOT EDIT
  * 
  * @file eve-esi-types/v2/index.d.ts
- * @summary This file is auto-generated and defines version 2.2.0 of the EVE Online ESI response types.
+ * @summary This file is auto-generated and defines version 2.2.4 of the EVE Online ESI response types.
  */
 import "./get_alliances_ok.d.ts";
 import "./get_alliances_alliance_id_ok.d.ts";
@@ -203,12 +203,112 @@ import "./extra-types.d.ts";
  */
 type RequireThese<T, K extends keyof T> = T & Required<Pick<T, K>>;
 
+/**
+ * Represents a function that can make ESI requests with various HTTP methods.
+ *
+ * @template ActualOpt - The actual type of the options.
+ *
+ * @example
+ * ```ts
+ * // @ ts-expect-error
+ * export const request: IESIRequestFunction<ESIRequestOptions> = (method, endpoint, pathParams, opt) => {
+ * // Implementation for "get" | "post" | "put" | "delete" request
+ * };
+ * // You can easily implement "get" | "post" | "put" | "delete" requests
+ * // with code like the following:
+ * (["get", "post", "put", "delete"] as (keyof typeof request)[]).forEach((method) => {
+ *     request[method] = function (this: typeof request, endpoint, params, opt) {
+ *         return this(method, endpoint, params, opt);
+ *     } as TESIRequestFunctionEachMethod<typeof method>;
+ * });
+ * ```
+ */
+export interface IESIRequestFunction<ActualOpt>
+  extends TESIRequestFunctionSignature<ActualOpt>, TESIRequestFunctionMethods<ActualOpt> {
+}
+
+/**
+ * Represents the methods available for making ESI requests.
+ * 
+ *  + This interface is used when you already have implementation code such as  
+ *    TESIRequestFunctionSignature and you want to implement additional shorthand methods.
+ *
+ * @template ActualOpt - The actual type of the options.
+ *
+ * @example
+ * ```ts
+ * export const request: TESIRequestFunctionSignature<ESIRequestOptions> = (method, endpoint, pathParams, opt) => {
+ * // Implementation for "get" | "post" | "put" | "delete" request
+ * };
+ * // You can easily implement "get" | "post" | "put" | "delete" requests
+ * // with code like the following:
+ * const esiMethods = {} as TESIRequestFunctionMethods<ESIRequestOptions>;
+ * (["get", "post", "put", "delete"] as (keyof TESIRequestFunctionMethods)[]).forEach((method) => {
+ *     esiMethods[method] = function (endpoint, params, opt) {
+ *         return request(method, endpoint, params, opt);
+ *     } as TESIRequestFunctionEachMethod<typeof method>;
+ * });
+ * ```
+ */
+export type TESIRequestFunctionMethods<ActualOpt = {}> = {
+  [method in TESIEntryMethod]: TESIRequestFunctionEachMethod<method, ActualOpt>;
+}
+
 declare global {
 
   /**
-   * is parameterized path
+   * ### ESI request function all in one signature
+   * 
+   * TESIRequestFunctionSignature is a type that defines the signature of an ESI request function.
+   * 
+   * This function sends a request to a specified endpoint and returns a response.
+   * 
+   * @template ActualOpt - The actual type of the option.  
+   *   Required parameters inferred by typescript are merged.
+   * @template M - The HTTP method to use for the request
+   * @template EP - The Path of the ESI endpoint to send the request to
+   * @template P2 - Parameters to include in the request
+   * @template Opt - Options to include in the request  
+   *   If there is a required parameter, its type will be merged with `ActualOpt`
+   * @template R - The response type
    */
-  type IsParameterizedPath<EP, A, B> = EP extends `${string}/{${string}}/${string | ""}` ? A: B;
+  type TESIRequestFunctionSignature<ActualOpt> = <
+    M extends TESIEntryMethod,
+    EP extends keyof TESIResponseOKMap[M],
+    P2 extends IfParameterizedPath<EP, Opt>,
+    Opt extends IdentifyParameters<TESIResponseOKMap[M][EP], ActualOpt>,
+    R extends InferESIResponseResult<M, EP>
+  >(method: M, endpoint: EP, pathParams?: P2, options?: Opt) => Promise<R>;
+
+  /**
+   * Represents a function that makes an ESI request using a specific HTTP method.
+   *
+   * @template M - The HTTP method to use for the request (e.g., "get", "post").
+   * @template ActualOpt - The actual type of the options to include in the request.
+   * 
+   * @param endpoint - The path of the ESI endpoint to send the request to.
+   * @param pathParams - An optional parameter that can be a number, an array of numbers, or other parameters
+   *                     depending on whether the path is parameterized.
+   * @param options - An optional object containing additional options for the request.
+   * 
+   * @returns A Promise object containing the response data, with the type inferred based on the method and endpoint.
+   */
+  type TESIRequestFunctionEachMethod<M extends TESIEntryMethod, ActualOpt = {}> = <
+    EP extends keyof TESIResponseOKMap[M],
+    P2 extends IfParameterizedPath<EP, Opt>,
+    Opt extends IdentifyParameters<TESIResponseOKMap[M][EP], ActualOpt>,
+    R extends InferESIResponseResult<M, EP>
+  >(endpoint: EP, pathParams?: P2, options?: Opt) => Promise<R>;
+
+  // /**
+  //  * is parameterized path
+  //  */
+  // type IsParameterizedPath<EP, A, B> = EP extends `${string}/{${string}}/${string | ""}` ? A: B;
+  /**
+   * if parameterized path then specify number type, otherwise will be `Opt` type.
+   */
+  type IfParameterizedPath<EP, Opt> = EP extends `${string}/{${string}}/${string | ""}` ? number | number[]: Opt;
+
   /**
    * Identifies the required parameters for a given entry type.
    *

package/v2.d.mts

@@ -11,7 +11,7 @@ import { type ESIRequestOptions } from "./rq-util.mjs";
  * fire ESI request
  * @template {TESIEntryMethod} M
  * @template {keyof TESIResponseOKMap[M]} EP
- * @template {IsParameterizedPath<EP, number | number[], Opt>} P2
+ * @template {IfParameterizedPath<EP, Opt>} P2
  * @template {IdentifyParameters<TESIResponseOKMap[M][EP], ESIRequestOptions>} Opt
  * @template {InferESIResponseResult<M, EP>} R
  *
@@ -23,10 +23,4 @@ import { type ESIRequestOptions } from "./rq-util.mjs";
  * @throws
  * @async
  */
-export declare function fire<
-    M extends TESIEntryMethod,
-    EP extends keyof TESIResponseOKMap[M],
-    Opt extends IdentifyParameters<TESIResponseOKMap[M][EP], ESIRequestOptions>,
-    P2 extends IsParameterizedPath<EP, number | number[], Opt>,
-    R extends InferESIResponseResult<M, EP>
->(mthd: M, endp: EP, pathParams?: P2, opt?: Opt): Promise<R>;
+export declare function fire<M extends TESIEntryMethod, EP extends keyof TESIResponseOKMap[M], P2 extends IfParameterizedPath<EP, Opt>, Opt extends IdentifyParameters<TESIResponseOKMap[M][EP], ESIRequestOptions>, R extends InferESIResponseResult<M, EP>>(mthd: M, endp: EP, pathParams?: P2, opt?: Opt): Promise<R>;

package/v2.mjs

@@ -1,5 +1,5 @@
 // import type { TESIResponseOKMap } from "eve-esi-types";
-import { curl, replaceCbt, fetchP, ESIRequesError, ESIErrorLimitReachedError } from "./rq-util.mjs";
+import { curl, fetchP, replaceCbt, getSDEVersion, ESIRequesError, initOptions, isDebug, ESIErrorLimitReachedError, fireRequestsDoesNotRequireAuth } from "./rq-util.mjs";
 // - - - - - - - - - - - - - - - - - - - -
 //           constants, types
 // - - - - - - - - - - - - - - - - - - - -
@@ -9,19 +9,10 @@ const isArray = Array.isArray;
 /**
  * enable/disable console.log
  */
-let LOG = false;
+let LOG = isDebug();
 /**
  * @typedef {import("./v2").TESIResponseOKMap} TESIResponseOKMap
- */
-/**
- * @typedef {`${string}.${string}.${string}`} TAcccessToken __{Header}.{Payload}.{Signature}__
- * @typedef ESIRequestOptions
- * @prop {Record<string, any>} [query] query params for ESI request.
- * @prop {any} [body] will need it for `POST` request etc.
- * @prop {true=} [auth] Can be an empty object if no authentication is required.description
- * @prop {TAcccessToken} [token] Can be an empty object if no authentication is required.description
- * @prop {boolean} [ignoreError]  if want response data with ignore error then can be set to `true`.
- * @prop {AbortController} [cancelable] cancel request immediately
+ * @typedef {import("./rq-util.mjs").ESIRequestOptions} ESIRequestOptions
  */
 // - - - - - - - - - - - - - - - - - - - -
 //        module vars, functions
@@ -34,44 +25,11 @@ const incrementAx = (minus) => minus ? ax-- : ax++;
 // - - - - - - - - - - - - - - - - - - - -
 //            main functions
 // - - - - - - - - - - - - - - - - - - - -
-// It should complete correctly.
-async function getEVEStatus() {
-    try {
-        const ok = await fire("get", "/characters/{character_id}/ship/", 994562, { auth: true });
-        // query patameter `filter` is optional
-        await fire("get", "/universe/structures/", {
-            query: {
-            // filter: "market"
-            }
-        });
-        // in this case, "categories" and "search" is required
-        await fire("get", "/characters/{character_id}/search/", 994562, {
-            query: {
-                categories: ["agent"],
-                search: "ok"
-            },
-            auth: true
-        });
-        // in this case, "order_type" is required
-        await fire("get", "/markets/{region_id}/orders/", 994562, {
-            query: {
-                order_type: "all"
-            },
-        });
-        // TODO: want TypeScript semantics to throw an error because there is a required query parameter, but it's not possible
-        await fire("get", "/characters/{character_id}/search/");
-        console.log(ok);
-    }
-    catch (error) {
-        console.error("Failed to get character ship -", error);
-    }
-    return fire("get", "/status/");
-}
 /**
  * fire ESI request
  * @template {TESIEntryMethod} M
  * @template {keyof TESIResponseOKMap[M]} EP
- * @template {IsParameterizedPath<EP, number | number[], Opt>} P2
+ * @template {IfParameterizedPath<EP, Opt>} P2
  * @template {IdentifyParameters<TESIResponseOKMap[M][EP], ESIRequestOptions>} Opt
  * @template {InferESIResponseResult<M, EP>} R
  *
@@ -85,73 +43,42 @@ async function getEVEStatus() {
  */
 export async function fire(mthd, endp, pathParams, opt) {
     if (typeof pathParams === "number") {
-        // @ts-ignore 
+        // @ts-expect-error
         pathParams = [pathParams]; // as unknown as P2;
     }
     if (isArray(pathParams)) {
-        // @ts-ignore actualy endp is string
+        // @ts-expect-error actualy endp is string
         endp = replaceCbt(endp, pathParams);
     }
     // When only options are provided
     /** @type {Opt} */
     // @ts-ignore
-    const actualOpt = pathParams || opt || {};
-    /** @type {RequestInit} */
-    const rqopt = {
-        method: mthd,
-        mode: "cors",
-        cache: "no-cache",
-        // @ts-ignore 
-        signal: actualOpt.cancelable?.signal,
-        headers: {}
-    };
-    const qss = {
-        language: "en",
-    };
-    if (actualOpt.query) {
-        // Object.assign(queries, options.queries); Object.assign is too slow
-        const oqs = actualOpt.query;
-        for (const k of Object.keys(oqs)) {
-            qss[k] = oqs[k];
-        }
-    }
-    // DEVNOTE: when datasource is not empty string. (e.g - "singularity"
-    // in this case must specify datasource.
-    // disabled since `REMOVING DATASOURCE SINGULARITY`
-    // if (actualOpt.datasource === "singularity") {
-    //     actualOpt.datasource = "tranquility";
-    // }
-    if (actualOpt.auth) {
-        // @ts-ignore The header is indeed an object
-        rqopt.headers.authorization = `Bearer ${actualOpt.token}`;
-    }
-    if (actualOpt.body) { // means "POST" method etc
-        // @ts-ignore The header is indeed an object
-        rqopt.headers["content-type"] = "application/json";
-        rqopt.body = JSON.stringify(actualOpt.body);
-    }
-    // @ts-ignore actualy endp is string
+    const actualOpt = opt || pathParams || {};
+    const { rqopt, qss } = initOptions(mthd, actualOpt);
+    // @ts-expect-error actualy endp is string
     const endpointUrl = curl(endp);
+    const up = new URLSearchParams(qss);
+    const url = `${endpointUrl}${up.size ? `?${up}` : ""}`;
+    LOG && log(url);
     ax++;
     try {
-        // @ts-ignore A silly type error will appear, but ignore it.
-        const res = await fetch(`${endpointUrl}?${new URLSearchParams(qss) + ""}`, rqopt).finally(() => ax--);
-        const stat = res.status;
+        const res = await fetch(url, rqopt).finally(() => ax--);
+        const { status } = res;
         if (!res.ok && !actualOpt.ignoreError) {
-            if (stat === 420) {
+            if (status === 420) {
                 actualOpt.cancelable && actualOpt.cancelable.abort();
                 throw new ESIErrorLimitReachedError();
             }
             else {
                 // console.log(res);
-                throw new ESIRequesError(`${res.statusText} (status=${stat})`);
+                throw new ESIRequesError(`${res.statusText} (status=${status})`);
             }
         }
         else {
             // DEVNOTE: - 204 No Content
-            if (stat === 204) {
+            if (status === 204) {
                 // this result is empty, decided to return status code.
-                return /** @type {R} */ ({ status: stat });
+                return /** @type {R} */ ({ status });
             }
             /** @type {R} */
             const data = await res.json();
@@ -161,19 +88,19 @@ export async function fire(mthd, endp, pathParams, opt) {
             }
             // - - - - x-pages response.
             // +undefined is NaN
-            // @ts-ignore becouse +null is 0
+            // @ts-expect-error becouse +null is 0
             const pc = +res.headers.get("x-pages");
             // has remaining pages? NaN > 1 === false !isNaN(pageCount)
             if (pc > 1) {
                 LOG && log('found "x-pages" header, pages: %d', pc);
-                const remData = await fetchP(endpointUrl, rqopt, qss, pc, incrementAx);
+                const remData = await fetchP(endpointUrl, rqopt, up, pc, incrementAx);
                 // finally, decide product data.
                 if (isArray(data) && isArray(remData)) {
                     // DEVNOTE: 2019/7/23 15:01:48 - types
                     return /** @type {R} */ (data.concat(remData));
                 }
                 else {
-                    // @ts-ignore TODO: fix type
+                    // @ts-expect-error TODO: fix type
                     remData && Object.assign(data, remData);
                 }
             }
@@ -181,14 +108,24 @@ export async function fire(mthd, endp, pathParams, opt) {
         }
     }
     catch (e) {
-        // @ts-ignore actualy endp is string
+        // @ts-expect-error actualy endp is string
         throw new ESIRequesError(`message: ${e.message}, endpoint=${endp}`);
     }
 }
+// It should complete correctly.
+/**
+ * @param {TESIRequestFunctionSignature<ESIRequestOptions>} fn
+ */
+async function getEVEStatus(fn) {
+    const sdeVersion = await getSDEVersion();
+    log(`sdeVersion: ${sdeVersion}`.blue);
+    await fireRequestsDoesNotRequireAuth(fn);
+    return fn("get", "/status/");
+}
 // type following and run
 // node v2.mjs
-// or yarn test:v2
-getEVEStatus().then(eveStatus => console.log(eveStatus));
+// or yarn test
+getEVEStatus(fire).then(eveStatus => console.log(eveStatus));
 // {
 //     "players": 16503,
 //     "server_version": "2794925",