eve-esi-types 1.0.0 → 2.0.0-beta

package/v2.mts

@@ -0,0 +1,316 @@
+/*!
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+  Copyright (C) 2025 jeffy-g <hirotom1107@gmail.com>
+  Released under the MIT license
+  https://opensource.org/licenses/mit-license.php
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+*/
+// - - - - - - - - - - - - - - - - - - - -
+//               imports
+// - - - - - - - - - - - - - - - - - - - -
+import type { TESIResponseOKMap } from "./v2";
+// import type { TESIResponseOKMap } from "eve-esi-types";
+
+
+// - - - - - - - - - - - - - - - - - - - -
+//           constants, types
+// - - - - - - - - - - - - - - - - - - - -
+// shorthands
+const log = console.log;
+const isArray = Array.isArray;
+/**
+ * enable/disable console.log
+ */
+let LOG = false;
+/**
+ * this always `https://esi.evetech.net`
+ */
+const BASE = "https://esi.evetech.net";
+
+
+type ESIRequestOptions = {
+    /**
+     * query params for ESI request.
+     */
+    queries?: Record<string, any>;
+    /**
+     * will need it for `POST` request etc.
+     */
+    body?: any;
+    /** 
+     * if want response data with ignore error then can be set to `true`.
+     */
+    ignoreError?: boolean;
+    /**
+     * cancel request immediately
+     */
+    cancelable?: AbortController;
+
+    /**
+     * Can be an empty object if no authentication is required.description
+     */
+    token?: string;
+
+    auth?: true;
+};
+/**
+ * @typedef {import("./v2").TESIResponseOKMap} TESIResponseOKMap
+ */
+/**
+ * @typedef ESIRequestOptions
+ * @prop {Record<string, any>} [queries] query params for ESI request.
+ * @prop {any} [body] will need it for `POST` request etc.
+ * @prop {boolean} [ignoreError]  if want response data with ignore error then can be set to `true`.
+ * @prop {AbortController} [cancelable] cancel request immediately
+ * @prop {string} [token] Can be an empty object if no authentication is required.description
+ * @prop {true=} [auth] Can be an empty object if no authentication is required.description
+ */
+
+
+// - - - - - - - - - - - - - - - - - - - -
+//        module vars, functions
+// - - - - - - - - - - - - - - - - - - - -
+/**
+ * Get the number of currently executing ESI requests
+ */
+let ax: number = 0;
+/**
+ * simple named error class.
+ */
+class ESIRequesError extends Error {}
+/**
+ * throws when x-esi-error-limit-remain header value is "0". (http status: 420)
+ */
+class ESIErrorLimitReachedError extends Error {
+    constructor() {
+        super("Cannot continue ESI request because 'x-esi-error-limit-remain' is zero!");
+    }
+    valueOf(): number {
+        return 420;
+    }
+}
+/**
+ * fetch the extra pages
+ * 
+ *   + if the `x-pages` header property ware more than 1
+ * 
+ * @param {string} endpointUrl
+ * @param {RequestInit} rqopt request options
+ * @param {Record<string, any>} qs queries
+ * @param {number} pc pageCount
+ */
+const fetchP = async <T extends any>(endpointUrl: string, rqopt: RequestInit, qs: Record<string, any>, pc: number) => {
+    const rqs: Promise<T>[] = [];
+    const rqp = new URLSearchParams(qs);
+    for (let i = 2; i <= pc; ) {
+        rqp.set("page", (i++) + "");
+        ax++;
+        rqs.push(
+            fetch(`${endpointUrl}?${rqp + ""}`, rqopt).then(
+                res => res.json()
+            ).catch(reason => {
+                console.warn(reason);
+                return [] as T;
+            }).finally(() => {
+                ax--;
+            })
+        );
+    }
+    return Promise.all(rqs).then(jsons => {
+        // DEVNOTE: let check the page 2, type is array?
+        if (isArray(jsons[0])) {
+            let combined: any[] = [];
+            for (let i = 0, end = jsons.length; i < end;) {
+                combined = combined.concat(jsons[i++]);
+            }
+            return combined as T;
+        }
+
+        LOG && log("> > > pages result are object < < < --", jsons);
+        return null;
+    });
+};
+
+/** ### replace (C)urly (B)races (T)oken
+ * 
+ * @example
+ * "/characters/{character_id}/skills"
+ * // ->
+ * "/characters/<char.character_id>/skills"
+ *
+ * @param {string} endpoint e.g - "/characters/{character_id}/"
+ * @param {number[]} ids
+ * @returns fragment of qualified endpoint uri or null.
+ */
+const replaceCbt = (endpoint: string, ids: number[]) => {
+    const re = /{([\w]+)}/g;
+    /** @type {RegExpExecArray?} */
+    let m: RegExpExecArray | null;
+    let idx = 0
+    while (m = re.exec(endpoint)) {
+        endpoint = endpoint.replace(m[0], ids[idx++] + "");
+    }
+    return endpoint;
+};
+/**
+ * 
+ * @param {string} endp this means endpoint url fragment like `/characters/{character_id}/` or `/characters/{character_id}/agents_research/`
+ *   + The version parameter can be omitted by using `<version>/<endpoint>`
+ */
+const curl = (endp: string) => {
+    endp = endp.replace(/^\/+|\/+$/g, "");
+    return `${BASE}/latest/${endp}/`;
+};
+
+
+// - - - - - - - - - - - - - - - - - - - -
+//            main functions
+// - - - - - - - - - - - - - - - - - - - -
+// It should complete correctly.
+async function getEVEStatus() {
+    try {
+        const ok = await fire("get", "/characters/{character_id}/ship/", 994562, { auth: true, token: "<accessToken of 994562>" });
+    } 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 {IdentifyParameters<TESIResponseOKMap[M][EP] & { result: any }, ESIRequestOptions>} Opt
+ * @template {TESIResponseOKMap[M][EP] extends { result: infer U } ? U : never} R
+ * 
+ * @param {M} mthd
+ * @param {EP} endp - The endpoint to request.
+ * @param {number | number[] | Opt} [pathParams] - Optional path parameters.
+ * @param {Opt} [opt] - default is empty object {}. `body` is json string
+ * @returns {Promise<R>} - The response from the endpoint.
+ * @throws
+ * @async
+ */
+export async function fire<
+    M extends TESIEntryMethod,
+    EP extends keyof TESIResponseOKMap[M],
+    Opt extends IdentifyParameters<TESIResponseOKMap[M][EP] & { result: any }, ESIRequestOptions>,
+    R extends TESIResponseOKMap[M][EP] extends { result: infer U } ? U : never
+>(
+    mthd: M, endp: EP, pathParams?: number | number[] | Opt,
+    opt?: Opt
+): Promise<R> {
+
+    if (typeof pathParams === "number") {
+        pathParams = /** @type {number[]} */([pathParams]);
+    }
+    if (isArray(pathParams)) {
+        // @ts-ignore actualy endp is string
+        endp = replaceCbt(endp, pathParams) as EP;
+    }
+    if (!opt) {
+        // When only options are provided
+        opt = /** @type {Opt} */(pathParams) as Opt || opt || {};
+    }
+
+    /** @type {RequestInit} */
+    const rqopt: RequestInit = {
+        method: mthd,
+        mode: "cors",
+        cache: "no-cache",
+        signal: opt.cancelable?.signal,
+        headers: {}
+    };
+    const qss: Record<string, string> = {
+        // language: "en",
+    };
+
+    if (opt.queries) {
+        // Object.assign(queries, options.queries); Object.assign is too slow
+        const oqs = opt.queries;
+        for (const k of Object.keys(oqs)) {
+            qss[k] = oqs[k] as string;
+        }
+    }
+    // DEVNOTE: when datasource is not empty string. (e.g - "singularity"
+    // in this case must specify datasource.
+    // disabled since `REMOVING DATASOURCE SINGULARITY`
+    // if (opt.datasource === "singularity") {
+    //     opt.datasource = "tranquility";
+    // }
+    if (opt.auth) {
+        // @ts-ignore The header is indeed an object
+        (rqopt.headers as any).authorization = `Bearer ${opt.token}`;
+    }
+    if (opt.body) { // means "POST" method etc
+        // @ts-ignore The header is indeed an object
+        (rqopt.headers as any)["content-type"] = "application/json";
+        rqopt.body = JSON.stringify(opt.body);
+    }
+
+    // @ts-ignore actualy endp is string
+    const endpointUrl = curl(endp);
+    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;
+        if (!res.ok && !opt.ignoreError) {
+            if (stat === 420) {
+                opt.cancelable && opt.cancelable.abort();
+                throw new ESIErrorLimitReachedError();
+            } else {
+                // console.log(res);
+                throw new ESIRequesError(`${res.statusText} (status=${stat})`);
+            }
+        } else {
+            // DEVNOTE: - 204 No Content
+            if (stat === 204) {
+                // this result is empty, decided to return status code.
+                return /** @type {R} */({ status: stat }) as unknown as R;
+            }
+
+            /** @type {R} */
+            const data: R = await res.json();
+            if (opt.ignoreError) {
+                // meaning `forceJson`?
+                return data;
+            }
+            // - - - - x-pages response.
+            // +undefined is NaN
+            // @ts-ignore 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<R>(endpointUrl, rqopt, qss, pc);
+                // finally, decide product data.
+                if (isArray(data) && isArray(remData)) {
+                    // DEVNOTE: 2019/7/23 15:01:48 - types
+                    return /** @type {R} */(data.concat(remData)) as unknown as R;
+                } else {
+                    // @ts-ignore TODO: fix type
+                    remData && Object.assign(data, remData);
+                }
+            }
+
+            return data;
+        }
+
+    } catch (e) {
+        // @ts-ignore actualy endp is string
+        throw new ESIRequesError(`message: ${(e as Error).message}, endpoint=${endp}`);
+    }
+}
+
+// node v2.mjs
+getEVEStatus().then(eveStatus => console.log(eveStatus));
+// {
+//     "players": 16503,
+//     "server_version": "2794925",
+//     "start_time": "2025-01-21T11:02:34Z"
+// }