eve-esi-types 2.1.0 → 2.2.0

package/README.md

@@ -3,10 +3,36 @@ Extracted the main type of ESI. Used for ESI request response types.
 
 ## Usage
 
-> Sample code is provided -> [`esi-request.mjs`](./esi-request.mjs)
+> This package is configured to use version 2 only.
 
+  + If you need to use version 1, please refer to the following link:  
+    [eve-esi-types v1](https://github.com/jeffy-g/eve-esi-types/tree/version-1.x)
+
+
+> Sample code is provided -> [`v2.mjs`](./v2.mjs)
 
 ```shell
-$ node esi-request.mjs
+$ node v2.mjs
 ```
+## API
+
+> The following function signature allows you to benefit from `eve-esi-types`.  
+> By specifying the method (`get`, `post`, `put`, `delete`) for each `endpoint`,  
+> you can determine the result type of the ESI request, what query parameters are required,  
+> and whether OAuth authentication is necessary (`auth: true`).
+
+```ts
+// function signature
+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>;
+```
+
+
+## References
 
+- [`ESI Types Utility Definitions`](./esi-types-util.md)

package/esi-types-util.md

@@ -0,0 +1,108 @@
+<!--!
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+  Copyright (C) 2025 jeffy-g <hirotom1107@gmail.com>
+  Released under the MIT license
+  https://opensource.org/licenses/mit-license.php
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+-->
+
+## ESI Types Utility Definitions
+
+### IsParameterizedPath
+
+`IsParameterizedPath<EP, A, B>` is a type to determine if a path is parameterized. If it is, it returns `A`, otherwise it returns `B`.
+
+```typescript
+type IsParameterizedPath<EP, A, B> = EP extends `${string}/{${string}}/${string | ""}` ? A : B;
+```
+
+### IdentifyParameters
+
+`IdentifyParameters<Entry, Opt>` is a type to identify the required parameters for a given entry type.
+
+```typescript
+type IdentifyParameters<Entry, Opt> = Opt & Pick<Entry, Exclude<keyof Entry, "result">>;
+```
+
+### InferESIResponseResult
+
+`InferESIResponseResult<M extends TESIEntryMethod, EP extends keyof TESIResponseOKMap[M]>` is a type to infer the result type of an ESI response based on the method and endpoint.
+
+```typescript
+type InferESIResponseResult<
+  M extends TESIEntryMethod,
+  EP extends keyof TESIResponseOKMap[M]
+> = TESIResponseOKMap[M][EP] extends { result: infer U } ? U : never;
+```
+
+### TESIEntryMethod
+
+`TESIEntryMethod` represents the HTTP methods supported by ESI.
+
+```typescript
+type TESIEntryMethod = keyof TESIResponseOKMap;
+```
+
+### TEndPointGet
+
+`TEndPointGet` represents the endpoints for the "get" method.
+
+```typescript
+type TEndPointGet = keyof TESIResponseOKMap["get"];
+```
+
+### TEndPointPost
+
+`TEndPointPost` represents the endpoints for the "post" method.
+
+```typescript
+type TEndPointPost = keyof TESIResponseOKMap["post"];
+```
+
+### TEndPointPut
+
+`TEndPointPut` represents the endpoints for the "put" method.
+
+```typescript
+type TEndPointPut = keyof TESIResponseOKMap["put"];
+```
+
+### TEndPointDelete
+
+`TEndPointDelete` represents the endpoints for the "delete" method.
+
+```typescript
+type TEndPointDelete = keyof TESIResponseOKMap["delete"];
+```
+
+### TESIResponseGetEntry
+
+`TESIResponseGetEntry<K extends TEndPointGet>` represents the entry details for the "get" method.
+
+```typescript
+type TESIResponseGetEntry<K extends TEndPointGet> = TESIResponseOKMap["get"][K];
+```
+
+### TESIResponsePutEntry
+
+`TESIResponsePutEntry<K extends TEndPointPut>` represents the entry details for the "put" method.
+
+```typescript
+type TESIResponsePutEntry<K extends TEndPointPut> = TESIResponseOKMap["put"][K];
+```
+
+### TESIResponsePostEntry
+
+`TESIResponsePostEntry<K extends TEndPointPost>` represents the entry details for the "post" method.
+
+```typescript
+type TESIResponsePostEntry<K extends TEndPointPost> = TESIResponseOKMap["post"][K];
+```
+
+### TESIResponseDeleteEntry
+
+`TESIResponseDeleteEntry<K extends TEndPointDelete>` represents the entry details for the "delete" method.
+
+```typescript
+type TESIResponseDeleteEntry<K extends TEndPointDelete> = TESIResponseOKMap["delete"][K];
+```

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "eve-esi-types",
-  "version": "2.1.0",
-  "description": "Extracted the main type of ESI. use for ESI request response types",
-  "main": "src/index.d.ts",
+  "version": "2.2.0",
+  "description": "Extracted the main type of ESI. use for ESI request response types (version 2 only)",
+  "main": "v2/index.d.ts",
   "scripts": {
-    "test": "node esi-request.mjs",
-    "test:v2": "node v2.mjs"
+    "test": "node v2.mjs"
   },
   "repository": {
     "type": "git",
@@ -13,13 +12,14 @@
   },
   "files": [
     "v2",
-    "src",
     "v2.mjs",
+    "v2.d.mts",
+    "rq-util.mjs",
+    "rq-util.d.mts",
     "LICENSE",
-    "README.md",
+    "*.md",
     "package.json",
-    "tsconfig.json",
-    "esi-request.mjs"
+    "tsconfig.json"
   ],
   "keywords": [
     "eve",

package/rq-util.d.mts

@@ -0,0 +1,84 @@
+/*!
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+//  Copyright (C) 2025 jeffy-g <hirotom1107@gmail.com>
+//  Released under the MIT license
+//  https://opensource.org/licenses/mit-license.php
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+*/
+/**
+ * @file rq-util.d.mts
+ */
+/**
+ * this always `https://esi.evetech.net`
+ */
+export declare const BASE = "https://esi.evetech.net";
+export type Truthy = string | number | boolean;
+/**
+ * __{Header}.{Payload}.{Signature}__
+ */
+export type TAcccessToken = `${string}.${string}.${string}`;
+export type ESIRequestOptions = {
+    /**
+     * query params for ESI request.
+     */
+    query?: 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?: TAcccessToken;
+    auth?: true;
+};
+/**
+ * simple named error class.
+ */
+export declare class ESIRequesError extends Error {
+}
+/**
+ * throws when x-esi-error-limit-remain header value is "0". (http status: 420)
+ */
+export declare class ESIErrorLimitReachedError extends ESIRequesError {
+    constructor();
+    valueOf(): number;
+}
+/**
+ * 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
+ * @param {(minus?: number) => void=} increment
+ */
+export declare const fetchP: <T extends unknown>(endpointUrl: string, rqopt: RequestInit, qs: Record<string, any>, pc: number, increment?: (minus?: Truthy) => void) => Promise<T | 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.
+ */
+export declare const replaceCbt: (endpoint: string, ids: number[]) => string;
+/**
+ *
+ * @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>`
+ */
+export declare const curl: (endp: string) => string;

package/rq-util.mjs

@@ -0,0 +1,107 @@
+/*!
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+//  Copyright (C) 2025 jeffy-g <hirotom1107@gmail.com>
+//  Released under the MIT license
+//  https://opensource.org/licenses/mit-license.php
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+*/
+/**
+ * @file rq-util.d.mts
+ */
+// - - - - - - - - - - - - - - - - - - - -
+//           constants, types
+// - - - - - - - - - - - - - - - - - - - -
+// shorthands
+const log = console.log;
+const isArray = Array.isArray;
+/**
+ * enable/disable console.log
+ */
+let LOG = false;
+/**
+ * this always `https://esi.evetech.net`
+ */
+export const BASE = "https://esi.evetech.net";
+/**
+ * simple named error class.
+ */
+export class ESIRequesError extends Error {
+}
+/**
+ * throws when x-esi-error-limit-remain header value is "0". (http status: 420)
+ */
+export class ESIErrorLimitReachedError extends ESIRequesError {
+    constructor() {
+        super("Cannot continue ESI request because 'x-esi-error-limit-remain' is zero!");
+    }
+    valueOf() {
+        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
+ * @param {(minus?: number) => void=} increment
+ */
+export const fetchP = async (endpointUrl, rqopt, qs, pc, increment = () => { }) => {
+    const rqs = [];
+    const rqp = new URLSearchParams(qs);
+    for (let i = 2; i <= pc;) {
+        rqp.set("page", (i++) + "");
+        increment();
+        rqs.push(fetch(`${endpointUrl}?${rqp + ""}`, rqopt).then(res => res.json()).catch(reason => {
+            console.warn(reason);
+            return [];
+        }).finally(() => {
+            increment(1);
+        }));
+    }
+    return Promise.all(rqs).then(jsons => {
+        // DEVNOTE: let check the page 2, type is array?
+        if (isArray(jsons[0])) {
+            let combined = [];
+            for (let i = 0, end = jsons.length; i < end;) {
+                combined = combined.concat(jsons[i++]);
+            }
+            return combined;
+        }
+        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.
+ */
+export const replaceCbt = (endpoint, ids) => {
+    const re = /{([\w]+)}/g;
+    /** @type {RegExpExecArray?} */
+    let m;
+    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>`
+ */
+export const curl = (endp) => {
+    endp = endp.replace(/^\/+|\/+$/g, "");
+    return `${BASE}/latest/${endp}/`;
+};

package/tsconfig.json

@@ -3,6 +3,7 @@
   "compilerOptions": {
     "skipDefaultLibCheck": true,
     "skipLibCheck": true,
+    "declaration": true,
     "outDir": ".", 
     "target": "esnext",
     "module": "esnext",