eve-esi-types 2.0.4-beta → 2.1.0

package/v2.mts

@@ -1,320 +0,0 @@
-/*!
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-  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>" });
-        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 {IdentifyParameters<TESIResponseOKMap[M][EP], ESIRequestOptions>} Opt
- * @template {InferESIResponseResult<M, EP>} 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], ESIRequestOptions>,
-    R extends InferESIResponseResult<M, EP>
->(
-    mthd: M, endp: EP, pathParams?: number | number[] | Opt,
-    opt: Opt = {} as Opt
-): Promise<R> {
-
-    if (typeof pathParams === "number") {
-        pathParams = /** @type {number[]} */([pathParams]);
-    }
-    if (isArray(pathParams)) {
-        // @ts-ignore actualy endp is string
-        endp = replaceCbt(endp as string, pathParams) as EP;
-    }
-    // When only options are provided
-    // @ts- ignore 
-    opt = /** @type {Opt} */(pathParams) as Opt || opt || /** @type {Opt} */({}) as Opt;
-
-    /** @type {RequestInit} */
-    const rqopt: RequestInit = {
-        method: mthd,
-        mode: "cors",
-        cache: "no-cache",
-        // @ts-ignore 
-        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}`);
-    }
-}
-
-// type following and run
-// node v2.mjs
-// or yarn test:v2
-getEVEStatus().then(eveStatus => console.log(eveStatus));
-// {
-//     "players": 16503,
-//     "server_version": "2794925",
-//     "start_time": "2025-01-21T11:02:34Z"
-// }